Documentation

Documentation

    ›SDK Setup

    General

    • Getting Started
    • Use Cases
    • Setup Guide

    Tutorials

    • Java Container
    • Node.JS Container
    • Python Container
    • .NET Container
    • Ruby Container

    SDK Setup

    • Introduction
    • JVM
    • .NET
    • Python
    • Ruby
    • Node.js
    • Go
    • Deployment Examples

    Session Configuration

    • Instances Selection
    • Source Code
    • Labels

    Breakpoints

    • Introduction
    • Breakpoint Status
    • Conditional Breakpoints
    • Breakpoint Limits
    • Built-in Variables

    Organizations

    • Organizations

    ETL Controller

    • Introduction
    • Installation
    • Configuration

    Data On-Premise

    • Introduction
    • Installation
    • Configuration

    Advanced

    • Live Logger
    • Collaboration
    • Tracing Timeline
    • Keyboard Shortcuts
    • Data Redaction

    More

    • Software Versions
    • Controller and Datastore License
    Edit

    .NET SDK

    This page dives into the nitty-gritty details on installing Rookout under various configurations.
    If you encounter difficulties with deploying Rookout, this is the place to look.

    Installation

    The .NET SDK provides the ability to fetch debug data from a running application in real-time.

    It can easily be installed as a NuGet package.

    Supported Languages

    The following languages are currently supported by the .NET SDK: C#, VB.NET, and F#.

    If you use a language that is not mentioned above, please let us know at support@rookout.com.

    Setup

    Start the SDK within your application by adding the following to your main method or your application's entry point:

    C#
    VB.NET
    F#
    using Rook;
    namespace Program
    {
    class Program
    {
    static int Main(string[] args)
    {
    Rook.RookOptions options = new Rook.RookOptions()
    {
    token = "[Your Rookout Token]",
    labels = new Dictionary<string, string> { { "env", "dev" } }
    };
    Rook.API.Start(options);

    // ...
    }
    }
    }
    Imports Rook

    Module Program
    Sub Main(args As String())
    Dim opts = New RookOptions()
    opts.token = "[Your Rookout Token]"
    opts.labels = New Dictionary(Of String, String)()
    opts.labels.Add("env", "dev")
    Rook.API.Start(opts)

    //......

    End Sub
    End Module
    open System
    open Rook
    open System.Collections.Generic

    [<EntryPoint>]
    let main argv =
    let labels = new Dictionary<string, string>()
    labels.Add("env", "dev")

    let opt = Rook.RookOptions(token="[Your Rookout Token]", labels=labels)
    Rook.API.Start(opt)

    // .....

    Check out the debug information, source information, and packaging-sources sections for recommendations on how to configure the build process.

    SDK API

    start

    public static void Start(RookOptions opts)
    

    The Start method is used to initialize the SDK in the background and accepts a RookOptions object with the following attributes:

    Argument                          Environment Variable                              Default ValueDescription
    tokenROOKOUT_TOKENNoneThe Rookout token for your organization. Should be left empty if you are using a Rookout ETL Controller
    labelsROOKOUT_LABELS{}A dictionary of key:value labels for your application instances. Use k:v,k:v format for environment variables
    git_commitROOKOUT_COMMITNoneString that indicates your git commit or a branch name
    git_originROOKOUT_REMOTE_ORIGINNoneString that indicates your git remote origin
    hostROOKOUT_CONTROLLER_HOSTNoneIf you are using a Rookout ETL Controller, this is the hostname for it
    portROOKOUT_CONTROLLER_PORTNoneIf you are using a Rookout ETL Controller, this is the port for it
    proxyROOKOUT_PROXYNoneURL to proxy server
    debugROOKOUT_DEBUGFalseSet to True to increase log level to debug

    Test connectivity

    To make sure the SDK was properly installed and test your configuration (environment variables only), download and run TestConnectivity:

    • Windows .Net Framework
    • .Net Core

    Unix:

    • Core 2.x: chmod +x ./rookout_test_core_2.x.sh && ./rookout_test_core_2.x.sh
    • Core 3.x: chmod +x ./rookout_test_core_3.x.sh && ./rookout_test_core_3.x.sh

    Windows: Simply run rookout_test_core_2.x.bat or rookout_test_core_3.x.bat respectively.

    Project Requirements

    Debug type

    Rookout requires your application to be built and deployed with debug information in the form of .pdb files.

    In your project’s settings, set the “debug type” to portable like so:

    <DebugType>portable</DebugType>
    

    While other “debug types” such as full and pdbonly may work (but are not recommended), the embedded type is not supported at all.

    For further reading: https://devblogs.microsoft.com/devops/understanding-symbol-files-and-visual-studios-symbol-settings/

    Optimizations

    Disabling compiler optimizations <Optimize>false</Optimize> will further improve the debugging experience at a small cost to the application performance.

    Multi-Project Solutions

    To support multi-projects Solutions its recommended to add the following Directory.Build.props file to your Root folder:

    <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    
      <ItemGroup>
        <PackageReference Include="Rookout" Version="0.1.*" />
      </ItemGroup>
    
    </Project>
    

    Dynamic library loading

    To be able to debug libraries loaded using AppDomain.Load(Byte[], Byte[]) make sure to load those binaries into Rookout using:

    Rook.API.LoadAssembly(Assembly a, byte[] pdb, byte[] assembly)
    

    Source information

    To enable automatic source fetching, information about the source control must be specified.

    Environment Variables or Start Parameters

    Use the environment variables or start parameters as described above in the API section.

    Git Folder

    Rookout gets the source information from the .git folder if both of the following apply:

    1. The .git folder is present at any of the parent directories of where the application is running (searching up the tree).
    2. No environment variables or start parameters are set for source information.

    MSBuildGitHash Package

    Use the MSBuildGitHash package to embed the Git information to your application binary.

    Note that for this method, the git binary is required to be installed on the build machine.

    After installing the MSBuildGitHash NuGet package add the following line in the .csproj file:

        <MSBuildGitHashCommand>git config --get remote.origin.url %26%26 git rev-parse HEAD</MSBuildGitHashCommand>
    

    Supported Versions

    ImplementationVersions
    .NET Framework4.5, 4.6, 4.7, 4.8
    .NET Core2.1, 2.2, 3.0, 3.1
    .NET5.0, 6.0

    IIS support

    We currently support IIS 8.0 and above.

    If the environment you are trying to debug is not mentioned in the list above, be sure to let us know: support@rookout.com

    Serverless and PaaS deployments

    Integrating with AWS Lambda

    When integrating Rookout into an application running on AWS Lambda, you should explicitly flush the collected information once lambda execution concludes.
    Rookout provides an easy to use wrapper - wrap your code with using (Rook.API.StartLambda(options)) as in the example below:

    using Rook;
    
    namespace LambdaExample
    {
        public class Function
        {
    
            public string FunctionHandler(string input, ILambdaContext context)
            {
                Rook.RookOptions options = new Rook.RookOptions()
                {
                    labels = new Dictionary<string, string> { { "env", "lambda" } }
                };
                using (Rook.API.StartLambda(options))
                {
                    /// Your code
                    return "Hello World";
                }
            }
        }
    }
    

    On .NET Core 3 or newer, you can also use await using instead of just using.

    Note: Adding the Rookout SDK will slow down your Serverless cold-start times. Please make sure your timeout is no less than 20 seconds.

    Refer to the SDK API for the available optional options

    Packaging Sources

    To make sure you are collecting data from the source line where you have set the breakpoint, include your source files within your library.

        <EmbedAllSources>true</EmbedAllSources>
    
    ← JVMPython →
    • Installation
    • Supported Languages
    • Setup
    • SDK API
      • start
    • Test connectivity
    • Project Requirements
      • Debug type
      • Optimizations
      • Multi-Project Solutions
      • Dynamic library loading
    • Source information
      • Environment Variables or Start Parameters
      • Git Folder
      • MSBuildGitHash Package
    • Supported Versions
    • IIS support
    • Serverless and PaaS deployments
      • Integrating with AWS Lambda
    • Packaging Sources
    General

    WelcomeUse CasesSetup Guide
    Tutorials

    Java Container TutorialNode Container TutorialPython Container TutorialDotnet Container TutorialRuby Container Tutorial
    SDK Setup

    Setup IntroJvm SetupDotnet SetupPython SetupRuby SetupNode SetupGo SetupDeployment Examples
    Session Configuration

    Debug Session SetupSource ReposProjects Labels
    Breakpoints

    BreakpointsBreakpoints StatusBreakpoints ConditionalBreakpoint LimitsBuilt In Variables
    Organizations

    Organizations
    ETL Controller

    Etl Controller IntroEtl Controller InstallEtl Controller Config
    Data On-Premise

    Dop IntroDop InstallDop Config
    Advanced

    Live LoggerCollaborationsTracing TimelineKeyboard ShortcutsData Redaction
    More

    Sdk DigestsLicense
    Other

    Status
    GitHub - RookoutFacebook - RookoutTwitter - RookoutLinkedIn - Rookout