.NET

Rollbar SDK for .NET

A .NET Rollbar Client that can be used in any application built on the following .NET versions: .NET Core 2.0+, .NET Standard 2.0+, and .NET Full Framework 4.5+.

Install

Nuget Package Manager:

Install-Package Rollbar

Blocking vs Non-Blocking Use

The SDK is designed to have as little impact on the hosting system or application as possible. Normally, you want to use asynchronous logging, since it has virtually no instrumentational overhead on your application execution performance at runtime. It has a "fire and forget" approach to logging.

However, in some specific situations (such as while logging right before exiting an application), you may want to use it synchronously so that the application does not quit before the logging completes.

That is why all the logging methods of the ILogger interface imply asynchronous/non-blocking implementation. However, the ILogger interface defines the AsBlockingLogger(TimeSpan timeout) method that returns a synchronous implementation of the same ILogger. This approach allows for easier code refactoring when switching between asynchronous and synchronous uses of the logger.

Therefore, the following call will perform async logging:

RollbarLocator.RollbarInstance.Log(ErrorLevel.Error, "test message");

While this call will perform blocking/synchronous logging with a timeout of 1 second:

RollbarLocator.RollbarInstance
  .AsBlockingLogger(TimeSpan.FromSeconds(5))
  .Log(ErrorLevel.Error, "test message");

In case of a timeout, all the blocking log methods throw System.TimeoutException instead of gracefully completing the call. Therefore you might want to make all the blocking log calls within a try-catch block while catching System.TimeoutException specifically to handle a timeout case.

Basic Usage

  • Configure Rollbar with RollbarLocator.RollbarInstance.Configure(new RollbarConfig("POST_SERVER_ITEM_ACCESS_TOKEN"))

  • Send errors (asynchronously) to Rollbar with
    RollbarLocator.RollbarInstance.Error(Exception)

  • Send messages (synchronously) to Rollbar with RollbarLocator.RollbarInstance.AsBlockingLogger(TimeSpan.FromSeconds(5)).Info(string)

Upgrading to v1.0.0+ from earlier versions

In order to upgrade to v1.0.0+ from an earlier version, you should change your config from the old version

Rollbar.Init(new RollbarConfig("POST_SERVER_ITEM_ACCESS_TOKEN"));

to

const string postServerItemAccessToken = "POST_SERVER_ITEM_ACCESS_TOKEN";
RollbarLocator.RollbarInstance
	.Configure(
  	  new RollbarConfig(postServerItemAccessToken) { Environment = "proxyTest" }
    );

Additionally, anywhere in your code that you were sending error reports via Rollbar.Report(Exception) or Rollbar.Report(string) will need to be replaced with either something like RollbarLocator.RollbarInstance.Error(new Exception("trying out the TraceChain", new NullReferenceException())) or RollbarLocator.RollbarInstance.Info("Basic info log example.").

Using Rollbar.NET within Strongly Named (or Signed) Host Applications

The Rollbar.NET assembly is not strongly named (or signed). Hence, you may get either build time warnings or run time assembly loading errors, depending on the exact type of the signed hosting application and its signing related settings.

These signing related issues can be easily resolved by using StrongNamer (https://github.com/dsplaisted/strongnamer) that is available as a NuGet package. Just add StrongNamer package as a NuGet dependency to every project of your solution that also reference Rollbar.NET and the issues will be solved.

Reference

RollbarConfig

The RollbarConfig object allows you to configure the Rollbar library.

  • AccessToken
    The access token for your project, allows you access to the Rollbar API
  • Endpoint
    The Rollbar API endpoint, defaults to https://api.rollbar.com/api/1/
  • Environment
    Environment name, e.g. "production" or "development", defaults to "production"
  • Enabled
    If set to false, errors will not be sent to Rollbar, defaults to true
  • LogLevel
    The least significant error level from which to start sending the messages to Rollbar. Here is the complete list of the error levels from the least significant one to the most significant one: debug, info, warning, error, critical.
  • Transform
    Allows you to specify a transformation function to modify the payload before it is sent to Rollbar. Use this function to add any value that is in Request.cs, such as the user's IP address, query string, and URL of the request.
new RollbarConfig
{
    Transform = payload =>
    {
        payload.Data.Person = new Person
        {
            Id = 123,
            UserName = "rollbar",
            Email = "user@rollbar.com"
        };
        payload.Data.CodeVersion = "2";
        payload.Data.Request = new Request()
        {
            Url = "http://rollbar.com",
            UserIp = "192.121.222.92"
        };
    }
}
  • ProxyAddress
    A string URI which will be used as the WebClient proxy by passing to the WebProxy constructor.
  • ProxyUsername
    A string specifying web proxy's username to use (if any).
  • ProxyPassword
    A string specifying web proxy's password to use (if any).
  • CheckIgnore
    Function called before sending payload to Rollbar. Return true to stop the error from being sent to Rollbar.
  • Truncate
    Truncates the payload before sending it to Rollbar.
  • Server
    An object with the following properties: Host, Root, Branch, and CodeVersion.
  • Person
    You can set the current person data like this:
private void SetRollbarReportingUser(string id, string email, string userName)
{
  Person person = new Person(id);
  person.Email = email;
  person.UserName = userName;
  RollbarLocator.RollbarInstance.Config.Person = person;
}

and this person will be attached to all future Rollbar calls.

  • PersonDataCollectionPolicies
    Allows to explicitly specify Person's data auto-collection policy flags. Supported values are None, Username, Email. Multiple policies can be combined (they are not mutually exclusive). Note: when combined, any other value takes priority over None even if None is explicitly mentioned. Default value is None.
  • IpAddressCollectionPolicy
    Allows to explicitly specify User IP address auto-collection policy. Supported values are Collect, CollectAnonymized (a portion of the IP address is masked out), DoNotCollect. These values are mutually exclusive. Default value is Collect.
  • MaxReportsPerMinute
    The maximum reports sent to Rollbar per minute, as an integer.
  • ReportingQueueDepth
    The reporting queue depth, as an integer. The reporting queue depth can be used to limit error report bursts when connectivity to the Rollbar API server is poor.
  • ScrubFields
    Array of field names to scrub out of _POST and _SESSION. Values will be replaced with asterisks. If overriding, make sure to list all fields you want to scrub, not just fields you want to add to the default. Param names are case-sensitive when comparing against the scrub list. Default: {'passwd', 'password', 'secret', 'confirm_password', 'password_confirmation'}
var config = new RollbarConfig(rollbarAccessToken) // minimally required Rollbar configuration
{
  Environment = rollbarEnvironment,
  ScrubFields = new string[]
  { 
    "password",
    "username",
  }
};
  • ScrubWhitelistFields
    The fields mentioned in this list are guaranteed to be excluded from the ScrubFields list in cases when the lists overlap.

Caught Exceptions

To send a caught exception to Rollbar, you must call RollbarLocator.RollbarInstance.Log(). You can set an item's level when you call this function. The level can be 'Debug', 'Info', 'Warning', 'Error', or 'Critical'.

In addition, there other conveninence methods for logging messages using different error levels that are named after the levels.

RollbarLocator.RollbarInstance.Error(exception);

Logging Messages Using the Notifier

When Using the Singleton-like Instance of the Notifier

  1. Get a reference to the singleton-like instance of the Notifier by calling RollbarLocator.RollbarInstance.
  2. Configure the instance (before any attempts to use it for logging) by calling its Configure(…) method while supplying valid configuration parameters.
  3. Call any of the ILogger’s methods on the instance.
const string postServerItemAccessToken = "POST_SERVER_ITEM_ACCESS_TOKEN";

RollbarLocator.RollbarInstance
  .Configure(new RollbarConfig(postServerItemAccessToken) { Environment = "proxyTest" })
  ;

RollbarLocator.RollbarInstance
  .Info("Basic info log example.")
  .Debug("First debug log.")
  .Error(new NullReferenceException())
  .Error(new Exception("trying out the TraceChain", new NullReferenceException()))
  ;

When Using a Scoped Instance of the Notifier

  1. Get a reference to a newly created instance of the Notifier by calling the RollbarFactory.CreateNew() helper method.
  2. Properly configure the instance (before any attempts to use it for logging) by calling its Configure(…) method while supplying valid configuration parameters.
  3. Call any of the ILogger’s methods on the instance.
  4. Dispose of the Notifier instance at the end of its scope by casting it to IDisposable and calling Dispose() on the cast.

Here the scoped instance of the Notifier is disposed of with the help of the using(…){…} block:

RollbarConfig loggerConfig = new RollbarConfig(RollbarUnitTestSettings.AccessToken)
{
  Environment = RollbarUnitTestSettings.Environment,
};

using (var logger = RollbarFactory.CreateNew().Configure(loggerConfig))
{
  logger.Log(ErrorLevel.Error, "test message");
  .Info("Basic info log example.")
    .Debug("First debug log.")
    .Error(new NullReferenceException())
    .Error(new Exception("trying out the TraceChain", new NullReferenceException()))
    ;
}

Monitoring the Notifier’s Internal Events

To monitor any internal event regardless of the specific instance of the Notifier:

  1. Get a reference to the RollbarQueueController.Instance singleton.
  2. Subscribe to its InternalEvent event.
  3. Implement the event handler as you desire. As the result of this subscription, at runtime, all the Rollbar internal events generated while using any instance of the Notifier will be reported into the event handler.

To monitor internal events within any specific instance of the Notifier:

  1. Get a reference to a specific instance of the Notifier.
  2. Subscribe to its InternalEvent event.
  3. Implement the event handler as you desire. As the result of this subscription, at runtime, all the Rollbar internal events generated while using this specific instance of the Notifier will be reported into the event handler.

Below is an example using both levels of monitoring at the same time:

static void Main(string[] args)
{
  ConfigureRollbarSingleton();

  RollbarLocator.RollbarInstance
    .Info("ConsoleApp sample: Basic info log example.")
    .Debug("ConsoleApp sample: First debug log.")
    .Error(new NullReferenceException("ConsoleApp sample: null reference exception."))
    .Error(new System.Exception("ConsoleApp sample: trying out the TraceChain", new NullReferenceException()))
    ;

  System.Threading.Thread.Sleep(TimeSpan.FromSeconds(10));

}

/// <summary>
/// Configures the Rollbar singleton-like notifier.
/// </summary>
private static void ConfigureRollbarSingleton()
{
  const string rollbarAccessToken = "POST_SERVER_ITEM_ACCESS_TOKEN";
  const string rollbarEnvironment = "RollbarNetSamples";

  var config = new RollbarConfig(rollbarAccessToken) // minimally required Rollbar configuration
  {
    Environment = rollbarEnvironment,
    ScrubFields = new string[]
    {
      "pw",
      "username",
    }
  };
  RollbarLocator.RollbarInstance
    // minimally required Rollbar configuration:
    .Configure(config)
    // optional step if you would like to monitor Rollbar internal events within your application:
    .InternalEvent += OnRollbarInternalEvent
    ;

  // Optional info about reporting Rollbar user:
  SetRollbarReportingUser("007", "jbond@mi6.uk", "JBOND");
}

/// <summary>
/// Sets the rollbar reporting user.
/// </summary>
/// <param name="id">The identifier.</param>
/// <param name="email">The email.</param>
/// <param name="userName">Name of the user.</param>
private static void SetRollbarReportingUser(string id, string email, string userName)
{
  Person person = new Person(id);
  person.Email = email;
  person.UserName = userName;
  RollbarLocator.RollbarInstance.Config.Person = person;
}

/// <summary>
/// Called when rollbar internal event is detected.
/// </summary>
/// <param name="sender">The sender.</param>
/// <param name="e">The <see cref="RollbarEventArgs"/> instance containing the event data.</param>
private static void OnRollbarInternalEvent(object sender, RollbarEventArgs e)
{
  Console.WriteLine(e.TraceAsString());

  RollbarApiErrorEventArgs apiErrorEvent = e as RollbarApiErrorEventArgs;
  if (apiErrorEvent != null)
  {
    //TODO: handle/report Rollbar API communication error event...
    return;
  }
  CommunicationEventArgs commEvent = e as CommunicationEventArgs;
  if (commEvent != null)
  {
    //TODO: handle/report Rollbar API communication event...
    return;
  }
  CommunicationErrorEventArgs commErrorEvent = e as CommunicationErrorEventArgs;
  if (commErrorEvent != null)
  {
    //TODO: handle/report basic communication error while attempting to reach 
    //      Rollbar API service... 
    return;
  }
  InternalErrorEventArgs internalErrorEvent = e as InternalErrorEventArgs;
  if (internalErrorEvent != null)
  {
    //TODO: handle/report basic internal error while using the Rollbar Notifier... 
    return;
  }
}

Capturing State of Critical Objects

We introduced RollbarAssistant utility class to make it easier to capture state of critical objects at runtime. The state is captured as a dictionary where a key is a data field name (prefixed with provided object instance name/ID) and a value is the corresponding field value at the time of capture. The CaptureState(...) method captures public and private data fields of an object. The method has two overloads: one for capturing state of an instance of a non-static class and another for capturing state of a static class.

Here is an example of most common usage pattern:

try
{
  ///...
}
catch (System.Exception ex)
{
  // capture state of this instance:
  var state = RollbarAssistant.CaptureState(this, "Self"); 
  // also, capture state of some other critical object:
  state = new Dictionary<string, object>(state.Concat(RollbarAssistant.CaptureState(criticalObj, nameof(criticalObj))));
  // also, capture current state of a static type:
  state = new Dictionary<string, object>(state.Concat(RollbarAssistant.CaptureState(typeof(StaticType))));

  // report the captured states along with the caught exception:
  RollbarLocator.RollbarInstance.AsBlockingLogger(TimeSpan.FromSeconds(3)).Error(ex, state);
}

Advanced Usage

If you want more control over sending data to Rollbar, there is one interesting class to worry about: Rollbar.DTOs.Payload. The class and the classes that compose the class cannot be constructed without all mandatory arguments, and mandatory fields cannot be set. Therefore, if you can construct a payload, then it is valid for the purposes of sending to Rollbar. You can have read/write access to instance reference of this type within your own functions/actions defined as CheckIgnore, Transform, and Truncate delegates of a RollbarConfig instance.

If you would like to define you own filtering rules to disallow reports some specific payload instances, implement a CheckIgnore delegate and assign it to a proper RollbarConfig instance.

Similarly, you can implement your own Transform delegate to modify any payload to be sent. For example, by calculating your own fingerprint of an exception payload or adding extra custom attributes to any payload.

There are two other particularly interesting classes to worry about: Rollbar.DTOs.Data and Rollbar.DTOs.Body. Rollbar.DTOs.Data can be filled out as completely or incompletely as you want, except for the Environment ("debug", "production", "test", etc) and Body fields. The Body is where what you're actually posting to Rollbar lives. All the other fields on Rollbar.DTOs.Data answer contextual questions about the bug, such as "who saw this error?" (RollbarPerson), "what HTTP request data can you give me about the error (if it happened during an HTTP Request)?" (Rollbar.DTOs.Request), and "how severe was the error?" (Level). Anything you see in the Rollbar API docs can be found in Rollbar.NET.

Rollbar.DTOs.Body can be constructed one of 5 ways:

  1. With a class extending from Exception, which will automatically produce a Rollbar.DTOs.Trace object, assigning it to the Trace field of the Rollbar.DTOs.Body.
  2. With a class extending from AggregateException, which will automatically produce an array of Rollbar.DTOs.Trace objects for each inner exception, assigning it to the TraceChain field of Rollbar.DTOs.Body.
  3. With an actual array of Exception objects, which will automatically produce an array of Rollbar.DTOs.Trace objects for each exception, assigning it to the TraceChain field of RollbarBody.
  4. With a Rollbar.DTOs.Message object, which consists of a string and any additional keys you wish to send along. It will be assigned to the Message field of Rollbar.DTOs.Body.
  5. With a string, which should be formatted like an iOS crash report. This library has no way to verify if you've done this correctly, but if you pass in a string it will be wrapped in a dictionary and assigned to the "raw" key and assigned to the CrashReport field of Rollbar.DTOs.Body

None of the fields on Rollbar.DTOs.Body are updatable, and all null fields in
Rollbar.NET are left off of the final JSON payload.

Examples

Any .NET Standard (.NET Core 2.0 and above, .NET Framework 4.5 and above) compliant application that already uses .NET's TraceListener(s)

You can start quickly enjoying all the benefits of Rollbar API services if you are already actively using .NET's built-in tracing infrastructure (aka, TraceSources and TraceListeners).
And you do not even need to recompile your .NET Framework based application - just configure RollbarTraceListener within your app.config file, drop the Rollbar.dll side-by-side with the config file and restart the application, so that all your traces will be forwarded to the Rollbar API from now on. Make sure your app.config file looks similar to this example:

<?xml version="1.0" encoding="utf-8"?>
<configuration>

  <system.diagnostics>
    <trace autoflush="true" indentsize="4">
      <listeners>
        <add name="textFileListener" 
             type="System.Diagnostics.TextWriterTraceListener" 
             initializeData="TextTrace.log" 
             traceOutputOptions="ProcessId, ThreadId, Timestamp, DateTime, Callstack,LogicalOperationStack"
             />
        <add name="rollbarListener" 
             type="Rollbar.NetStandard.RollbarTraceListener,Rollbar" 
             traceOutputOptions="ProcessId, ThreadId, Timestamp, DateTime, Callstack,LogicalOperationStack" 
             rollbarAccessToken="17965fa5041749b6bf7095a190001ded" 
             rollbarEnvironment="RollbarNetSamples"
             />
        <remove name="Default"/>
      </listeners>
    </trace>
  </system.diagnostics>

  <startup> 
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2"/>
  </startup>

</configuration>

If you need more control over the Rollbar notifier's static instance that is used by the RollbarTraceListener - do not specify rollbarAccessToken and rollbarEnvironment attributes in the example above and just add Rollbar specific configuration elements/sections within the same app.config file, for example, add something like this:


  <configSections>
    <section name="rollbar" type="Rollbar.NetFramework.RollbarConfigSection, Rollbar"/>
    <section name="rollbarTelemetry" type="Rollbar.NetFramework.RollbarTelemetryConfigSection, Rollbar"/>
  </configSections>

  <rollbar
    accessToken="17965fa5041749b6bf7095a190001ded"
    environment="unit-tests"
    enabled="true"
    scrubFields="ThePassword, Secret"
    scrubWhitelistFields="ThePassword"
    logLevel="Info"
    maxReportsPerMinute="160"
    reportingQueueDepth="120"
    personDataCollectionPolicies="Username, Email"
    ipAddressCollectionPolicy="CollectAnonymized"
    />

<rollbarTelemetry
    telemetryEnabled="true"
    telemetryQueueDepth="100"
    telemetryAutoCollectionTypes="Network, Log, Error"
    telemetryAutoCollectionInterval="00:00:00.3000000"
    />

However, if the flavor .NET Standard implementation used by your application does not support app.config files you can always configure Rollbar singleton in code as well as add a RollbarTraceListener instance (that will be using the just configured Rollbar singleton) to the tracing infrastructure in code (exactly as any other TraceListener). But in this case, of cause, you will have to recompile your application.

ASP.NET Core 2

The SDK can be integrated into an ASP.NET Core 2 application on two levels:

  1. Each ASP.NET Core controllers’ method implementation could be surrounded by a try-catch block where, within the catch(…){…} block, any caught exception is passed to a common exception handling routine which in turn reports the exception via the SDK.
  2. A request processing pipeline of the application is extended with the Rollbar.NET middleware component that monitors all the inner middleware components of the pipeline for unhandled exceptions and reports them via the Rollbar.NET Notifier singleton instance and then rethrows the exceptions while wrapping them with a new Exception object.

You can check out a sample ASP.NET Core 2 based application that demonstrates a proper use of the middleware component here.

First, the singleton component needs to be properly configured. There are two approaches to doing this. If both approaches are used, the second option always overrides the first option.

Option 1 - Configure the Rollbar singleton via the app settings

Add at least the minimum required configuration parameters to the hosting application’s appsettings.json file. Any of the properties of the RollbarConfig class that has public setter can be set using this approach.

{
  "Logging": {
    "IncludeScopes": false,
    "Debug": {
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "Console": {
      "LogLevel": {
        "Default": "Warning"
      }
    }
  },

  "Rollbar": {
    "AccessToken": "POST_SERVER_ITEM_ACCESS_TOKEN",
    "Environment": "AspNetCoreMiddlewareTest"
  }
}

Option 2 - Configure the Rollbar singleton in code

Within the ConfigureServices(…) method of Startup.cs, add proper Rollbar configuration and register the Rollbar logger with the application services:

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
  ConfigureRollbarSingleton();

  //...
}

/// <summary>
/// Configures the Rollbar singleton-like notifier.
/// </summary>
private void ConfigureRollbarSingleton()
{
  const string rollbarAccessToken = "POST_SERVER_ITEM_ACCESS_TOKEN";
  const string rollbarEnvironment = "RollbarNetSamples";

  RollbarLocator.RollbarInstance
    // minimally required Rollbar configuration:
    .Configure(new RollbarConfig(rollbarAccessToken) { Environment = rollbarEnvironment })
    // optional step if you would like to monitor Rollbar internal events within your application:
    .InternalEvent += OnRollbarInternalEvent
    ;
}

Activate the Rollbar

Next, add Rollbar logging service:

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
  //...

  services.AddRollbarLogger(loggerOptions =>
                            {
                              loggerOptions.Filter = (loggerName, loglevel) => loglevel >= LogLevel.Trace;
                            });

  services.AddMvc();
}

Now, add the Rollbar middleware to the application pipeline. This is normally done by adding its usage within the Configure(…) method of Startup.cs.

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
  if (env.IsDevelopment())
  {
    app.UseDeveloperExceptionPage();
  }

  app.UseRollbarMiddleware();

  // Any other middleware component intended to be "monitored" by Rollbar.NET middleware
  // go below this line:

  app.UseMvc();
}

That's it! Now every unhandled exception within the middleware pipeline under the Rollbar middleware component monitoring will be reported to Rollbar.

ASP.NET MVC

See our documentation for ASP.NET MVC.

Winforms

To use inside a Winforms Application, do the following inside your main method:

[STAThread]
static void Main()
{
    RollbarLocator.RollbarInstance.Configure(new RollbarConfig
    {
        AccessToken = "POST_SERVER_ITEM_ACCESS_TOKEN",
        Environment = "production"
    });
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);

    Application.ThreadException += (sender, args) =>
    {
        RollbarLocator.RollbarInstance.Error(args.Exception);
    };

    AppDomain.CurrentDomain.UnhandledException += (sender, args) =>
    {
        RRollbarLocator.RollbarInstance.Error(args.ExceptionObject as System.Exception);
    };
    
    TaskScheduler.UnobservedTaskException += (sender, args) =>
    {
        RollbarLocator.RollbarInstance.Error(args.Exception);
    };

    Application.Run(new Form1());
}

WPF

It is optional to set the user for Rollbar, and this can be reset to a different user at any time. This example includes a default user being set with MainWindow.xml loads by calling the SetRollbarReportingUser function. Gist example code here.

In App.cs:

namespace Sample
{
    /// <summary>
    /// Interaction logic for App.xaml
    /// </summary>
    public partial class App : Application
    {
        protected override void OnStartup(StartupEventArgs e)
        {
            base.OnStartup(e);
            System.Diagnostics.Debug.WriteLine("App Start Up");

            //Initialize Rollbar
            RollbarLocator.RollbarInstance.Configure(new RollbarConfig
            {
                AccessToken = "POST_SERVER_ITEM_ACCESS_TOKEN",
                Environment = "production"          
            });
            // Setup Exception Handler
            AppDomain.CurrentDomain.UnhandledException += (sender, args) =>
            {
                RollbarLocator.RollbarInstance.Error(args.ExceptionObject as System.Exception);
            };
        }
    }
}

In MainWindow.cs:

namespace Sample
{
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            System.Diagnostics.Debug.Write("Starting MainWindow");

            InitializeComponent();

            //Set Default User for RollbarReporting
            //  -- Reset if user logs in or wait to call SetRollbarReportingUser until user logs in 
            SetRollbarReportingUser("id", "myEmail@example.com", "default");
        }

        private void SetRollbarReportingUser(string id, string email, string userName)
        {
            Person person = new Person(id);
            person.Email = email;
            person.UserName = userName;
            RollbarLocator.RollbarInstance.Config.Person = person;
        }
    }
}

WebForms

Application Level Error Handling

From the application error handler in the Global.asax file:

void Application_Error(object sender, EventArgs e)
{
  Exception exception = Server.GetLastError();

  // Let's report to Rollbar on the Application/Global Level:
  var metaData = new Dictionary<string, object>();
  metaData.Add("reportLevel", "GlobalLevel");
  RollbarLocator.RollbarInstance.Error(exception, metaData);

  if (exception is HttpUnhandledException)
  {
    // Pass the error on to the error page.
    Server.Transfer("ErrorPage.aspx?handler=Application_Error%20-%20Global.asax", true);
  }
}

Page Level Error Handling

From a page error handler in its code-behind file/class:

  private void Page_Error(object sender, EventArgs e)
  {
    // Get last error from the server.
    Exception exception = Server.GetLastError();

    // Let's report to Rollbar on the Page Level:
    var metaData = new Dictionary<string, object>();
    metaData.Add("reportLevel", "PageLevel");
    metaData.Add("failedPage", this.AppRelativeVirtualPath);
    RollbarLocator.RollbarInstance.Error(exception, metaData);

    // Handle specific exception.
    if (exception is InvalidOperationException)
    {
      // Pass the error on to the error page.
      Server.Transfer("ErrorPage.aspx?handler=Page_Error%20-%20Default.aspx", true);
    }
  }

Code Level Error Handling

From the catch block:

try
{
  // Let's simulate an error:
  throw new NullReferenceException("WebForms.Site sample: simulated exception");
}
catch (Exception exception)
{
  // Let's report to Rollbar on the Code Level:
  var metaData = new Dictionary<string, object>();
  metaData.Add("reportLevel", "CodeLevel");
  metaData.Add("failedPage", this.AppRelativeVirtualPath);
  RollbarLocator.RollbarInstance.Error(exception, metaData);
  throw exception;
}

Telemetry

The Rollbar.NET SDK has an ability to collect (independently from its logger components) some telemetry information at runtime and keeps it within a configurable fixed depth Telemetry queue. It provides an API for capturing telemetry events within the queue so that whenever the Rollbar logger reports any data to Rollbar API the telemetry items available in the Telemetry queue at the time of logging are automatically attached to the logger payload. This Telemetry data is intended to provide extra information about the events preceding the logging event that could be useful when analyzing the logging event itself.
Currently, the Telemetry events are categorized by types. For example, network telemetry events, error telemetry events, manual telemetry events, etc.
The Telemetry functionality of the SDK can be configured either in code or via an application configuration file. It can be either enabled or disabled. It allows configuration of the Telemetry queue depth. It also allows to filter what telemetry types to be included (or not) into the collection. In addition, it allows to specify if Telemetry data auto-capture should be enabled or not (however, the auto capture functionality yet to be finalized and implemented soon).

The Telemetry infrastructure is built around an application wide service called TelemetryCollector that is implemented as a singleton. It provides API for configuring the Telemetry behavior, capturing Telemetry events as needed and “snapping” all the available captured telemetry items at any given time. The fixed depth TelemetryQueue is hosted internally by the TelemetryCollector.

Configuration

In Code

/// <summary>
/// Configures the rollbar telemetry.
/// </summary>
private static void ConfigureRollbarTelemetry()
{
  TelemetryConfig telemetryConfig = new TelemetryConfig(
    telemetryEnabled: true,
    telemetryQueueDepth: 3
  );
  TelemetryCollector.Instance.Config.Reconfigure(telemetryConfig);
}

Via appsettings.json Application Configuration File

Via app.config Application Configuration File

Capturing Telemetry Events

            TelemetryCollector.Instance.Capture(
                new Telemetry(
                    TelemetrySource.Client,
                    TelemetryLevel.Info,
                    new LogTelemetry("Something interesting happened.")
                    )
                );

            TelemetryCollector.Instance.Capture(
                new Telemetry(
                    TelemetrySource.Client,
                    TelemetryLevel.Error,
                    new ErrorTelemetry(new System.Exception("Worth mentioning!"))
                    )
                );

            TelemetryCollector.Instance.Capture(
                new Telemetry(
                    TelemetrySource.Client,
                    TelemetryLevel.Error,
                    new ManualTelemetry(new Dictionary<string, object>() { 
                { "param1", "value1" }, 
                { "param2", "value2" }, }
              )
                  )
                );

Rollbar Deployment API Client for .NET

Rollbar Deployment API implements deployment tracking as a REST-based service.
This Rollbar.NET Notifier SDK includes .NET compatible client to the Deployment API.

The key API type is the RollbarDeploysManager that implements IRollbarDeploysManager interfaces. The interface defines async methods for

  • registering new deployment instance,
  • querying registered deployment instances page-by-page,
  • and querying deployment instance details by specified deploymentID.

The RollbarDeploysManager does not have default parameterless constructor defined since it needs some required parameters to be provided at construction time, like Rollbar write and/or read access tokens. Once properly constructed it can be used for deployment registration (by supplying a valid instance of the Deployment class) and querying for previously registered deployments:

IRollbarDeploysManager deploysManager = 
  new RollbarDeploysManager(
  RollbarUnitTestSettings.AccessToken,
  RollbarUnitTestSettings.DeploymentsReadAccessToken
);  
var deployment = 
  new Deployment(RollbarUnitTestSettings.Environment, "99909a3a5a3dd4363f414161f340b582bb2e999")
{
  Comment = "Some new unit test deployment @ " + DateTimeOffset.Now,
  LocalUsername = "UnitTestRunner",
  RollbarUsername = "rollbar",
};

var task = deploysManager.RegisterAsync(deployment);
task.Wait(TimeSpan.FromSeconds(3));

var deployments = GetAllDeployments();
var latestDeployment = deployments.FirstOrDefault();
var getDeploymentTask = deploysManager.GetDeploymentAsync(latestDeployment.DeployID);
getDeploymentTask.Wait(TimeSpan.FromSeconds(3));
var deploymentDetails = getDeploymentTask.Result;

where GetAllDeployments() could be implemented as:

private ICollection<IDeploymentDetails> GetAllDeployments()
{
  List<IDeploymentDetails> deployments = new List<IDeploymentDetails>();

  int pageCount = 0;
  int pageItems = 0;
  do
  {
    var task = this._deploysManager.GetDeploymentsPageAsync(RollbarUnitTestSettings.Environment, ++pageCount);
    task.Wait(TimeSpan.FromSeconds(1));
    pageItems = task.Result.Length;
    if (pageItems > 0)
    {
      deployments.AddRange(task.Result);
    }
  }
  while (pageItems > 0);

  return deployments;
}

Help / Support

If you run into any issues, please email us at support@rollbar.com

For bug reports, please open an issue on GitHub.