Mindscape.Raygun4Net.AspNetCore 11.0.0

dotnet add package Mindscape.Raygun4Net.AspNetCore --version 11.0.0
NuGet\Install-Package Mindscape.Raygun4Net.AspNetCore -Version 11.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Mindscape.Raygun4Net.AspNetCore" Version="11.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Mindscape.Raygun4Net.AspNetCore --version 11.0.0
#r "nuget: Mindscape.Raygun4Net.AspNetCore, 11.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Mindscape.Raygun4Net.AspNetCore as a Cake Addin
#addin nuget:?package=Mindscape.Raygun4Net.AspNetCore&version=11.0.0

// Install Mindscape.Raygun4Net.AspNetCore as a Cake Tool
#tool nuget:?package=Mindscape.Raygun4Net.AspNetCore&version=11.0.0

Raygun4Net.AspNetCore - Raygun Provider for ASP.NET Core projects

Where is my app API key?

When you create a new application on your Raygun dashboard, your app API key is displayed at the top of the instructions page. You can also find the API key by clicking the "Application Settings" button in the side bar of the Raygun dashboard.

Namespace

The main classes can be found in the Mindscape.Raygun4Net namespace.

Setup & Usage

In your ASP.NET Core project, add the Raygun4Net.AspNetCore package to your project.

Add Raygun to your services:

public void ConfigureServices(IServiceCollection services)
{
  // Assumes you're configuring Raygun in appsettings.json
  services.AddRaygun(Configuration);
  
  // Or if you're configuring Raygun in code
  services.AddRaygun(settings =>
  {
    settings.ApiKey = "YOUR_APP_API_KEY";
    ...
  });
}

Add Raygun to your middleware:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
  // This should be registered early in the pipeline to catch all exceptions
  app.UseRaygun();
}

If you're configuring using appsettings.json, add the following to your appsettings.json file:

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

Manually sending exceptions

After using services.AddRaygun(...), you can inject RaygunAgent into your controllers and use it to send exceptions manually.

public class MyController : Controller
{
  private readonly RaygunAgent _raygunAgent;

  public MyController(RaygunAgent raygunAgent)
  {
    _raygunAgent = raygunAgent;
  }

  public async Task<IActionResult> TestManualError()
  {
    try
    {
      throw new Exception("Test from .NET Core MVC app");
    }
    catch (Exception ex)
    {
      await _raygunAgent.SendInBackground(ex);
    }

    return View();
  }
}

Custom User Provider

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

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

Additional configuration options and features

The following features can be configured in the appsettings.json file or in code.

For example, in the appsettings.json file:

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

The equivalent in code:

services.AddRaygun(settings =>
{
  settings.ApiKey = "YOUR_APP_API_KEY";
  settings.ExcludeErrorsFromLocal = true;
  ...
});

Examples below are shown in appsettings.json format.

Replace unseekable request streams

Raygun will try to send the raw request payload with each exception report where applicable, but this is only possible with request streams that are seekable. If you are not seeing any raw request payloads in your exception reports where you'd expect to see them, then you can set the ReplaceUnseekableRequestStreams setting to true in your appsettings.json. This will attempt to replace any unseekable streams with a seekable copy on the request object so that Raygun can later read the raw request payload.

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

This setting is false by default to avoid breaking changes or any unforseen issues with its initial deployment.

Raygun will not attempt to send raw request payloads for GET requests, "x-www-form-urlencoded" requests or "text/html" requests.

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 (http://tools.ietf.org/html/rfc2324), you could use the configuration below.

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

Exclude errors that originate from a local origin

Toggle this boolean and Raygun will not send errors if the request originated from a local origin. i.e. A way to prevent local debug/development from notifying Raygun without having to resort to Web.config transforms.

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

Remove sensitive request data

If you have sensitive data in an HTTP request that you wish to prevent being transmitted to Raygun, you can provide lists of possible keys (names) to remove. Keys to ignore can be specified on the RaygunSettings in appsettings.json, or on the RaygunSettings when you create the RaygunClient or call services.AddRaygun(settings => {...}); The available options are:

  • IgnoreSensitiveFieldNames
  • IgnoreQueryParameterNames
  • IgnoreFormFieldNames
  • IgnoreHeaderNames
  • IgnoreCookieNames
  • IgnoreServerVariableNames

These can be set to an array of keys to ignore. Setting an option as * will indicate that all the keys will not be sent to Raygun. Placing * before, after or at both ends of a key will perform an ends-with, starts-with or contains operation respectively. For example, IgnoreFormFieldNames: ["*password*"] will cause Raygun to ignore all form fields that contain "password" anywhere in the name. These options are not case sensitive.

Note: The IgnoreSensitiveFieldNames will be applied to ALL fields in the RaygunRequestMessage.

We provide extra options for removing sensitive data from the request raw data. This comes in the form of filters as implemented by the IRaygunDataFilter interface. These filters read the raw data and strip values whose keys match those found in the RaygunSettings IgnoreSensitiveFieldNames property.

We currently provide two implementations with this provider.

RaygunKeyValuePairDataFilter e.g. filtering "user=raygun&password=pewpew"

RaygunXmlDataFilter e.g. filtering "<password>pewpew</password>"

These filters are initially disabled and can be enbled through the RaygunSettings class. You may also provide your own implementation of the IRaygunDataFilter and pass this to the RaygunClient to use when filtering raw data. An example for implementing an JSON filter can be found at the end of this readme.

Modify or cancel message

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 - either automatically or manually. The event arguments provide the RaygunMessage object that is about to be sent. One use for this event handler is to add or modify any information on the RaygunMessage. Another use for this method is to identify exceptions that you never want to send to raygun, and if so, set e.Cancel = true to cancel the send.

Strip 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 multi-parameter method:

RaygunClient.AddWrapperExceptions(typeof(TargetInvocationException));

In this case, if a TargetInvocationException occurs, it will be removed and replaced with the actual InnerException that was the cause. Note that TargetInvocationException is already added to the wrapper exception list; you do not have to add this manually. This method is useful if you have your own custom wrapper exceptions, or a framework is throwing exceptions using its own wrapper.

Unique (affected) user tracking

There are properties named User and UserInfo on RaygunClient which you can set to provide user info such as ID and email address This allows you to see the count of affected users for each error in the Raygun dashboard. If you provide an email address, and the user has an associated Gravatar, you will see their avatar in the error instance page.

Make sure to abide by any privacy policies that your company follows when using this feature.

Version numbering

You can provide an application version value by setting the ApplicationVersion property of the RaygunClient (in the format x.x.x.x where x is a positive integer).

Tags and custom data

When sending exceptions manually, you can also send an arbitrary list of tags (an array of strings), and a collection of custom data (a dictionary of any objects). This can be done using the various Send and SendInBackground method overloads.

Example JSON Data Filter

using System;
using System.Linq;
using System.Collections.Generic;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Mindscape.Raygun4Net.Filters;

public class RaygunJsonDataFilter : IRaygunDataFilter
{
  private const string FILTERED_VALUE = "[FILTERED]";

  public bool CanParse(string data)
  {
    if (!string.IsNullOrEmpty(data))
    {
      int index = data.TakeWhile(c => char.IsWhiteSpace(c)).Count();
      if (index < data.Length)
      {
        if (data.ElementAt(index).Equals('{'))
        {
          return true;
        }
      }
    }
    return false;
  }

  public string Filter(string data, IList<string> ignoredKeys)
  {
    try
    {
      JObject jObject = JObject.Parse(data);

      FilterTokensRecursive(jObject.Children(), ignoredKeys);

      return jObject.ToString(Formatting.None, null);
    }
    catch
    {
      return null;
    }
  }

  private void FilterTokensRecursive(IEnumerable<JToken> tokens, IList<string> ignoredKeys)
  {
    foreach (JToken token in tokens)
    {
      if (token is JProperty)
      {
        var property = token as JProperty;

        if (ShouldIgnore(property, ignoredKeys))
        {
          property.Value = FILTERED_VALUE;
        }
        else if (property.Value.Type == JTokenType.Object)
        {
          FilterTokensRecursive(property.Value.Children(), ignoredKeys);
        }
      }
    }
  }

  private bool ShouldIgnore(JProperty property, IList<string> ignoredKeys)
  {
    bool hasValue = property.Value.Type != JTokenType.Null;

    if (property.Value.Type == JTokenType.String)
    {
      hasValue = !string.IsNullOrEmpty(property.Value.ToString());
    }

    return hasValue && !string.IsNullOrEmpty(property.Name) && ignoredKeys.Any(f => f.Equals(property.Name, StringComparison.OrdinalIgnoreCase));
  }
}
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (7)

Showing the top 5 NuGet packages that depend on Mindscape.Raygun4Net.AspNetCore:

Package Downloads
Hochfrequenz.sharedAzureHelper

Helper classes to interact with Hochfrequenzes azure services

NLog.Raygun

A custom NLog target that will push exceptions to Raygun

LoggingAbstractor.Raygun

Logging Abstractor is a library for .NET that allows you to swap out logging providers with ease.

Serilog.Sinks.Raygun.AspNetCore

A Serilog sink that writes events to Raygun using the MindscapeHQ AspNetCore library

Xamariners.Functions.Core

Xamariners.Functions.Core is a library of common classes and helpers for Azure functions.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
11.0.0 871 6/9/2024
11.0.0-rc1 60 6/7/2024
11.0.0-pre3 63 5/30/2024
11.0.0-pre2 79 5/24/2024
11.0.0-pre1 74 5/23/2024
10.1.2 7,895 5/9/2024
10.1.2-pre-1 75 5/9/2024
10.1.1 11,962 3/27/2024
10.1.1-pre-1 109 3/20/2024
10.1.0 1,896 3/18/2024
10.1.0-pre-2 102 3/18/2024
10.1.0-pre-1 117 3/15/2024
10.0.0 1,341 3/13/2024
10.0.0-pre-6 111 3/12/2024
10.0.0-pre-5 117 3/12/2024
10.0.0-pre-4 1,396 2/23/2024
10.0.0-pre-2 158 2/23/2024
10.0.0-pre-1 158 2/22/2024
9.0.4 19,289 3/3/2024
9.0.4-pre-1 2,716 2/29/2024
9.0.3 7,670 2/27/2024
9.0.2 3,549 2/22/2024
9.0.2-pre-1 152 2/19/2024
9.0.1 4,908 2/8/2024
9.0.0-pre3 185 2/7/2024
9.0.0-pre-1 150 2/2/2024
8.3.0-pre1 1,827 1/26/2024
8.1.0-pre3 165 1/9/2024
8.0.1 22,615 11/28/2023
8.0.1-pre-1 184 11/27/2023
8.0.0 5,341 11/14/2023
8.0.0-pre-1 226 11/9/2023
7.1.0 18,899 10/9/2023
7.1.0-pre-1 180 9/22/2023
7.0.0 25,391 9/12/2023
6.7.2 31,832 9/6/2023
6.7.1 816 9/6/2023
6.7.0-pre2 177 8/21/2023
6.6.6 755,224 4/8/2022
6.6.5 240,526 3/2/2022
6.6.4 2,903 2/28/2022
6.6.3 2,029 2/23/2022
6.6.2 631,979 9/2/2021
6.6.1 2,990 8/30/2021
6.6.0 512 8/30/2021
6.5.0 208,310 4/15/2021
6.4.1 135,193 12/2/2020
6.4.0 878,629 10/1/2020
6.3.1 109,011 8/17/2020
6.3.0 90,397 6/30/2020
6.2.1-beta1 2,105 2/13/2020
6.2.0 835,451 10/9/2019
6.1.0 526,566 4/11/2019
6.0.1 354,157 10/4/2018
6.0.0 379,653 5/28/2018
5.5.0 923,434 5/16/2017
5.3.2 40,485 8/23/2016
5.3.1 2,728 7/22/2016