Migration Guide

Upgrading includes both breaking changes and new features.

Migrating to 3.12.0

NuGet Changes

If you're using the Sentry.EntityFramework NuGet package, you must update to at least version 6.2 of the EntityFramework NuGet package.

Migrating from 2.x to 3.x

Breaking Changes

Please read through all breaking changes prior to upgrading.

Grouping Changes

The format of the stack traces were greatly improved with the help of Ben Adam's iconic library Ben.Demystifier. Frames now include details such as async, static, the actual return type, method parameters, tuples and their names, and more.

However, this will affect grouping. If you prefer to stay with the original stack trace format, you can opt-out of this feature with:

options.StackTraceMode = StackTraceMode.Original;

Serialization

In version 3.0.0, the Sentry SDK for .NET changed from Newtonsoft.Json to System.Text.Json. Using the new library has many advantages. These include the lack of an additional dependency (when targeting .NET Core 3, .NET 5, and later versions) and much faster performance.

One breaking change that affects objects set as Context and Extra is that Newtonsoft.Json was previously able to serialize some types, which is not possible with System.Text.Json.

Setting an instance of Exception that was caught in a catch block could fail to serialize, and the event would be dropped by Sentry. This won't break your app, but the error wouldn't make it into Sentry:

 ---> System.NotSupportedException: Serialization and deserialization of 'System.Type' instances are not supported and should be avoided since they can lead to security issues.
   at System.Text.Json.Serialization.Converters.TypeConverter.Write(Utf8JsonWriter writer, Type value, JsonSerializerOptions options)
   at System.Text.Json.Serialization.JsonConverter`1.TryWrite(Utf8JsonWriter writer, T& value, JsonSerializerOptions options, WriteStack& state)
   at System.Text.Json.JsonPropertyInfo`1.GetMemberAndWriteJson(Object obj, WriteStack& state, Utf8JsonWriter writer)
   at System.Text.Json.Serialization.Converters.ObjectDefaultConverter`1.OnTryWrite(Utf8JsonWriter writer, T value, JsonSerializerOptions options, WriteStack& state)
   at System.Text.Json.Serialization.JsonConverter`1.TryWrite(Utf8JsonWriter writer, T& value, JsonSerializerOptions options, WriteStack& state)
   at System.Text.Json.JsonPropertyInfo`1.GetMemberAndWriteJson(Object obj, WriteStack& state, Utf8JsonWriter writer)
   at System.Text.Json.Serialization.Converters.ObjectDefaultConverter`1.OnTryWrite(Utf8JsonWriter writer, T value, JsonSerializerOptions options, WriteStack& state)
   at System.Text.Json.Serialization.JsonConverter`1.TryWrite(Utf8JsonWriter writer, T& value, JsonSerializerOptions options, WriteStack& state)
   at System.Text.Json.Serialization.JsonConverter`1.WriteCore(Utf8JsonWriter writer, T& value, JsonSerializerOptions options, WriteStack& state)

To avoid this issue, pass a serializable object into Sentry. For example, map the instance of Exception to an anonymous object:

try
{
    throw new ArgumentNullException("test");
}
catch (Exception e)
{
    SentrySdk.ConfigureScope(s =>
    {
        s.Contexts["Exception"] = new
        {
            e.Message,
            e.StackTrace,
            e.Data
        };
    });
    SentrySdk.CaptureMessage("Exception in contexts");
}

Namespace Change

Classes under Sentry.Protocol were moved to the root namespace Sentry. All except Context classes like App, Device, etc.

ASP.NET

ASP.NET (not Core) users need to install an additional package, Sentry.AspNet. Without this package, HTTP related information will not be added to events.

You can plug the package into the Init as follows:

SentrySdk.Init(o =>
{
    o.AddAspNet();
});

The motivation was to remove the reference to System.Web and decouple the core of the package from any specific namespaces of the .NET Framework. This change improves the experience from other environments, such as game engines like Unity and Godot.

ASP.NET Core

Environment Casing

To match Sentry's default environment naming convention, unless explicitly set otherwise, the Sentry environment will be reported in lowercase. That means if ASPNET_ENVIRONMENT is equal to Production, the Sentry SDK will report it as production.

Removal of IncludeRequestPayload

The option IncludeRequestPayload that was deprecated in the Sentry SDK 2.0 has been removed. The replacement is the option MaxRequestBodySize.

New Methods on IHub and ISentryClient

Sentry's performance monitoring capabilities requires additive API changes to interfaces such as IHub and ISentryClient. If you implement your own IHub, you'll need to implement two new methods:

ISentryClient received: CaptureTransaction. IHub received: StartTransaction and GetTraceHeader.

Rename of DiagnosticsLogger to DiagnosticLogger

To align with other SDKs, the option is now named: DiagnosticLogger Docs PR.

Dsn as a String

SentryOptions now take a string for Dsn:

Before: o.Dsn = new Dsn(".."); After: o.Dsn = "..";

LogEntry Became Message

The property of SentryEvent that supports a structured log entry was renamed to Message to align with the protocol and other SDKs.

Self-Hosted Support

This version uses the envelope endpoint. If you are using an on-premise installation it requires Sentry version >= v20.6.0 to work. If you are using sentry.io nothing will change and no action is needed.

New Features and Improvements

Offline Caching

You can optionally have events cached to disk. To do so, specify which directory the SDK can use to write crash files:

options.CacheDirectoryPath = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData))

Attachments

You can add attachments to events. Please refer to our Attachments documentation.

User Feedback

You can add user feedback to events via a .NET API. Please refer to the User Feedback documentation.

ASP.NET Core gRPC support

A new package was added ASP.NET Core gPRC support, adding the ability to log the request payload in case of errors.

Release Notes

Please refer to GitHub for the complete release notes.

Migrating from SharpRaven to Sentry SDK

Below are the main differences between SharpRaven and Sentry SDK, including a list of features available in Sentry SDK that are not available in SharpRaven.

Sentry Package

• Automatic capture of global unhandled exceptions (AppDomain)
• Scope management
• Duplicate events automatically dropped
• Events from the same exception automatically dropped
• Web proxy support
• HttpClient/HttpClientHandler configuration callback
• Compress request body
• Event sampling opt-in
• Event flooding protection (429 retry-after and internal bound queue)
• Release automatically set (AssemblyInformationalVersionAttribute, AssemblyVersion or env var)
• DSN discovered via environment variable
• Release (version) reported automatically
• CLS Compliant
• Strong named
• BeforeSend and BeforeBreadcrumb callbacks
• Event and Exception processors
• SourceLink (including PDB in nuget package)
• Device OS info sent
• Device Runtime info sent
• Enable SDK debug mode (opt-in)
• Attach stack trace for captured messages (opt-in)

Sentry.Extensions.Logging

• Includes all features from the Sentry package.
• BeginScope data added to Sentry scope, sent with events
• LogInformation or higher added as breadcrumb, sent with next events.
• LogError or higher automatically captures an event
• Minimal levels are configurable.

Sentry.AspNetCore

• Includes all features from the Sentry package.
• Includes all features from the Sentry.Extensions.Logging package.
• 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.
• Any event sent will include relevant application log messages
• RequestId as tag
• URL as tag
• Environment is automatically set (IHostingEnvironment)
• Request payload can be captured if opt-in
• Support for EventProcessors registered with DI
• Support for ExceptionProcessors registered with DI
• Captures logs from the request (using Microsoft.Extensions.Logging)
• Supports configuration system (e.g: appsettings.json)
• Server OS info sent
• Server Runtime info sent
• Request headers sent
• Request body compressed

All packages are:

• Strong named
• Tested on Windows, Linux, and macOS
• Tested on .NET Core, .NET Framework, and Mono

It's also very configurable, for example:

• HTTP Proxy
• Event sampling
• Enable request body extraction
• Send PII data (Personal Identifiable Information, requires opt-in)
• Read diagnostics activity data
• BeforeSend: Callback to modify/reject event before sending
• BeforeBreadcrumb: Callback to modify/reject a breadcrumb
• LogEventFilter: Filter events by inspecting log data
• Maximum number of breadcrumbs to store
• Event queue depth
• Shutdown timeout: If there are events to send, how long to wait until shutdown
• Accept compressed response
• Compress request body
• Breadcrumb level: Minimum log level to store as a breadcrumb
• Event level: Minimum log level to send an event to Sentry
• Disable duplicate event detection
• Disable capture of global unhandled exceptions
• Add event processor
• Add exception processor
• Enable SDK debug mode
• Attach stack trace for captured messages (opt-in)

Breaking Changes

Upgrading from SharpRaven to Sentry SDK includes the following breaking changes.

.NET Framework Support Reduced

If your project is targeting .NET Framework, it will need to be using at least v4.6.1 to use Sentry (SharpRaven supported .NET Framework v3.5 and higher).

Initialization

Changed how to initialize Sentry:

using Sentry;

// Initialize with DSN
SentrySdk.Init("https://examplePublicKey@o0.ingest.sentry.io/0");

// Initialize with options
SentrySdk.Init(o =>
{
    o.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";
});

For ASP.NET (classic) integration, add Sentry.AspNet package and initialize it by calling o.AddAspNet():

using Sentry;
using Sentry.AspNet;

SentrySdk.Init(o =>
{
    o.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";

    o.AddAspNet();
});

Event Queue

Contrary to SharpRaven, events in Sentry SDK are sent in background without blocking the currently executing code. Calling SentrySdk.CaptureException(...) does not immediately send an event, but instead queues it up on a background thread.

Usage changes:

// Before
ravenClient.Capture(...);
await ravenClient.CaptureAsync(...);

// After
SentrySdk.CaptureEvent(...);

If you need to stop the execution until events captured are sent to Sentry, you can also flush the queue:

SentrySdk.CaptureException(...);
// Only proceed once exception is captured. Waiting up to 2 seconds for it.
await SentrySdk.FlushAsync(TimeSpan.FromSeconds(2));

You can close the SDK, which will also flush the event queue, by invoking the IDisposable returned by SentrySdk.Init(...):

var sentryInitialization = SentrySdk.Init("https://examplePublicKey@o0.ingest.sentry.io/0");

// Capture a non-error message
SentrySdk.CaptureMessage("hello world");

// Tear down Sentry and flush queued up events
sentryInitialization.Dispose();

Event Processors

Usage changes:

// Before
ravenClient.BeforeSend = requester =>
{
    // Here you can log data from the requester
    // or replace it entirely if you want.
    return requester;
};

// After
SentrySdk.Init(o =>
{
    o.BeforeSend = e =>
    {
        // Mutate the event or return null to drop it altogether
        return e;
    };
}
});

Providing User Information

SharpRaven used IUserFactory interface for extracting user information. In Sentry SDK you can instead provide user information directly:

SentrySdk.ConfigureScope(scope =>
{
    scope.User = new User
    {
        Id = "42",
        Email = "john.doe@example.com"
    };
})

For ASP.NET Core applications, this is done automatically. User information is extracted from the context of the currently executing request.