1. Home
  2. Language Guides
  3. .NET
  4. Crash Reporting
  5. ASP.NET

ASP.NET

This provider is compatible with the following frameworks:

  • ASP.NET (Core) WebAPI
  • ASP.NET (Core) MVC

See ASP.NET Framework for the .NET Framework version of these instructions.

Installation

Step 1 - Install the NuGet package

ASP.NET is supported through our Raygun4Net.AspNetCore provider.

The best way to install Raygun4Net.AspNetCore is to use the dotnet CLI tool. Run the following command in your project folder to install it.

dotnet add package Mindscape.Raygun4Net.AspNetCore

Another method is to directly edit your .csproj file and add "Mindscape.Raygun4Net.AspNetCore" to your dependencies.

<ItemGroup>
  <PackageReference Include="Mindscape.Raygun4Net.AspNetCore" Version="6.*" />
</ItemGroup>

After you've done this, run dotnet restore from the command line, or use the Restore NuGet Packages option within Visual Studio to download and install the package.

Alternatively, visit the NuGet package site for instructions on installation.

Step 2 - Set up Raygun in appsettings.json

Add the following code to your appsettings.json or alternative config file:

"RaygunSettings": {
  "ApiKey":  "paste_your_api_key_here"
}

Note: Your app API key is displayed when you create a new application in your Raygun account, or can be viewed in the application settings.

Step 3 - Configure the Raygun Middleware

Configure the Raygun Middleware to handle exceptions that have been triggered and send unhandled exceptions automatically.

In Program.cs:

  1. Add using Mindscape.Raygun4Net.AspNetCore; to your using statements.
  2. Add builder.Services.AddRaygun(builder.Configuration);.
  3. Add app.UseRaygun(); after any other ExceptionHandling methods, e.g., app.UseDeveloperExceptionPage() or app.UseExceptionHandler("/Home/Error").
using Mindscape.Raygun4Net.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRaygun(builder.Configuration);
  
/* The rest of your builder setup */

var app = builder.Build();
app.UseRaygun();

/* The rest of your app setup */

The above setup 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.

Step 4 - Release

For Raygun to capture unhandled exceptions, you will need to run your application in Production mode (dotnet run --environment Production). This way, unhandled exceptions will not be passed to the Development exception handler. You can also raise a test exception like so:

app.MapGet("/throw", (Func<string>)(() => throw new Exception("Exception in request pipeline")));

Once we detect your first error event, the Raygun app will automatically update.

Optional - Enhance your logging with Raygun

To fully leverage the capabilities of Raygun, we recommend integrating it into your logging pipeline. By doing so, any time a method like _logger.LogError() is invoked, a report is also dispatched to Raygun. This can be easily achieved by using our Serilog Sinks Raygun provider.

On the first line of the /[Pages|Views]/Shared/_layout.cshtml file, add @inject Microsoft.Extensions.Configuration.IConfiguration Configuration

Then, at the end of the <head> element, add the Raygun4JS CDN fetch script with the API key automatically imported from your app's Configuration.

@inject Microsoft.Extensions.Configuration.IConfiguration Configuration
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>@ViewData["Title"] - razorDemo</title>
    <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
    <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />
    <link rel="stylesheet" href="~/razorDemo.styles.css" asp-append-version="true" />
    <script type="text/javascript">
      !function(a,b,c,d,e,f,g,h){a.RaygunObject=e,a[e]=a[e]||function(){
      (a[e].o=a[e].o||[]).push(arguments)},f=b.createElement(c),g=b.getElementsByTagName(c)[0],
      f.async=1,f.src=d,g.parentNode.insertBefore(f,g),h=a.onerror,a.onerror=function(b,c,d,f,g){
      h&&h(b,c,d,f,g),g||(g=new Error(b)),a[e].q=a[e].q||[],a[e].q.push({
      e:g})}}(window,document,"script","//cdn.raygun.io/raygun4js/raygun.min.js","rg4js");
    </script>
    <script type="text/javascript">
      rg4js('apiKey', '@Configuration["RaygunSettings:ApiKey"]');
      rg4js('enableCrashReporting', true);
      rg4js('enableRUM', true); <!-- Optional, enable Real User Monitoring -->
    </script>
</head>
<body>
<!-- The rest of the body  -->
</body>

If you want to include the logged-in user's details, they can populated from the HttpContext.User object.

To do this, add @using System.Security.Claims to the top of the _layout.cshtml file, then update the Raygun4JS fetch script at the end of the <head> element to include the rg4js('setUser', {...}); section below:

<script type="text/javascript">
  rg4js('apiKey', '@Configuration["RaygunSettings:ApiKey"]');
  rg4js('enableCrashReporting', true);
  rg4js('enableRUM', true); <!-- Optional, enable Real User Monitoring -->
  rg4js('setUser', {
        identifier: @ViewContext.HttpContext?.User?.FindFirstValue(ClaimTypeNameIdentifier),
        isAnonymous: @(!(ViewContext.HttpContext?.User?.Identity?.IsAuthenticated ??false)),
        email: @ViewContext.HttpContext?.User?.FindFirstValue(ClaimTypes.Email),
        fullName: @ViewContext.HttpContext?.User?.FindFirstValue(ClaimTypes.GivenName),
    });
</script>

Depending on your authentication model, you may need to adjust what ClaimTypes you use.

For more front-end configuration options, visit our JavaScript provider's Advanced Features documentation.

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

Ideally, you will have already set up your logging service to send errors to Raygun (this can be accomplished with the Serilog Sinks Raygun provider or a global ILogger implementation), in which case you can manually report exceptions through your logger.

If you are not using a logging service, you can manually send exceptions by creating 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 shut down 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("paste_your_api_key_here").SendInBackground(e);
}

If you are using a singleton RaygunClient, you'll need to manually set the HTTP context (if applicable) before manually sending an exception.

Example:

public class RaygunController : Controller
{
  private readonly RaygunClient _singletonRaygunClient;

  public RaygunController(RaygunClient singletonRaygunClient)
  {
    _singletonRaygunClient = singletonRaygunClient;
  }

  public async Task<IActionResult> TestManualError()
  {
    try
    {
      throw new Exception("Test exception");
    }
    catch (Exception ex)
    {
      _singletonRaygunClient.SetCurrentContext(HttpContext);
      await _singletonRaygunClient.Send(ex);
    }
    return View();
  }
}

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 before catching and sending it. This will ensure that stack traces are included, allowing for better error grouping within Raygun and easier debugging for you.

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.AspNetCore;
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()
});

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 exception");
    }
    catch (Exception ex)
    {
      var raygunClient = _clientProvider.GetClient(_settings.Value, HttpContext);
      await raygunClient.SendInBackground(ex);
    }

    return View();
  }
}

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 for 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, context);
    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.

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 exception reports are grouped together or put into separate groups that 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.

note: 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, context);
    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.

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": "paste_your_api_key_here",
  "ExcludedStatusCodes": [418]
}

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 you are generating pointless noise in the development process. This option is a convenient alternative to using transforms to do the same thing.

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

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": "paste_your_api_key_here",
  "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 true will cause Raygun4Net to ignore all values in that category. 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.

User information enables the Raygun dashboard to track unique users impacted by each error or crash. While you can input any useful data, remember to respect your company's privacy policies. At minimum, input a unique GUID for user impact visibility per error. A database ID, if available, could help in resolving issues. Providing names and contact details allows for direct communication about issue resolution.

By default Raygun4Net ships with a DefaultRaygunUserProvider which will attempt to get the user information from the HttpContext.User object. This is Opt-In which can be added by calling services.AddRaygunUserProvider()

If you want to provide your own implementation of the IRaygunUserProvider you can do so by creating a class that implements the interface and then adding it to the services during configuration using services.AddRaygunUserProvider<MyCustomUserProvider>().

Below is an example user provider that uses the HttpContext.User similar to our DefaultRaygunUserProvider.

public class ExampleUserProvider : IRaygunUserProvider
{
  private readonly IHttpContextAccessor _contextAccessor;
  
  public ExampleUserProvider(IHttpContextAccessor httpContextAccessor)
  {
    _contextAccessor = contextAccessor;
  }
  
  public RaygunIdentifierMessage? GetUser()
  {
    var ctx = _contextAccessor.HttpContext;
    
    if (ctx == null)
    {
      return null;
    }

    var identity = ctx.User.Identity as ClaimsIdentity;
    
    if (identity?.IsAuthenticated == true)
    {
      return new RaygunIdentifierMessage(identity.Name)
      {
        IsAnonymous = false
      };
    
    return null;
  }
}

This can be registered in the services during configuration like so:

services.AddRaygunUserProvider<ExampleUserProvider>();

note: This behaviour is new since Raygun4Net v10.0.0. The previous User and UserInfo properties are marked as obsolete but are still functioning for now.

Here are 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.

note: The string properties on a User have a maximum length of 255 characters. Users that have fields that exceed this amount will not be processed.

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.

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 none apply to the current exception.

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": "paste_your_api_key_here",
  "ApplicationVersion": "1.3.37.0"
}

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 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.

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));

The Raygun4Net provider uses the default Windows proxy settings when sending messages to Raygun. Unfortunately we don't support setting a proxy server or proxy credentials by configuration yet.

The provider is open source and available at the Raygun4Net repository.

On this page: