Mindscape.Raygun4Net.AspNetCore 11.1.2-pre-1

This is a prerelease version of Mindscape.Raygun4Net.AspNetCore.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Mindscape.Raygun4Net.AspNetCore --version 11.1.2-pre-1                
NuGet\Install-Package Mindscape.Raygun4Net.AspNetCore -Version 11.1.2-pre-1                
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.1.2-pre-1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Mindscape.Raygun4Net.AspNetCore --version 11.1.2-pre-1                
#r "nuget: Mindscape.Raygun4Net.AspNetCore, 11.1.2-pre-1"                
#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.1.2-pre-1&prerelease

// Install Mindscape.Raygun4Net.AspNetCore as a Cake Tool
#tool nuget:?package=Mindscape.Raygun4Net.AspNetCore&version=11.1.2-pre-1&prerelease                

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:

dotnet add package Mindscape.Raygun4Net.AspNetCore

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 RaygunClient into your controllers and use it to send exceptions manually.

public class MyController : Controller
{
  private readonly RaygunClient _raygunClient;

  public MyController(RaygunClient raygunClient)
  {
    _raygunClient = raygunClient;
  }

  public async Task<IActionResult> TestManualError()
  {
    try
    {
      throw new Exception("Test from .NET Core MVC app");
    }
    catch (Exception ex)
    {
      await _raygunClient.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>();

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

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
}

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.

Version numbering

By default, Raygun4Net will attempt to set ApplicationVersion from the entry assembly. It is possible to override this by providing a version through RaygunSettings:

"RaygunSettings": {
  "ApplicationVersion": "1.0.0.0"
}

Or

services.AddRaygun(settings =>
{
  settings.ApplicationVersion = "1.0.0.0";
});

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 SendAsync and SendInBackground method overloads.

Example:

await _raygunClient.SendAsync(ex, new List<string> { "Tag1", "Tag2" }, new Dictionary<string, string> { { "customKey", "value" } });

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:

  1. RaygunKeyValuePairDataFilter e.g. filtering "user=raygun&password=pewpew"
  2. RaygunXmlDataFilter e.g. filtering "<password>pewpew</password>"

These filters are initially disabled and can be enbled through the RaygunSettings class.

services.AddRaygun(settings => 
{
  settings.UseXmlRawDataFilter = true;
  settings.UseKeyValuePairRawDataFilter = true;
  settings.IsRawDataIgnoredWhenFilteringFailed = true;
  settings.RawDataFilters.Add(new RaygunJsonDataFilter()); // Example below
});

You may also provide your own implementation of the IRaygunDataFilter and pass this to the RaygunClient to use when filtering raw data.

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.1.2-pre-2 32 11/12/2024
11.1.2-pre-1 156 9/17/2024
11.1.1 30,007 9/12/2024
11.1.0 11,280 8/25/2024
11.0.4-pre-5 115 8/23/2024
11.0.4-pre-4 109 8/22/2024
11.0.4-pre-2 128 8/15/2024
11.0.4-pre-1 111 8/13/2024
11.0.3 21,089 7/25/2024
11.0.3-pre-1 104 7/22/2024
11.0.2 23,018 6/20/2024
11.0.0 6,782 6/9/2024
11.0.0-rc1 94 6/7/2024
11.0.0-pre3 93 5/30/2024
11.0.0-pre2 113 5/24/2024
11.0.0-pre1 110 5/23/2024
10.1.2 17,272 5/9/2024
10.1.2-pre-1 125 5/9/2024
10.1.1 23,836 3/27/2024
10.1.1-pre-1 138 3/20/2024
10.1.0 2,653 3/18/2024
10.1.0-pre-2 125 3/18/2024
10.1.0-pre-1 145 3/15/2024
10.0.0 1,928 3/13/2024
10.0.0-pre-6 133 3/12/2024
10.0.0-pre-5 139 3/12/2024
10.0.0-pre-4 3,785 2/23/2024
10.0.0-pre-2 179 2/23/2024
10.0.0-pre-1 190 2/22/2024
9.0.4 25,614 3/3/2024
9.0.4-pre-1 2,739 2/29/2024
9.0.3 13,343 2/27/2024
9.0.2 6,164 2/22/2024
9.0.2-pre-1 175 2/19/2024
9.0.1 7,299 2/8/2024
9.0.0-pre3 215 2/7/2024
9.0.0-pre-1 178 2/2/2024
8.3.0-pre1 3,928 1/26/2024
8.1.0-pre3 189 1/9/2024
8.0.1 27,732 11/28/2023
8.0.1-pre-1 214 11/27/2023
8.0.0 7,623 11/14/2023
8.0.0-pre-1 271 11/9/2023
7.1.0 19,962 10/9/2023
7.1.0-pre-1 213 9/22/2023
7.0.0 35,172 9/12/2023
6.7.2 43,611 9/6/2023
6.7.1 1,005 9/6/2023
6.7.0-pre2 203 8/21/2023
6.6.6 866,316 4/8/2022
6.6.5 285,714 3/2/2022
6.6.4 2,937 2/28/2022
6.6.3 2,406 2/23/2022
6.6.2 676,853 9/2/2021
6.6.1 3,025 8/30/2021
6.6.0 564 8/30/2021 6.6.0 is deprecated.
6.5.0 219,367 4/15/2021
6.4.1 139,982 12/2/2020
6.4.0 897,794 10/1/2020
6.3.1 111,445 8/17/2020
6.3.0 95,186 6/30/2020
6.2.1-beta1 2,134 2/13/2020
6.2.0 861,120 10/9/2019
6.1.0 543,565 4/11/2019
6.0.1 358,755 10/4/2018
6.0.0 382,619 5/28/2018
5.5.0 927,603 5/16/2017
5.3.2 40,523 8/23/2016
5.3.1 2,797 7/22/2016