Documentation

ASP .NET

Documentation - Raygun4Net - Console Apps Error Tracking & Reporting

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net and install it.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net/ for instructions on installation using the package manager console.

2. Setup Raygun in Web.config

In your Web.config file, find configSections and add the following entry:

<section name="RaygunSettings" type="Mindscape.Raygun4Net.RaygunSettings, Mindscape.Raygun4Net"/>

Then reference it by adding the following line somewhere after the configSections tag. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the "Application Settings". RaygunSettings has many options which are explained further down this page.

<RaygunSettings apikey="YOUR_APP_API_KEY" />

3. Add the Raygun HTTP module to automatically send exceptions

Still in Web.config, set up the Raygun HTTP module. This is done slightly differently depending on what version of IIS you're using. If in doubt, just try them both:

For IIS 6.0 (Or a fallback for using IIS 7.0 in classic mode), use system.web

<system.web>
  <httpModules>
    <add name="RaygunErrorModule" type="Mindscape.Raygun4Net.RaygunHttpModule"/>
  </httpModules>
</system.web>

For IIS 7.0, use system.webServer

<system.webServer>
  <modules>
    <add name="RaygunErrorModule" type="Mindscape.Raygun4Net.RaygunHttpModule"/>
  </modules>
</system.webServer>

The above set up will cause all unhandled exceptions to be sent to your Raygun account.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exception data. Sometimes you may want to send exceptions manually - either in an exception handler as an alternative to using the HTTP module, or to report handled exceptions from within a try/catch block.

To manually send exceptions, create an instance of the RaygunClient class. The default constructor will use the API Key that you set up in Web.config. Alternatively, you could use the constructor that takes an API Key if you need to send the exception to a different one of your Raygun applications, or if you didn't set it in the config.

With the RaygunClient, you can call either the Send or SendInBackground methods. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of using a RaygunClient within the Application_Error handler. This is an alternative to using the HTTP module described in step 3 of the setup instructions above.

protected void Application_Error()
{
  var exception = Server.GetLastError();
  new RaygunClient().Send(exception);
}

Similarly, here's how to manually send exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  new RaygunClient().SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Raygun4Net features

The rest of this documentation will describe all the optional features of Raygun4Net. Some of these features simply require setting attributes on RaygunSettings in Web.config, and other features require using properties or methods on a RaygunClient instance.

Providing a custom RaygunClient to the HTTP module

The HTTP module mentioned in step 3 of the instructions above will use its own RaygunClient instance to send exceptions. If you need to use any of the features that require customizing a RaygunClient instance, then you can provide the HTTP module with your own RaygunClient as follows.

In your global HttpApplication class, create a static instance of RaygunClient, and set any options on it within your Application_Start method. The default constructor of RaygunClient will use the API Key that you set up in Web.config, or you can pass in an API key if you need to. Next, implement the IRaygunApplication interface, and in the single method that you need to implement - GenerateRaygunClient, simply return your RaygunClient instance. And that's it - from now on, the HTTP module will use your RaygunClient returned from this method to send all unhandled exceptions.

public class Global : System.Web.HttpApplication, IRaygunApplication
{
  private static readonly RaygunClient _raygunClient = new RaygunClient();

  protected void Application_Start(object sender, EventArgs e)
  {
    // Set any options on the client here
  }

  public RaygunClient GenerateRaygunClient()
  {
    return _raygunClient;
  }
}

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party plugins) or due to issues that cannot be solved (such as various bot attacks). In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This assumes that the Raygun HTTP module is being used, and so includes the IRaygunApplication interface technique described above.

public class Global : System.Web.HttpApplication, IRaygunApplication
{
  private static readonly RaygunClient _raygunClient = new RaygunClient();

  protected void Application_Start(object sender, EventArgs e)
  {
    // Attach the event handler:
    _raygunClient.SendingMessage += RaygunClient_SendingMessage;
  }

  private void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
  {
    // This is an example of cancelling a message:
    if (e.Message.Details.Request.Url.StartsWith("/api/v2/breachedaccount/"))
    {
      e.Cancel = true;
    }
  }

  public RaygunClient GenerateRaygunClient()
  {
    return _raygunClient;
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This assumes that the Raygun HTTP module is being used, and so includes the IRaygunApplication interface technique described above.

public class Global : System.Web.HttpApplication, IRaygunApplication
{
  private static readonly RaygunClient _raygunClient = new RaygunClient();

  protected void Application_Start(object sender, EventArgs e)
  {
    // Attach the event handler:
    _raygunClient.CustomGroupingKey += RaygunClient_CustomGroupingKey;
  }

  private void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
  {
    // This example simply performs pure message based grouping on basic Exception instances:
    if (e.Message.Details.Error.ClassName.Equals("Exception"))
    {
      string key = e.Exception.Message;
      e.CustomGroupingKey = key;
    }
  }

  public RaygunClient GenerateRaygunClient()
  {
    return _raygunClient;
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Exclude errors by HTTP status code

If using the HTTP module, then you can exclude errors by their HTTP status code by providing a comma separated list of status codes to ignore in the configuration. For example if you wanted to exclude errors that return the I'm a teapot response code, you could use this configuration:

<RaygunSettings apikey="YOUR_APP_API_KEY" excludeHttpStatusCodes="418" />

Exclude errors that originate from a local origin

To prevent Raygun4Net from sending exceptions that originate from a local origin (your debug/development machine), set the excludeErrorsFromLocal attribute to true as seen in the code below. This is useful if you find that everyone in your team sending exceptions from their local machines is noisy and pointless. This option is a convenient alternative to using Web.config transforms to do the same thing.

<RaygunSettings apikey="YOUR_APP_API_KEY" excludeErrorsFromLocal="true" />

Remove sensitive request data

By default, Raygun4Net will send all form-fields, headers, cookies and server-variables in the current HTTP request. If you have sensitive data in an HTTP request that you wish to prevent being transmitted to Raygun, you can provide a list of possible named values to remove:

<RaygunSettings apikey="YOUR_APP_API_KEY" ignoreFormFieldNames="password,creditcard,cv2" />

Four attributes are available, to remove values from these four properties:

  • ignoreFormFieldNames (ignores values from HttpRequest.Form)
  • ignoreHeaderNames (ignores values from HttpRequest.Headers)
  • ignoreCookieNames (ignores values from HttpRequest.Cookies)
  • ignoreServerVariableNames (ignores values from HttpRequest.ServerVariables)

Or specify them in code with the following multi-parameter method:

_raygunClient.IgnoreFormFieldNames("password", "creditcard", "cv2");

Setting any of these four options to * will cause Raygun4Net to ignore all values in that category, so none of them are sent to Raygun.io. Also, by placing * before, after or at both ends of a name, Raygun4Net will use that as an ends-with, starts-with or contains condition respectively when determining what to ignore.

Medium Trust

When integrated into an ASP.NET project running on Azure or shared web hosts running under Medium Trust, the provider can be configured to run correctly using this:

<RaygunSettings apikey="YOUR_APP_API_KEY" mediumTrust="true" />

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each exception has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a few ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

_raygunClient.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

_raygunClient.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Another way to provide the user information is to use one of the Send or SendInBackground overloads which has a RaygunIdentifierMessage as a parameter. The overloads include 'tags' and 'custom data' parameters (see below) which you can set as null if you don't need to use them. This should be used if you only get the user information when a crash occurs, or if the user information is not fixed, or in heavily threaded scenarios where you have a separate RaygunClient instance for each thread.

_raygunClient.SendInBackground(exception, null, null, new RaygunIdentifierMessage("user@email.com") { IsAnonymous = false, FullName = "Robbie Robot", FirstName = "Robbie" });

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

_raygunClient.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

_raygunClient.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

By default, Raygun4Net will attempt to send the assembly version of your project with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

_raygunClient.ApplicationVersion = "1.3.37.0";

Alternatively, you can set the applicationVersion in Web.config as follows. If both are set, the property mentioned above takes precedence over the Web.config setting.

<RaygunSettings apikey="YOUR_APP_API_KEY" applicationVersion="1.3.37.0" />

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

_raygunClient.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default HttpUnhandledException and TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support (Only applicable to .NET 4.0 and higher)

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances using the method described above, all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exceptions (HttpUnhandledException and TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

_raygunClient.RemoveWrapperExceptions(typeof(TargetInvocationException));

Proxy settings

The Raygun4Net provider uses the default Windows proxy settings (as set in Internet Explorer's Connection tab, or Web.config) when sending messages to Raygun. If your proxy requires authentication credentials, you can provide these by setting the ProxyCredentials property of your RaygunClient instance:

_raygunClient.ProxyCredentials = new NetworkCredential("user", "pword");

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Signed version

A version of Raygun4Net that has been signed with a strong name is available for those who need it. While following the set up instructions above, simply install the Mindscape.Raygun4Net.Signed NuGet package.

ASP .NET MVC

Documentation - Raygun4Net - .NET MVC Error Tracking & Reporting

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net.Mvc and install it. Make sure you do pick the Mvc package rather than the standard Raygun4Net package.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net.Mvc/ for instructions on installation using the package manager console.

2. Setup Raygun in Web.config

In your Web.config file, find configSections and add the following entry:

<section name="RaygunSettings" type="Mindscape.Raygun4Net.RaygunSettings, Mindscape.Raygun4Net"/>

Then reference it by adding the following line somewhere after the configSections tag. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings. RaygunSettings has many options which are explained further down this page.

<RaygunSettings apikey="YOUR_APP_API_KEY" />

3. Add the Raygun HTTP module to automatically send exceptions

Still in Web.config, set up the Raygun HTTP module. This is done slightly differently depending on what version of IIS you're using. If in doubt, just try them both:

For IIS 6.0 (Or a fallback for using IIS 7.0 in classic mode), use system.web

<system.web>
  <httpModules>
    <add name="RaygunErrorModule" type="Mindscape.Raygun4Net.RaygunHttpModule"/>
  </httpModules>
</system.web>

For IIS 7.0, use system.webServer

<system.webServer>
  <modules>
    <add name="RaygunErrorModule" type="Mindscape.Raygun4Net.RaygunHttpModule"/>
  </modules>
</system.webServer>

The above set up will cause all unhandled exceptions to be sent to your Raygun account.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually - either in an exception filter as an alternative to using the HTTP module, or to report handled exceptions from within a try/catch block.

To manually send exceptions, create an instance of the RaygunClient class. The default constructor will use the API Key that you set up in Web.config. Alternatively, you could use the constructor that takes an API Key if you need to send the exception to a different one of your Raygun applications, or if you didn't set it in the config.

With the RaygunClient, you can call either the Send or SendInBackground methods. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  new RaygunClient().SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Providing a custom RaygunClient to the HTTP module

The HTTP module mentioned in step 3 of the instructions above will use its own RaygunClient instance to send exceptions. If you need to use any of the features that require customizing a RaygunClient instance, then you can provide the HTTP module with your own RaygunClient as follows.

In your global HttpApplication class, create a static instance of RaygunClient, and set any options on it within your Application_Start method. The default constructor of RaygunClient will use the API Key that you set up in Web.config, or you can pass in an API key if you need to. Next, implement the IRaygunApplication interface, and in the single method that you need to implement - GenerateRaygunClient, simply return your RaygunClient instance. And that's it - from now on, the HTTP module will use your RaygunClient returned from this method to send all unhandled exceptions.

public class MvcApplication : System.Web.HttpApplication, IRaygunApplication
{
  private static readonly RaygunClient _raygunClient = new RaygunClient();

  protected void Application_Start(object sender, EventArgs e)
  {
    // Set any options on the client here
  }

  public RaygunClient GenerateRaygunClient()
  {
    return _raygunClient;
  }
}

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party plugins) or due to issues that cannot be solved (such as various bot attacks). In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This assumes that the Raygun HTTP module is being used, and so includes the IRaygunApplication interface technique described above.

public class MvcApplication : System.Web.HttpApplication, IRaygunApplication
{
  private static readonly RaygunClient _raygunClient = new RaygunClient();

  protected void Application_Start(object sender, EventArgs e)
  {
    // Attach the event handler:
    _raygunClient.SendingMessage += RaygunClient_SendingMessage;
  }

  private void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
  {
    // This is an example of cancelling a message:
    if (e.Message.Details.Request.Url.StartsWith("/api/v2/breachedaccount/"))
    {
      e.Cancel = true;
    }
  }

  public RaygunClient GenerateRaygunClient()
  {
    return _raygunClient;
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This assumes that the Raygun HTTP module is being used, and so includes the IRaygunApplication interface technique described above.

public class MvcApplication : System.Web.HttpApplication, IRaygunApplication
{
  private static readonly RaygunClient _raygunClient = new RaygunClient();

  protected void Application_Start(object sender, EventArgs e)
  {
    // Attach the event handler:
    _raygunClient.CustomGroupingKey += RaygunClient_CustomGroupingKey;
  }

  private void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
  {
    // This example simply performs pure message based grouping on basic Exception instances:
    if (e.Message.Details.Error.ClassName.Equals("Exception"))
    {
      string key = e.Exception.Message;
      e.CustomGroupingKey = key;
    }
  }

  public RaygunClient GenerateRaygunClient()
  {
    return _raygunClient;
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Exclude errors by HTTP status code

If using the HTTP module, then you can exclude errors by their HTTP status code by providing a comma separated list of status codes to ignore in the configuration. For example if you wanted to exclude errors that return the I'm a teapot response code, you could use this configuration:

<RaygunSettings apikey="YOUR_APP_API_KEY" excludeHttpStatusCodes="418" />

Exclude errors that originate from a local origin

To prevent Raygun4Net from sending exceptions that originate from a local origin (your debug/development machine), set the excludeErrorsFromLocal attribute to true as seen in the code below. This is useful if you find that everyone in your team sending exceptions from their local machines is noisy and pointless. This option is a convenient alternative to using Web.config transforms to do the same thing.

<RaygunSettings apikey="YOUR_APP_API_KEY" excludeErrorsFromLocal="true" />

Remove sensitive request data

By default, Raygun4Net will send all form-fields, headers, cookies and server-variables in the current HTTP request. If you have sensitive data in an HTTP request that you wish to prevent being transmitted to Raygun, you can provide a list of possible named values to remove:

<RaygunSettings apikey="YOUR_APP_API_KEY" ignoreFormFieldNames="password,creditcard,cv2" />

Four attributes are available, to remove values from these four properties:

  • ignoreFormFieldNames (ignores values from HttpRequest.Form)
  • ignoreHeaderNames (ignores values from HttpRequest.Headers)
  • ignoreCookieNames (ignores values from HttpRequest.Cookies)
  • ignoreServerVariableNames (ignores values from HttpRequest.ServerVariables)

Or specify them in code with the following multi-parameter method:

_raygunClient.IgnoreFormFieldNames("password", "creditcard", "cv2");

Setting any of these four options to * will cause Raygun4Net to ignore all values in that category, so none of them are sent to Raygun.io. Also, by placing * before, after or at both ends of a name, Raygun4Net will use that as an ends-with, starts-with or contains condition respectively when determining what to ignore.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve those that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique GUID will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a few ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

_raygunClient.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

_raygunClient.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Another way to provide the user information is to use one of the Send or SendInBackground overloads which has a RaygunIdentifierMessage as a parameter. The overloads include 'tags' and 'custom data' parameters (see below) which you can set as null if you don't need to use them. This should be used if you only get the user information when a crash occurs, or if the user information is not fixed, or in heavily threaded scenarios where you have a separate RaygunClient instance for each thread.

_raygunClient.SendInBackground(exception, null, null, new RaygunIdentifierMessage("user@email.com") { IsAnonymous = false, FullName = "Robbie Robot", FirstName = "Robbie" });

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

_raygunClient.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

_raygunClient.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

By default, Raygun4Net will attempt to send the assembly version of your project with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

_raygunClient.ApplicationVersion = "1.3.37.0";

Alternatively, you can set the applicationVersion in Web.config as follows. If both are set, the property mentioned above takes precedence over the Web.config setting.

<RaygunSettings apikey="YOUR_APP_API_KEY" applicationVersion="1.3.37.0" />

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

_raygunClient.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default HttpUnhandledException and TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support (Only applicable to .NET 4.0 and higher)

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances using the method described above, all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exceptions (HttpUnhandledException and TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

_raygunClient.RemoveWrapperExceptions(typeof(TargetInvocationException));

Proxy settings

The Raygun4Net provider uses the default Windows proxy settings (as set in Internet Explorer's Connection tab, or Web.config) when sending messages to Raygun. If your proxy requires authentication credentials, you can provide these by setting the ProxyCredentials property of your RaygunClient instance:

_raygunClient.ProxyCredentials = new NetworkCredential("user", "pword");

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Web Api

Documentation - Raygun4Net - WebAPI Error Tracking & Reporting

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net.WebApi and install it. Make sure you do pick the WebApi package rather than the standard Raygun4Net package.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net.WebApi/ for instructions on installation using the package manager console.

2. Setup Raygun in Web.config

In your Web.config file, find configSections and add the following entry:

<section name="RaygunSettings" type="Mindscape.Raygun4Net.RaygunSettings, Mindscape.Raygun4Net"/>

Then reference it by adding the following line somewhere after the configSections tag. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings. RaygunSettings has many options which are explained further down this page.

<RaygunSettings apikey="YOUR_APP_API_KEY" />

3. Attach the RaygunWebApiClient

In your WebApiConfig class, call the static RaygunWebApiClient.Attach(config) method from within the Register method:

using Mindscape.Raygun4Net.WebApi;
public static class WebApiConfig
{
  public static void Register(HttpConfiguration config)
  {
    RaygunWebApiClient.Attach(config);
    
    // Web API routes here
  }
}

The above set up will cause all unhandled exceptions to be sent to your Raygun account where you can easily view all of your error monitoring and crash report data.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually - such as handled exceptions from within a try/catch block.

To manually send exceptions, create an instance of the RaygunWebApiClient class. The default constructor will use the API Key that you set up in Web.config. Alternatively, you could use the constructor that takes an API Key if you need to send the exception to a different one of your Raygun applications, or if you didn't set it in the config.

With the RaygunWebApiClient, you can call either the Send or SendInBackground methods. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  new RaygunWebApiClient().SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunWebApiClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Providing a custom RaygunWebApiClient to the automatic exception handlers

The Attach method mentioned in step 3 of the instructions above will use its own RaygunWebApiClient instance to send exceptions. If you need to use any of the features that require setting options on a RaygunWebApiClient instance, then you can provide the Attach method with your own RaygunWebApiClient as follows.

Use the static RaygunWebApiClient.Attach method overload that takes a function. Within this function, return a new (or previously created) RaygunWebApiClient instance. In this function you can set any additional options on the RaygunWebApiClient instance that you need - more information about each feature is described in the various sections below. Using the default constructor will pick up the api key you set in Web.config, or you can pass an api key into the constructor if you need to.

public static class WebApiConfig
{
  private static RaygunWebApiClient _raygunClient;

  public static void Register(HttpConfiguration config)
  {
    RaygunWebApiClient.Attach(config, () => {
      if (_raygunClient == null) {
        _raygunClient = new RaygunWebApiClient();
        // Set any options on the RaygunWebApiClient instance here
      }
      return _raygunClient;
    });

    // Web API routes here
  }
}

Modify or cancel messages

On a RaygunWebApiClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunWebApiClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party plugins) or due to issues that cannot be solved (such as various bot attacks). In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. Notice that this code uses the technique described above of passing a client instance to the Attach method.

public static class WebApiConfig
{
  private static RaygunWebApiClient _raygunClient;

  public static void Register(HttpConfiguration config)
  {
    RaygunWebApiClient.Attach(config, () => {
      if (_raygunClient == null) {
        _raygunClient = new RaygunWebApiClient();
        _raygunClient.SendingMessage += (sender, args) =>
        {
          // This is an example of cancelling a message:
          if ("BadServer".Equals(args.Message.Details.MachineName))
          {
            args.Cancel = true;
          }
        };
      }
      return _raygunClient;
    });

    // Web API routes here
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunWebApiClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. Notice that this code uses the technique described above of passing a client instance to the Attach method.

public static class WebApiConfig
{
  private static RaygunWebApiClient _raygunClient;

  public static void Register(HttpConfiguration config)
  {
    RaygunWebApiClient.Attach(config, () => {
      if (_raygunClient == null) {
        _raygunClient = new RaygunWebApiClient();
        _raygunClient.CustomGroupingKey += (sender, args) =>
        {
          // This example simply performs pure message based grouping on basic Exception instances:
          if (args.Message.Details.Error.ClassName.Equals("Exception"))
          {
            string key = args.Exception.Message;
            args.CustomGroupingKey = key;
          }
        };
      }
      return _raygunClient;
    });

    // Web API routes here
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Exclude errors by HTTP status code

If using the HTTP module, then you can exclude errors by their HTTP status code by providing a comma separated list of status codes to ignore in the configuration. For example if you wanted to exclude errors that return the I'm a teapot response code, you could use this configuration:

<RaygunSettings apikey="YOUR_APP_API_KEY" excludeHttpStatusCodes="418" />

Exclude errors that originate from a local origin

To prevent Raygun4Net from sending exceptions that originate from a local origin (your debug/development machine), set the excludeErrorsFromLocal attribute to true as seen in the code below. This is useful if you find that everyone in your team sending exceptions from their local machines is noisy and pointless. This option is a convenient alternative to using Web.config transforms to do the same thing.

<RaygunSettings apikey="YOUR_APP_API_KEY" excludeErrorsFromLocal="true" />

Remove sensitive request data

By default, Raygun4Net will send all form-fields and headers in the current HTTP request. If you have sensitive data in an HTTP request that you wish to prevent being transmitted to Raygun, you can provide a list of possible named values to remove:

<RaygunSettings apikey="YOUR_APP_API_KEY" ignoreFormFieldNames="password,creditcard,cv2" />

Two attributes are available, to remove values from these two properties:

  • ignoreFormFieldNames (ignores values from HttpRequestMessage.Form)
  • ignoreHeaderNames (ignores values from HttpRequestMessage.Headers)

Or specify them in code with the following multi-parameter method:

_raygunClient.IgnoreFormFieldNames("password", "creditcard", "cv2");

Setting any of these options to * will cause Raygun4Net to ignore all values in that category, so none of them are sent to Raygun.io. Also, by placing * before, after or at both ends of a name, Raygun4Net will use that as an ends-with, starts-with or contains condition respectively when determining what to ignore.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a couple of ways to provide user information, the simplest of which is to set the User property of the RaygunWebApiClient instance to an identifier of your choosing:

_raygunClient.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

_raygunClient.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

_raygunClient.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

_raygunClient.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

By default, Raygun4Net will attempt to send the assembly version of your project with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunWebApiClient.

_raygunClient.ApplicationVersion = "1.3.37.0";

Alternatively, you can set the applicationVersion in Web.config as follows. If both are set, the property mentioned above takes precedence over the Web.config setting.

<RaygunSettings apikey="YOUR_APP_API_KEY" applicationVersion="1.3.37.0" />

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

_raygunClient.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support (Only applicable to .NET 4.0 and higher)

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances using the method described above, all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exception (TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

_raygunClient.RemoveWrapperExceptions(typeof(TargetInvocationException));

Proxy settings

The Raygun4Net provider uses the default Windows proxy settings (as set in Internet Explorer's Connection tab, or Web.config) when sending messages to Raygun. If your proxy requires authentication credentials, you can provide these by setting the ProxyCredentials property of your RaygunWebApiClient instance:

_raygunClient.ProxyCredentials = new NetworkCredential("user", "pword");

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

WPF

Documentation - Raygun4Net - WPF Error Tracking & Reporting

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net and install it.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net/ for instructions on installation using the package manager console.

2. Create a RaygunClient

Create an instance of RaygunClient by passing your app API key to the constructor. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings. We recommend putting the RaygunClient in your App class.

using Mindscape.Raygun4Net;
private RaygunClient _raygunClient = new RaygunClient("YOUR_APP_API_KEY");

3. Listen to unhandled exceptions

Attach an event handler to the DispatcherUnhandledException event of your application. In the event handler, use the RaygunClient.Send method to send the Exception.

public App()
{
  DispatcherUnhandledException += OnDispatcherUnhandledException;
}

private void OnDispatcherUnhandledException(object sender, DispatcherUnhandledExceptionEventArgs e)
{
  _raygunClient.Send(e.Exception);
}

The above set up will cause all unhandled exceptions to be sent to your Raygun account where you can easily view all of your error monitoring and crash report data.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

RaygunClient provides Send and SendInBackground methods for manually sending to Raygun. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  _raygunClient.SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party libraries) or due to issues that cannot be solved. In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This code extends upon the setup instructions detailed above.

public partial class App : Application
{
  private RaygunClient _raygunClient = new RaygunClient("YOUR_APP_API_KEY");

  public App()
  {
    // Attach the event handler:
    _raygunClient.SendingMessage += RaygunClient_SendingMessage;
    DispatcherUnhandledException += OnDispatcherUnhandledException;
  }

  private void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
  {
    // This is an example of cancelling a message:
    if ("NotImplementedException".Equals(e.Message.Details.Error.ClassName))
    {
      e.Cancel = true;
    }
  }

  private void OnDispatcherUnhandledException(object sender, DispatcherUnhandledExceptionEventArgs e)
  {
    _raygunClient.Send(e.Exception);
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This code extends upon the setup instructions detailed above.

public partial class App : Application
{
  private RaygunClient _raygunClient = new RaygunClient("YOUR_APP_API_KEY");

  public App()
  {
    // Attach the event handler:
    _raygunClient.CustomGroupingKey += RaygunClient_CustomGroupingKey;
    DispatcherUnhandledException += OnDispatcherUnhandledException;
  }

  private void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
  {
    // This example simply performs pure message based grouping on basic Exception instances:
    if (e.Message.Details.Error.ClassName.Equals("Exception"))
    {
      string key = e.Exception.Message;
      e.CustomGroupingKey = key;
    }
  }

  private void OnDispatcherUnhandledException(object sender, DispatcherUnhandledExceptionEventArgs e)
  {
    _raygunClient.Send(e.Exception);
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each exception has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a few ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

_raygunClient.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

_raygunClient.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Another way to provide the user information is to use one of the Send or SendInBackground overloads which has a RaygunIdentifierMessage as a parameter. The overloads include 'tags' and 'custom data' parameters (see below) which you can set as null if you don't need to use them. This should be used if you only get the user information when a crash occurs, or if the user information is not fixed, or in heavily threaded scenarios where you have a separate RaygunClient instance for each thread.

_raygunClient.SendInBackground(exception, null, null, new RaygunIdentifierMessage("user@email.com") { IsAnonymous = false, FullName = "Robbie Robot", FirstName = "Robbie" });

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

_raygunClient.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

_raygunClient.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

By default, Raygun4Net will attempt to send the assembly version of your project with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

_raygunClient.ApplicationVersion = "1.3.37.0";

Alternatively, you can set the applicationVersion in Web.config as follows. If both are set, the property mentioned above takes precedence over the app.config setting.

<RaygunSettings apikey="YOUR_APP_API_KEY" applicationVersion="1.3.37.0" />

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

_raygunClient.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default HttpUnhandledException and TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support (Only applicable to .NET 4.0 and higher)

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances using the method described above, all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exceptions (HttpUnhandledException and TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

_raygunClient.RemoveWrapperExceptions(typeof(TargetInvocationException));

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Signed version

A version of Raygun4Net that has been signed with a strong name is available for those who need it. While following the set up instructions above, simply install the Mindscape.Raygun4Net.Signed NuGet package.

WinForms

Documentation - Raygun4Net - Winforms Error Tracking & Reporting

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net and install it.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net/ for instructions on installation using the package manager console.

2. Create a RaygunClient

Create an instance of RaygunClient by passing your app API key to the constructor. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings. We recommend putting the RaygunClient in your Program class.

using Mindscape.Raygun4Net;
private static RaygunClient _raygunClient = new RaygunClient("YOUR_APP_API_KEY");

3. Listen to unhandled exceptions

Attach an event handler to the Application.ThreadException event and AppDomain.CurrentDomain.UnhandledException event before calling Application.Run method. In the event handlers, use the RaygunClient.Send method to send the Exception.

[STAThread]
static void Main()
{
  Application.EnableVisualStyles();
  Application.SetCompatibleTextRenderingDefault(false);

  Application.ThreadException += new ThreadExceptionEventHandler(Application_ThreadException);
  AppDomain.CurrentDomain.UnhandledException += new UnhandledExceptionEventHandler(CurrentDomain_UnhandledException);

  Application.Run(new Form1());
}

private static void Application_ThreadException(object sender, ThreadExceptionEventArgs e)
{
  _raygunClient.Send(e.Exception);
}

private static void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
{
  _raygunClient.Send(e.ExceptionObject as Exception);
}

The above set up will cause all unhandled exceptions to be sent to your Raygun account.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

RaygunClient provides Send and SendInBackground methods for manually sending to Raygun. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  _raygunClient.SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party libraries) or due to issues that cannot be solved. In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This code extends upon the setup instructions detailed above.

static class Program
{
  private static RaygunClient _raygunClient = new RaygunClient("YOUR_APP_API_KEY");

  [STAThread]
  static void Main()
  {
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);

    // Attach the event handler:
    _raygunClient.SendingMessage += RaygunClient_SendingMessage;
    Application.ThreadException += new ThreadExceptionEventHandler(Application_ThreadException);
    AppDomain.CurrentDomain.UnhandledException += new UnhandledExceptionEventHandler(CurrentDomain_UnhandledException);

    Application.Run(new Form1());
  }

  private static void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
  {
    // This is an example of cancelling a message:
    if ("NotImplementedException".Equals(e.Message.Details.Error.ClassName))
    {
      e.Cancel = true;
    }
  }

  private static void Application_ThreadException(object sender, ThreadExceptionEventArgs e)
  {
    _raygunClient.Send(e.Exception);
  }

  private static void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
  {
    _raygunClient.Send(e.ExceptionObject as Exception);
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This code extends upon the setup instructions detailed above.

static class Program
{
  private static RaygunClient _raygunClient = new RaygunClient("YOUR_APP_API_KEY");

  [STAThread]
  static void Main()
  {
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);

    // Attach the event handler:
    _raygunClient.CustomGroupingKey += RaygunClient_CustomGroupingKey;
    Application.ThreadException += new ThreadExceptionEventHandler(Application_ThreadException);
    AppDomain.CurrentDomain.UnhandledException += new UnhandledExceptionEventHandler(CurrentDomain_UnhandledException);

    Application.Run(new Form1());
  }

  private static void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
  {
    // This example simply performs pure message based grouping on basic Exception instances:
    if (e.Message.Details.Error.ClassName.Equals("Exception"))
    {
      string key = e.Exception.Message;
      e.CustomGroupingKey = key;
    }
  }

  private static void Application_ThreadException(object sender, ThreadExceptionEventArgs e)
  {
    _raygunClient.Send(e.Exception);
  }

  private static void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
  {
    _raygunClient.Send(e.ExceptionObject as Exception);
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each crash or error has affected. This is a huge help with prioritising issues to solve those that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a few ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

_raygunClient.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

_raygunClient.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Another way to provide the user information is to use one of the Send or SendInBackground overloads which has a RaygunIdentifierMessage as a parameter. The overloads include 'tags' and 'custom data' parameters (see below) which you can set as null if you don't need to use them. This should be used if you only get the user information when a crash occurs, or if the user information is not fixed, or in heavily threaded scenarios where you have a separate RaygunClient instance for each thread.

_raygunClient.SendInBackground(exception, null, null, new RaygunIdentifierMessage("user@email.com") { IsAnonymous = false, FullName = "Robbie Robot", FirstName = "Robbie" });

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

_raygunClient.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

_raygunClient.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

By default, Raygun4Net will attempt to send the assembly version of your project with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

_raygunClient.ApplicationVersion = "1.3.37.0";

Alternatively, you can set the applicationVersion in Web.config as follows. If both are set, the property mentioned above takes precedence over the app.config setting.

<RaygunSettings apikey="YOUR_APP_API_KEY" applicationVersion="1.3.37.0" />

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

_raygunClient.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default HttpUnhandledException and TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support (Only applicable to .NET 4.0 and higher)

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances using the method described above, all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exceptions (HttpUnhandledException and TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

_raygunClient.RemoveWrapperExceptions(typeof(TargetInvocationException));

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Signed version

A version of Raygun4Net that has been signed with a strong name is available for those who need it. While following the set up instructions above, simply install the Mindscape.Raygun4Net.Signed NuGet package.

Console apps

Documentation - Console apps

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net and install it.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net/ for instructions on installation using the package manager console.

2. Create a RaygunClient

Create an instance of RaygunClient by passing your app API key to the constructor. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings. We recommend putting the RaygunClient in your Program class.

using Mindscape.Raygun4Net;
private static RaygunClient _raygunClient = new RaygunClient("YOUR_APP_API_KEY");

3. Listen to unhandled exceptions

Attach an event handler to the AppDomain.CurrentDomain.UnhandledException event before your main program logic. In the event handler, use the RaygunClient.Send method to send the Exception.

static void Main(string[] args)
{
  AppDomain.CurrentDomain.UnhandledException += CurrentDomain_UnhandledException;

  // Proceed with program execution here
}

private static void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
{
  _raygunClient.Send(e.ExceptionObject as Exception);
}

The above set up will cause all unhandled exceptions to be sent to your Raygun account.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

RaygunClient provides Send and SendInBackground methods for manually sending to Raygun. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  _raygunClient.SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party libraries) or due to issues that cannot be solved. In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This code extends upon the setup instructions detailed above.

public class Program
{
  private static RaygunClient _raygunClient = new RaygunClient("YOUR_APP_API_KEY");

  static void Main(string[] args)
  {
    // Attach the event handler:
    _raygunClient.SendingMessage += RaygunClient_SendingMessage;
    AppDomain.CurrentDomain.UnhandledException += CurrentDomain_UnhandledException;

    // Proceed with program execution here
  }

  private static void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
  {
    // This is an example of cancelling a message:
    if ("NotImplementedException".Equals(e.Message.Details.Error.ClassName))
    {
      e.Cancel = true;
    }
  }

  private static void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
  {
    _raygunClient.Send(e.ExceptionObject as Exception);
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This code extends upon the setup instructions detailed above.

public class Program
{
  private static RaygunClient _raygunClient = new RaygunClient("YOUR_APP_API_KEY");

  static void Main(string[] args)
  {
    // Attach the event handler:
    _raygunClient.CustomGroupingKey += RaygunClient_CustomGroupingKey;
    AppDomain.CurrentDomain.UnhandledException += CurrentDomain_UnhandledException;

    // Proceed with program execution here
  }

  private static void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
  {
    // This example simply performs pure message based grouping on basic Exception instances:
    if (e.Message.Details.Error.ClassName.Equals("Exception"))
    {
      string key = e.Exception.Message;
      e.CustomGroupingKey = key;
    }
  }

  private static void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
  {
    _raygunClient.Send(e.ExceptionObject as Exception);
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve those that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a few ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

_raygunClient.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

_raygunClient.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Another way to provide the user information is to use one of the Send or SendInBackground overloads which has a RaygunIdentifierMessage as a parameter. The overloads include 'tags' and 'custom data' parameters (see below) which you can set as null if you don't need to use them. This should be used if you only get the user information when a crash occurs, or if the user information is not fixed, or in heavily threaded scenarios where you have a separate RaygunClient instance for each thread.

_raygunClient.SendInBackground(exception, null, null, new RaygunIdentifierMessage("user@email.com") { IsAnonymous = false, FullName = "Robbie Robot", FirstName = "Robbie" });

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

_raygunClient.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

_raygunClient.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

By default, Raygun4Net will attempt to send the assembly version of your project with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

_raygunClient.ApplicationVersion = "1.3.37.0";

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

_raygunClient.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default HttpUnhandledException and TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support (Only applicable to .NET 4.0 and higher)

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances using the method described above, all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exceptions (HttpUnhandledException and TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

_raygunClient.RemoveWrapperExceptions(typeof(TargetInvocationException));

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Signed version

A version of Raygun4Net that has been signed with a strong name is available for those who need it. While following the set up instructions above, simply install the Mindscape.Raygun4Net.Signed NuGet package.

Windows Phone

Documentation - Raygun4Net - Windows Store Error Tracking & Reporting

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net and install it.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net/ for instructions on installation using the package manager console.

2. Attach the RaygunClient

In the App.xaml.cs constructor (or any main entry point to your application), call the static RaygunClient.Attach method with your app API key. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

using Mindscape.Raygun4Net;
public App()
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  
  // Standard app initialization logic here
}

Raygun4Net will now automatically detect and send all unhandled exceptions to your Raygun account.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

RaygunClient provides a Send method for manually sending exceptions to Raygun. The Send method has many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  RaygunClient.Current.Send(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party libraries) or due to issues that cannot be solved. In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This code extends upon the setup instructions detailed above.

public App()
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.SendingMessage += RaygunClient_SendingMessage;
  
  // Standard app initialization logic here
}

private void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
{
  // This is an example of cancelling a message:
  if ("NotImplementedException".Equals(e.Message.Details.Error.ClassName))
  {
    e.Cancel = true;
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This code extends upon the setup instructions detailed above.

public App()
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.CustomGroupingKey += RaygunClient_CustomGroupingKey;
  
  // Standard app initialization logic here
}

private void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
{
  // This example simply performs pure message based grouping on basic Exception instances:
  if (e.Message.Details.Error.ClassName.Equals("Exception"))
  {
    string key = e.Exception.Message;
    e.CustomGroupingKey = key;
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a couple of ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

RaygunClient.Current.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

RaygunClient.Current.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Tags

An overload of the Send method allows you to include a list of tags with each manually sent exception:

RaygunClient.Current.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included. An overload for sending both tags and custom data is also provided.

Custom data

You can include key-value custom data using an overload of the Send method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

RaygunClient.Current.Send(exception, new Dictionary<string, object>() { { "key", "value" } });

An overload for sending both tags and custom data is also provided.

Version numbering

By default, Raygun4Net will attempt to send the assembly version of your project with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

RaygunClient.Current.ApplicationVersion = "1.3.37.0";

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

RaygunClient.Current.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default TargetInvocationException will always be stripped - see below to override this behavior.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exception (TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

RaygunClient.Current.RemoveWrapperExceptions(typeof(TargetInvocationException));

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Windows Store

Documentation - Windows Store

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net and install it.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net/ for instructions on installation using the package manager console.

2. Attach the RaygunClient

In the App.xaml.cs constructor (or any central entry point in your application), call the static RaygunClient.Attach method with your app API key. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

using Mindscape.Raygun4Net;
public App()
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
}

Raygun4Net will now automatically detect and send all unhandled exceptions to your Raygun account where you can easily see all of your error monitoring and crash report data.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

RaygunClient provides Send and SendAsync methods for manually sending to Raygun. It's important to note that SendAsync should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendAsync methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  RaygunClient.Current.SendAsync(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party libraries) or due to issues that cannot be solved. In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This code extends upon the setup instructions detailed above.

public App()
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.SendingMessage += RaygunClient_SendingMessage;
}

private void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
{
  // This is an example of cancelling a message:
  if ("NotImplementedException".Equals(e.Message.Details.Error.ClassName))
  {
    e.Cancel = true;
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This code extends upon the setup instructions detailed above.

public App()
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.CustomGroupingKey += RaygunClient_CustomGroupingKey;
}

private void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
{
  // This example simply performs pure message based grouping on basic Exception instances:
  if (e.Message.Details.Error.ClassName.Equals("Exception"))
  {
    string key = e.Exception.Message;
    e.CustomGroupingKey = key;
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a couple of ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

RaygunClient.Current.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

RaygunClient.Current.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Tags

An overload of the Send and SendAsync method allows you to include a list of tags with each manually sent exception:

RaygunClient.Current.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included. An overload for sending both tags and custom data is also provided.

Custom data

You can include key-value custom data using an overload of the Send and SendAsync method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

RaygunClient.Current.Send(exception, new Dictionary<string, object>() { { "key", "value" } });

An overload for sending both tags and custom data is also provided.

Version numbering

By default, Raygun4Net will attempt to send the package version of your project with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

RaygunClient.Current.ApplicationVersion = "1.3.37.0";

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

RaygunClient.Current.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances using the method described above, all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exception (TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

RaygunClient.Current.RemoveWrapperExceptions(typeof(TargetInvocationException));

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Signed version

A version of Raygun4Net that has been signed with a strong name is available for those who need it. While following the set up instructions above, simply install the Mindscape.Raygun4Net.Signed NuGet package.

WinRT

Documentation - Raygun4Net - WinRT Error Tracking & Reporting

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net and install it.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net/ for instructions on installation using the package manager console.

2. Attach the RaygunClient

In the App.xaml.cs constructor (or any main entry point to your application), call the static RaygunClient.Attach method with your app API key. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

using Mindscape.Raygun4Net;
public App()
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
}

Raygun4Net will now automatically detect and send all unhandled exceptions to your Raygun account where you can view all of your error monitoring and crash report data.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

RaygunClient provides a Send method for manually sending exceptions to Raygun. The Send method has options for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  RaygunClient.Current.Send(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party libraries) or due to issues that cannot be solved. In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This code extends upon the setup instructions detailed above.

public App()
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.SendingMessage += RaygunClient_SendingMessage;
}

private void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
{
  // This is an example of cancelling a message:
  if ("NotImplementedException".Equals(e.Message.Details.Error.ClassName))
  {
    e.Cancel = true;
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This code extends upon the setup instructions detailed above.

public App()
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.CustomGroupingKey += RaygunClient_CustomGroupingKey;
}

private void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
{
  // This example simply performs pure message based grouping on basic Exception instances:
  if (e.Message.Details.Error.ClassName.Equals("Exception"))
  {
    string key = e.Exception.Message;
    e.CustomGroupingKey = key;
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a couple of ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

RaygunClient.Current.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

RaygunClient.Current.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Tags

Options on the Send method allows you to include a list of tags with each manually sent exception:

RaygunClient.Current.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an option on the Send method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

RaygunClient.Current.Send(exception, new Dictionary<string, object>() { { "key", "value" } });

Version numbering

By default, Raygun4Net will attempt to send the package version of your project with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

RaygunClient.Current.ApplicationVersion = "1.3.37.0";

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

RaygunClient.Current.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances using the method described above, all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exception (TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

RaygunClient.Current.RemoveWrapperExceptions(typeof(TargetInvocationException));

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Signed version

A version of Raygun4Net that has been signed with a strong name is available for those who need it. While following the set up instructions above, simply install the Mindscape.Raygun4Net.Signed NuGet package.

Xamarin for iOS

Documentation - Xamarin.iOS - Error & Crash Reporting

Setup instructions

1. Install the NuGet package or Xamarin Component

Choose the following installation instructions depending on your situation:

NuGet - Visual Studio

Make sure NuGet is installed in Visual Studio, then right-click on your project and select "Manage NuGet Packages..." Make sure you're in the "Online" section in the left hand pane. Then, in the top right search box, search for Mindscape.Raygun4Net and install it.

NuGet - Xamarin Studio

Xamarin Studio has NuGet support built in (Make sure Xamarin Studio is up to date if it's not available). Right-click your project, hover over the "Add" item, then select "Add NuGet Packages..." Check that the top left selector is either showing "All Sources" or "Official NuGet Gallery". Then, in the top right search box, search for Mindscape.Raygun4Net and install it via the "Add Package" button in the bottom right corner.

Xamarin Component - Visual Studio

Right-click on the Components folder in your project and select "Get More Components..." Search for Raygun4Net, click the search result and then install it via the "Add to App" button.

Xamarin Component - Xamarin Studio

Double-click the Components folder in your project and click the "Get More Components" button in the top right corner. Search for Raygun4Net, click the search result and then install it via the "Add to App" button.

2. Attach the RaygunClient

In the main entry point of your application, call the static RaygunClient.Attach method with your app API key. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

using Mindscape.Raygun4Net;
static void Main(string[] args)
{
  RaygunClient.Attach("YOUR_APP_API_KEY");

  UIApplication.Main(args, null, "AppDelegate");
}

Raygun4Net will now automatically detect and send all unhandled exceptions to your Raygun account where you can view all of your error monitoring and crash report data.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

RaygunClient provides Send and SendInBackground methods for manually sending to Raygun. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  RaygunClient.Current.SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party libraries) or due to issues that cannot be solved. In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This code extends upon the setup instructions detailed above.

static void Main(string[] args)
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.SendingMessage += RaygunClient_SendingMessage;

  UIApplication.Main(args, null, "AppDelegate");
}

private static void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
{
  // This is an example of cancelling a message:
  if ("NotImplementedException".Equals(e.Message.Details.Error.ClassName))
  {
    e.Cancel = true;
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This code extends upon the setup instructions detailed above.

static void Main(string[] args)
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.CustomGroupingKey += RaygunClient_CustomGroupingKey;

  UIApplication.Main(args, null, "AppDelegate");
}

private static void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
{
  // This example simply performs pure message based grouping on basic Exception instances:
  if (e.Message.Details.Error.ClassName.Equals("Exception"))
  {
    string key = e.Exception.Message;
    e.CustomGroupingKey = key;
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a couple of ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

RaygunClient.Current.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

RaygunClient.Current.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

RaygunClient.Current.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

RaygunClient.Current.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

By default, Raygun4Net will attempt to send the bundle version of your application with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

RaygunClient.Current.ApplicationVersion = "1.3.37.0";

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

RaygunClient.Current.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default AggregateException and TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances (Which is done by default), all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exceptions (AggregateException and TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

RaygunClient.Current.RemoveWrapperExceptions(typeof(TargetInvocationException));

No ARMv7s support

When you compile your application, you may get a compile time error like the following:

file is universal (4 slices) but does not contain a(n) armv7s slice: XXXX/libRaygun4iOS.a file 'XXXX/libRaygun4iOS.a' for architecture armv7s XXXX.iOS

 

To solve this, in Xamarin Studio, double click your project in the solution explorer to bring up the project options. In the left hand menu, under the "Build" category, select "iOS Build". The options that appear will include "Supported architectures" with a drop down next to it. Open the drop down, and select the option that matches your current option - but without "ARMv7s". Note that your app will still be able to run on the ARMv7s architecture.

This is happening because our native Raygun4iOS provider is embedded within the Raygun4Net.Xamarin.iOS provider. This is to provide native iOS exception reporting from within your managed Xamarin app. Raygun4iOS is developed with XCode, which no longer includes ARMv7s in the list of standard architectures. ARMv7s only provides some small performance improvements over ARMv7, but since each architecture supported by a framework increases the size of the framework, it is not worth supporting it.

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Xamarin for Mac

Documentation - Xamarin.Mac - Error & Crash Reporting

Setup instructions

1. Download and reference the dll

Xamarin for Mac support is not included in the NuGet package or the Raygun4Net Xamarin Component. Instead, download the .zip of assemblies from the latest release on GitHub:https://github.com/MindscapeHQ/raygun4net/releases (Click the green button). Then copy and reference the Mindscape.Raygun4Net.Xamarin.Mac.dll or the Mindscape.Raygun4Net.Mac.Unified.dll into your Xamarin.Mac project.

2. Attach the RaygunClient

In the main entry point of your application, call the static RaygunClient.Attach method with your app API key. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

using Mindscape.Raygun4Net;
static void Main(string[] args)
{
  RaygunClient.Attach("YOUR_APP_API_KEY");

  NSApplication.Init();
  NSApplication.Main(args);
}

Raygun4Net will now automatically detect and send all unhandled exceptions to your Raygun account where you can view all of your error monitoring and crash reporting data.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

RaygunClient provides Send and SendInBackground methods for manually sending to Raygun. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  RaygunClient.Current.SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party libraries) or due to issues that cannot be solved. In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This code extends upon the setup instructions detailed above.

static void Main(string[] args)
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.SendingMessage += RaygunClient_SendingMessage;

  NSApplication.Init();
  NSApplication.Main(args);
}

private static void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
{
  // This is an example of cancelling a message:
  if ("NotImplementedException".Equals(e.Message.Details.Error.ClassName))
  {
    e.Cancel = true;
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This code extends upon the setup instructions detailed above.

static void Main(string[] args)
{
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.CustomGroupingKey += RaygunClient_CustomGroupingKey;

  NSApplication.Init();
  NSApplication.Main(args);
}

private static void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
{
  // This example simply performs pure message based grouping on basic Exception instances:
  if (e.Message.Details.Error.ClassName.Equals("Exception"))
  {
    string key = e.Exception.Message;
    e.CustomGroupingKey = key;
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a couple of ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

RaygunClient.Current.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

RaygunClient.Current.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

RaygunClient.Current.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

RaygunClient.Current.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

By default, Raygun4Net will attempt to send the bundle version of your application with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

RaygunClient.Current.ApplicationVersion = "1.3.37.0";

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

RaygunClient.Current.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default AggregateException and TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances (Which is done by default), all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exceptions (AggregateException and TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

RaygunClient.Current.RemoveWrapperExceptions(typeof(TargetInvocationException));

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Xamarin for Android

Documentation - Xamarin.Android - Error & Crash Reporting

Setup instructions

1. Install the NuGet package or Xamarin Component

Choose the following installation instructions depending on your situation:

NuGet - Visual Studio

Make sure NuGet is installed in Visual Studio, then right-click on your project and select "Manage NuGet Packages..." Make sure you're in the "Online" section in the left hand pane. Then, in the top right search box, search for Mindscape.Raygun4Net and install it.

NuGet - Xamarin Studio

Xamarin Studio has NuGet support built in (Make sure Xamarin Studio is up to date if it's not available). Right-click your project, hover over the "Add" item, then select "Add NuGet Packages..." Check that the top left selector is either showing "All Sources" or "Official NuGet Gallery". Then, in the top right search box, search for Mindscape.Raygun4Net and install it via the "Add Package" button in the bottom right corner.

Xamarin Component - Visual Studio

Right-click on the Components folder in your project and select "Get More Components..." Search for Raygun4Net, click the search result and then install it via the "Add to App" button.

Xamarin Component - Xamarin Studio

Double-click the Components folder in your project and click the "Get More Components" button in the top right corner. Search for Raygun4Net, click the search result and then install it via the "Add to App" button.

2. Attach the RaygunClient

In the main entry Activity of your application, call the static RaygunClient.Attach method with your app API key. Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

using Mindscape.Raygun4Net;
protected override void OnCreate(Bundle bundle)
{
  base.OnCreate(bundle);
  RaygunClient.Attach("YOUR_APP_API_KEY");
  
  // Other OnCreate logic here
}

Raygun4Net will now automatically detect and send all unhandled exceptions to your Raygun account where you can view all of your error monitoring and crash reporting data.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually, such as handled exceptions from within a try/catch block.

RaygunClient provides Send and SendInBackground methods for manually sending to Raygun. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  RaygunClient.Current.SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party libraries) or due to issues that cannot be solved. In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. This code extends upon the setup instructions detailed above.

protected override void OnCreate(Bundle bundle)
{
  base.OnCreate(bundle);
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.SendingMessage += RaygunClient_SendingMessage;

  // Other OnCreate logic here
}

private void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
{
  // This is an example of cancelling a message:
  if ("NotImplementedException".Equals(e.Message.Details.Error.ClassName))
  {
    e.Cancel = true;
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. This code extends upon the setup instructions detailed above.

protected override void OnCreate(Bundle bundle)
{
  base.OnCreate(bundle);
  RaygunClient.Attach("YOUR_APP_API_KEY");
  // Attach the event handler:
  RaygunClient.Current.CustomGroupingKey += RaygunClient_CustomGroupingKey;

  // Other OnCreate logic here
}

private void RaygunClient_CustomGroupingKey(object sender, RaygunCustomGroupingKeyEventArgs e)
{
  // This example simply performs pure message based grouping on basic Exception instances:
  if (e.Message.Details.Error.ClassName.Equals("Exception"))
  {
    string key = e.Exception.Message;
    e.CustomGroupingKey = key;
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a couple of ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

RaygunClient.Current.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

RaygunClient.Current.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

RaygunClient.Current.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

RaygunClient.Current.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

By default, Raygun4Net will attempt to send the package version of your application with each report. If this is unavailable, or if you need to provide your own custom version value, you can do so by setting the ApplicationVersion property of the RaygunClient.

RaygunClient.Current.ApplicationVersion = "1.3.37.0";

Machine name

Getting the machine name requires using the BluetoothAdapter, which in turn requires the appropriate permission to be setup - and so we don't do this in the Raygun4Net provider by default. If you want to capture the machine name, first add the following to your AssemblyInfo:

-[assembly: UsesPermission(Android.Manifest.Permission.Bluetooth)]

Then attach an event handler to the SendingMessage event of a RaygunClient instance. (If you have called the static Attach method, you can get the static RaygunClient instance via RaygunClient.Current). The following is an example handler that fetches the machine name and sets it on the Raygun message:

private void RaygunClient_SendingMessage(object sender, RaygunSendingMessageEventArgs e)
{
  BluetoothAdapter adapter = BluetoothAdapter.DefaultAdapter;
  e.Message.Details.MachineName = adapter == null ? "Unknown" : adapter.Name;
}

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

RaygunClient.Current.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default AggregateException and TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances (Which is done by default), all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exceptions (AggregateException and TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

RaygunClient.Current.RemoveWrapperExceptions(typeof(TargetInvocationException));

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

ASP .NET Core

Documentation - Raygun4Net - ASP.NET Core Error Tracking & Reporting

Setup instructions

1. Install the NuGet package

The best way to install Raygun4Net.AspNetCore is to use the NuGet package manager. With the NuGet Visual Studio extension installed, right-click on your project and select "Manage NuGet Packages..." Make sure "Online" is highlighted in the left hand pane, then use the top right search box to find Mindscape.Raygun4Net.AspNetCore and install it.

Another method is to directly edit your project.json file and add "Mindscape.Raygun4Net.AspNetCore": "5.5.0.0" to your dependencies. After you've done this, run dotnet.exe restore or restore packages within Visual Studio to download and install the package.

Alternatively, visit https://nuget.org/packages/Mindscape.Raygun4Net.WebApi/ for instructions on installation using the package manager console.

2. Setup Raygun in appsettings.json

Add the following code to your appsettings.json (if you're using another type of config, add it there):

"RaygunSettings": {
  "ApiKey": "YOUR_APP_API_KEY"
}

Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings. RaygunSettings has many options which are explained further down this page.

3. Configure the RaygunAspNetCoreMiddleware

To configure the RaygunAspNetCoreMiddleware to handle exceptions that have been triggered and send unhandled exceptions automatically.

In Startup.cs:

  1. Add using Mindscape.Raygun4Net; to your using statements.
  2. Add app.UseRaygun(); to the Configure method after any other ExceptionHandling methods e.g. app.UseDeveloperExceptionPage() or app.UseExceptionHandler("/Home/Error").
  3. Add services.AddRaygun(Configuration); to the ConfigureServices method.
using Mindscape.Raygun4Net;
public class Startup
{
  public void ConfigureServices(IServiceCollection services)
  {
    // Add framework services.
    services.AddMvc();
    services.AddRaygun(Configuration);
  }

  public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
  {
    app.UseExceptionHandler("/Home/Error");
    app.UseRaygun();
    app.UseStaticFiles();
    app.UseMvc(routes =>
    {
      routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
    });
  }
}

The above set up will cause all unhandled exceptions to be sent to your Raygun account where you can easily view all of your error monitoring and crash report data.

Manually sending exceptions

The above instructions will setup Raygun4Net to automatically detect and send all unhandled exceptions. Sometimes you may want to send exceptions manually - such as handled exceptions from within a try/catch block.

To manually send exceptions, create an instance of the RaygunClient class.

With the RaygunClient, you can call either the Send or SendInBackground methods. It's important to note that SendInBackground should only be used for handled exceptions, rather than exceptions that will cause the application to crash - otherwise the application will most likely shutdown all threads before Raygun is able to finish sending. Both the Send and SendInBackground methods have many overloads for sending additional data which are explained in the various feature sections below.

Here's an example of manually sending exceptions from a try/catch block:

try
{
  // Do something here that might go wrong
}
catch (Exception e)
{
  new RaygunClient("YOUR_APP_API_KEY").SendInBackground(e);
}

Throw exceptions to avoid missing stack traces

Sometimes you may have code that detects that something has gone wrong, but doesn't actually throw an exception. If you want to log this to Raygun, it is tempting to just create a new exception instance and pass it through one of the RaygunClient send methods. Note however that a .NET exception needs to be thrown in order for its stack trace to be populated. So whenever you want to send a new exception instance to Raygun, make sure you are throwing the exception, then catch and send it from within a try/catch block as in the code example above. This will ensure that you log the stack trace which is useful for you to debug, and is used by Raygun to group exceptions.

Configure RaygunClient or settings in RaygunAspNetCoreMiddleware

The AddRaygun method has an overload that takes a RaygunMiddlewareSettings object. These settings control the middleware (not to be confused with RaygunSettings which are the common settings we use across all of our .NET providers). Currently there's just one property on it, ClientProvider. This gives you a hook into the loading of RaygunSettings and the construction of the RaygunAspNetCoreClient used to send errors.

For example, say you want to set user details on your error reports. You'd create a custom client provider like this:

using Microsoft.AspNetCore.Http;
using Mindscape.Raygun4Net;
using Mindscape.Raygun4Net.Messages;
using System.Linq;
using System.Security.Claims;

public class ExampleRaygunAspNetCoreClientProvider : DefaultRaygunAspNetCoreClientProvider
{
  public override RaygunClient GetClient(RaygunSettings settings, HttpContext context)
  {
    var client = base.GetClient(settings, context);

    var identity = context?.User?.Identity as ClaimsIdentity;
    if (identity?.IsAuthenticated == true)
    {
      var email = identity.Claims.Where(c => c.Type == ClaimTypes.Email).Select(c => c.Value).FirstOrDefault();

      client.UserInfo = new RaygunIdentifierMessage(email)
      {
        IsAnonymous = false,
        Email = email,
        FullName = identity.Name
      };
    }

    return client;
  }
}

Then you would change your services.AddRaygun(Configuration) call in ConfigureServices to this:

services.AddRaygun(Configuration, new RaygunMiddlewareSettings()
{
  ClientProvider = new ExampleRaygunAspNetCoreClientProvider()
});

Manually sending exceptions with a custom ClientProvider

When configuring a custom ClientProvider you will also want to leverage this ClientProvider to get an instance of the RaygunClient when manually sending an exception. To do this use the Dependency Injection framework to provide an instance of the IRaygunAspNetCoreClientProvider and IOptions to your MVC Controller. This will then ensure that the Raygun crash report also contains any HttpContext information and will execute any code defined in your ClientProvider.GetClient() method.

public class RaygunController : Controller
{
  private readonly IRaygunAspNetCoreClientProvider _clientProvider;
  private readonly IOptions<RaygunSettings> _settings;

  public RaygunController(IRaygunAspNetCoreClientProvider clientProvider, IOptions<RaygunSettings> settings)
  {
    _clientProvider = clientProvider;
    _settings = settings;
  }

  public async Task TestManualError()
  {
    try
    {
      throw new Exception("Test from .NET Core MVC app");
    }
    catch (Exception ex)
    {
      var raygunClient = _clientProvider.GetClient(_settings.Value, HttpContext);
      await raygunClient.SendInBackground(ex);
    }

    return View();
  }
}

Modify or cancel messages

On a RaygunClient instance, attach an event handler to the SendingMessage event. This event handler will be called just before the RaygunClient sends an exception report - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. There are two different uses for this event handler:

  • Modify the message. You can make any changes you want to the RaygunMessage object such as removing, adding or changing values. Any changes that you make will affect the exception report that gets sent to Raygun.
  • Cancel the message. Sometimes you may get exceptions from parts of the application that you have no control over (such as 3rd party plugins) or due to issues that cannot be solved (such as various bot attacks). In this event handler, you can look through the properties of the RaygunMessage to determine if the exception is one that you don't care about. If so, you can then set e.Cancel = true to prevent Raygun4Net from sending it.

Here is an example of cancelling a message. Notice that this code uses the technique described above of configuring the RaygunMiddlewareSettings with a custom client provider.

public class ExampleRaygunAspNetCoreClientProvider : DefaultRaygunAspNetCoreClientProvider
{
  public override RaygunClient GetClient(RaygunSettings settings, HttpContext context)
  {
    var client = base.GetClient(settings);
    client.SendingMessage += (sender, args) =>
    {
      // This is an example of cancelling a message:
      if ("BadServer".Equals(args.Message.Details.MachineName))
      {
        args.Cancel = true;
      }
    };
    return client;
  }
}

Note that if an exception occurs within your SendingMessage event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Custom grouping

When exception reports are sent to Raygun, they get grouped using our classification logic. We improve this logic every now and then, but sometimes you may come across scenarios where exceptions reports are grouped together or put into separate groups where you were not expecting. This can be from cases we are not yet handling, scenarios that are specific to your application, or unique grouping preferences you have. Raygun4Net lets you provide your own custom grouping logic before exceptions are sent to Raygun.

To use the custom grouping key feature, start by getting the RaygunClient instance used to send your exception reports and attach an event handler to the CustomGroupingKey event. This event gets fired before the SendingMessage event described in the section above. The event arguments provide both the original Exception object and the RaygunMessage object that is about to be sent. In the event handler, you can use whatever logic you want to build a grouping key (string) for the given exception. When the key is ready, set it to the CustomGroupingKey property of the event arguments. Exceptions that end up with the same key will be grouped together. Grouping keys have a limit of 100 characters.

Unless you have extreme grouping logic that needs to be applied to all exceptions, we recommend that you only apply custom grouping logic to scenarios that we are not handling for you. You can include checks in your event handler for certain types of exceptions for example, and only create a custom grouping key for them. Exceptions that you don't provide a custom grouping key for will be grouped in Raygun using the grouping classifiers we provide.

Here is an example of providing a custom grouping key. Notice that this code uses the technique described above of configuring the RaygunMiddlewareSettings with a custom client provider.

public class ExampleRaygunAspNetCoreClientProvider : DefaultRaygunAspNetCoreClientProvider
{
  public override RaygunClient GetClient(RaygunSettings settings, HttpContext context)
  {
    var client = base.GetClient(settings);
    client.CustomGroupingKey += (sender, args) =>
    {
      // This example simply performs pure message based grouping on basic Exception instances:
      if (args.Message.Details.Error.ClassName.Equals("Exception"))
      {
        string key = args.Exception.Message;
        args.CustomGroupingKey = key;
      }
    };
    return client;
  }
}

Note that if an exception occurs within your CustomGroupingKey event handler, Raygun4Net will detect this and send the new exception as well as the original exception that was being processed. When processing the new exception, the event handler will not be called again in order to avoid an infinite loop.

Exclude errors by HTTP status code

You can exclude errors by their HTTP status code by providing an array of status codes to ignore in the configuration. For example if you wanted to exclude errors that return the I'm a teapot response code, you could use this configuration:

"RaygunSettings": {
  "ApiKey": "YOUR_APP_API_KEY",
  "ExcludedStatusCodes": [418]
}

Exclude errors that originate from a local origin

To prevent Raygun4Net from sending exceptions that originate from a local origin (your debug/development machine), set the ExcludeErrorsFromLocal setting to true as seen in the code below. This is useful if you find that everyone in your team sending exceptions from their local machines is noisy and pointless. This option is a convenient alternative to using transforms to do the same thing.

"RaygunSettings": {
  "ApiKey": "YOUR_APP_API_KEY",
  "ExcludeErrorsFromLocal": true
}

Remove sensitive request data

By default, Raygun4Net will send all form-fields and headers in the current HTTP request. If you have sensitive data in an HTTP request that you wish to prevent being transmitted to Raygun, you can provide a list of possible named values to remove:

"RaygunSettings": {
  "ApiKey": "YOUR_APP_API_KEY",
  "IgnoreFormFieldNames": ["password","creditcard","cv2"]
}

Three attributes are available, to remove values from these properties:

  • IgnoreFormFieldNames (ignores values from HttpRequest.Form)
  • IgnoreHeaderNames (ignores values from HttpRequest.Headers)
  • IgnoreCookieNames (ignores values from HttpRequest.Cookies)

Or specify them in code with the following multi-parameter method:

raygunClient.IgnoreFormFieldNames("password", "creditcard", "cv2");

Setting any of these options to * will cause Raygun4Net to ignore all values in that category, so none of them are sent to Raygun.io. Also, by placing * before, after or at both ends of a name, Raygun4Net will use that as an ends-with, starts-with or contains condition respectively when determining what to ignore.

Unique user tracking

Providing user information will allow your Raygun dashboard to display the number of unique users that each error or crash has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each error. If available, you could provide an ID that is meaningful to you such as a database ID. This could help you to look up information at your end that aids in solving issues. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

There are a couple of ways to provide user information, the simplest of which is to set the User property of the RaygunClient instance to an identifier of your choosing:

raygunClient.User = "user@email.com";

If a single identifier string isn't enough, you can set the UserInfo property instead to provide more information:

raygunClient.UserInfo = new RaygunIdentifierMessage("user@email.com")
{
  IsAnonymous = false,
  FullName = "Robbie Robot",
  FirstName = "Robbie"
};

Here are all the available RaygunIdentifierMessage properties:

  • Identifier (passed into the constructor) is the unique identifier from your system for this user.
  • IsAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • Email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • FullName The user's full name.
  • FirstName The user's first (or preferred) name.
  • UUID A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

Tags

An overload of Send and SendInBackground allows you to include a list of tags with each manually sent exception:

raygunClient.Send(exception, new List<string>() { "tag1", "tag2" });

Exceptions can be searched in your Raygun dashboard by tags that you've included.

Custom data

You can include key-value custom data using an overload of the Send or SendInBackground method. Values can be primitive types or rich object structures. All properties of objects and their children will be sent to Raygun. Cyclic object references will be detected and handled as appropriate, and any property getter that produces an exception will cause that property value to be displayed as the exception message.

raygunClient.Send(exception, null, new Dictionary<string, object>() { { "key", "value" } });

The second parameter is the list of tags (mentioned above) which can be null if you don't have tags for the current exception.

Version numbering

You can provide an application version value by setting the ApplicationVersion property of the RaygunClient

raygunClient.ApplicationVersion = "1.3.37.0";

Alternatively, you can set the applicationVersion in configuration as follows. If both are set, the property mentioned above takes precedence over the configuration setting.

"RaygunSettings": {
  "ApiKey": "YOUR_APP_API_KEY",
  "ApplicationVersion": "1.3.37.0"
}

Stripping wrapper exceptions

If you have common outer exceptions that wrap a valuable inner exception which you'd prefer to group by, you can specify these by using the following multi-parameter method:

raygunClient.AddWrapperExceptions(typeof(MyWrapperException));

The above example will cause MyWrapperException instances to be stripped away and never sent to Raygun. Instead, only the inner exception of any stripped exceptions will be sent. By default TargetInvocationException will always be stripped - see below to override this behavior.

AggregateException support

AggregateException is a special case as they can hold multiple inner exceptions. By stripping AggregateException instances using the method described above, all inner exceptions will be sent to Raygun as separate exception reports. That way, each inner exception can be put into the appropriate individual groups and managed separately.

Prevent wrapper exception stripping

If you want to prevent Raygun4Net from stripping the default wrapper exception (TargetInvocationException) then you can call the multi-parameter RemoveWrapperExceptions method as shown below. This can also be useful if you've used the above instructions to cause Raygun4Net to strip a wrapper exception type that you later don't want to strip within a single execution of the app.

raygunClient.RemoveWrapperExceptions(typeof(TargetInvocationException));

Proxy settings

The Raygun4Net provider uses the default Windows proxy settings (as set in Internet Explorer's Connection tab) when sending messages to Raygun. Unfortunately we don't support setting a proxy server or proxy credentials by configuration yet. 

Source code

If you want to see how Raygun4Net works, or you need to make your own modifications, you can find all the source code in this GitHub repository.

Documentation missing?

If we don't have documentation about your desired topic, send us a message and we'll create it for you.