ASP.NET Core

Sentry provides an integration with ASP.NET Core through the Sentry.AspNetCore NuGet package.

Overview of the features

• Easy ASP.NET Core integration, single line: UseSentry
• Captures unhandled exceptions in the middleware pipeline
• Captures exceptions handled by the framework UseExceptionHandler and Error page display
• Captures process-wide unhandled exceptions (AppDomain)
• Captures LogError or LogCritical
• Any event sent will include relevant application log messages
• RequestId as tag
• URL as tag
• Environment is automatically set (IHostingEnvironment)
• Release automatically set (AssemblyInformationalVersionAttribute, AssemblyVersion or environment variable)
• Request payload can be captured if opt-in
• Support for EventProcessors registered with DI
• Support for ExceptionProcessors registered with DI
• Supports configuration system (bind to SentryAspNetCoreOptions)
• Server OS info sent
• Server Runtime info sent
• Request headers sent
• HTTP Proxy configuration
• Request body compressed
• Event flooding protection (429 retry-after and internal bound queue)
• Assembly Strong named
• Tested on Windows, Linux and macOS
• Tested on .NET Core, .NET Framework and Mono

Install

Add the Sentry dependency:

Install-Package Sentry.AspNetCore -Version 4.9.0

This package extends Sentry.Extensions.Logging. This means that besides the ASP.NET Core related features, through this package you'll also get access to all the framework's logging integration and also the features available in the main Sentry SDK.

Configure

The simplest way to configure the Sentry.AspNetCore package is not by calling SentrySdk.Init directly but rather using the extension method UseSentry to the WebHostBuilder in combination with the framework's configuration system. The configuration values bind to SentryAspNetCoreOptions which extends SentryLoggingOptions from the Sentry.Extensions.Logging and further extends SentryOptions from the Sentry package.

This means all options for the inner packages are available to be configured through the configuration system.

When using WebHost.CreateDefaultBuilder, the framework automatically loads appsettings.json and environment variables, binding to SentryAspNetCoreOptions.

For example:

  "Sentry": {
    "Dsn": "https://examplePublicKey@o0.ingest.sentry.io/0",
    "MaxRequestBodySize": "Always",
    "SendDefaultPii": true,
    "MinimumBreadcrumbLevel": "Debug",
    "MinimumEventLevel": "Warning",
    "AttachStackTrace": true,
    "Debug": true,
    "DiagnosticsLevel": "Error"
  },

An example of some of the options that can be configured via appsettings.json.

It's also possible to bind properties to the SDK via environment variables, like:

Windows

set Sentry__Debug=true

Linux or macOS

export Sentry__Debug=true

ASP.NET Core will automatically read this environment variable and bind it to the SDK configuration object.

When configuring the SDK via the frameworks configuration system, it's possible to add the SDK by simply calling UseSentry without providing any further information:

ASP.NET Core 2.x:

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        // Add the following line:
        .UseSentry()

ASP.NET Core 3.0:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            // Add the following line:
            webBuilder.UseSentry();
        });

Some of the settings require actual code. For those, like the BeforeSend callback you can simply:

.UseSentry(options =>
{
    options.BeforeSend = @event =>
    {
        // Never report server names
        @event.ServerName = null;
        return @event;
    };
})

Example modifying all events before they are sent to avoid server names being reported.

Dependency Injection

Much of the behavior of the ASP.NET Core integration with Sentry can be customized by using the frameworks dependency injection system. That is done by registering your own implementation of some of the exposed abstraction.

Lifetimes

The lifetime used will be respected by the SDK. For example, when registering a Transient dependency, a new instance of the processor is created for each event sent out to Sentry. This allows the use of non thread-safe event processors.

Capturing the affected user

When opting-in to SendDefaultPii, the SDK will automatically read the user from the request by inspecting HttpContext.User. Default claim values like NameIdentifier for the Id will be used.

If you wish to change the behavior of how to read the user from the request, you can register a new IUserFactory into the container:

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<IUserFactory, MyUserFactory>();
}

Adding event and exception processors

Event processors and exception processors can be added via DI:

public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<ISentryEventProcessor, MyEventProcessor>();
    services.AddScoped<ISentryEventExceptionProcessor, MyExceptionProcessor>();
}

Options and Initialization

As previously mentioned, this package is a wrapper around Sentry.Extensions.Logging and Sentry. Please refer to the documentation of these packages to get the options that are defined at those levels.

Below, the options that are specific to Sentry.AspNetCore will be described.

SendDefaultPii

Although this setting is part of the Sentry package, in the context of ASP.NET Core, it means reporting the user by reading the frameworks HttpContext.User. The strategy to create the SentryUser can be customized. Please read retrieving user info for more.

Environment

The environment name is automatically populated by reading the frameworks IHostingEnvironment value.

This option is part of the Sentry package. The value of IHostingEnvironment will only be used if no other method was used.

Methods that take precedence over IHostingEnvironment are:

• Programmatically: options.Environment
• Environment variable SENTRY_ENVIRONMENT
• Configuration system like appsettings.json

MaxRequestBodySize

This parameter controls whether integrations should capture HTTP request bodies. It can be set to one of the following values:

• None: Request bodies are never sent.
• Small: Only small request bodies will be captured. The cutoff for small depends on the SDK (typically 4KB).
• Medium: Medium and small requests will be captured (typically 10KB).
• Always: The SDK will always capture the request body as long as Sentry can make sense of it.

If the request bodies should be captured, all requests will have the EnableRewind method invoked. This is done so that the request data can be read later, in case an error happens while processing the request.

IncludeActivityData

Opt-in to capture values from System.Diagnostic.Activity if one exists.

Samples

• A simple example without MVC. (C#)
• An example using MVC and most of the SDK features. (C#)
• An example using Giraffe on top of ASP.NET Core with a basic overview of available features. (F#)
• For more samples of the .NET SDKs.