Connect .NET to Bugsink

When a .NET application fails, Bugsink gives you the exception, stack trace, and context you need to investigate it.

This guide covers the initial setup, other ways to capture errors, and the useful context you can attach to them. You’ll start by connecting an ordinary .NET application and triggering a deliberate error to confirm that it reaches Bugsink.

To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.

Install the SDK

Add the open-source Sentry .NET SDK to your project. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project:

dotnet add package Sentry

Configure your DSN

Initialize the SDK near the start of your application. This example reads the DSN from the environment so it does not have to live in source control. The using declaration also gives the SDK a chance to send queued events during an orderly application shutdown:

using var sentry = SentrySdk.Init(options =>
{
    options.Dsn = Environment.GetEnvironmentVariable("SENTRY_DSN");
    options.Release = "inventory-dotnet@1.0.0";
});

Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the application:

export SENTRY_DSN=https://key@bugsink.example/1

Send a test error

Temporarily throw an exception in a code path you can run:

throw new InvalidOperationException("Bugsink setup check");

Run that code path once. The exception should still behave normally in your application; the SDK’s unhandled-exception integration reports it to Bugsink before the process exits.

See the error in Bugsink

Open your Bugsink project. The new InvalidOperationException issue contains the .NET stack trace and points at the application line which raised it.

Bugsink preview: unhandled exception
Bugsink preview

That’s it: your application is connected. Remove the deliberate exception. Future unhandled exceptions will be reported without capture calls in your application code.

Capture other kinds of errors

Unhandled exceptions arrive automatically. You can also report exceptions your code catches, error-level logs, and exceptional conditions which do not have an exception.

Handled exceptions

A handled exception reports a failure without changing how your application recovers. Call CaptureException() inside a catch block when you still want the exception’s stack trace and context in Bugsink. Handled Errors explains when this is useful in more depth:

try
{
    ProcessOrder(orderId, quantity);
}
catch (OrderQuantityException exception)
{
    SentrySdk.CaptureException(exception);
}

The exception remains handled by your application and appears as an issue in Bugsink.

Bugsink preview: handled exception
Bugsink preview

Microsoft.Extensions.Logging

The logging integration turns Error and higher log entries into Bugsink events. This fits applications which already use ILogger; the category names the logger, while the message template and its formatted value both remain available. Lower-level entries become breadcrumbs on the next event.

Add the integration package:

dotnet add package Sentry.Extensions.Logging

Then add the Sentry provider to your logging builder. The SDK itself must already be initialized as shown above:

using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddSentry(options =>
    {
        options.MinimumBreadcrumbLevel = LogLevel.Information;
        options.MinimumEventLevel = LogLevel.Error;
    });
});
var logger = loggerFactory.CreateLogger("Inventory.Payments");
logger.LogInformation("Starting payment provider call");
logger.LogError("Payment provider {Provider} unavailable", "ExamplePay");

Bugsink preview: formatted error log
Bugsink preview

Serilog

Serilog records can become Bugsink events through the Sentry sink while your application keeps using its normal logger calls. Informational records become breadcrumbs, while error records preserve the logger, message template, structured properties, and attached exception.

Add the integration package to an application which already uses Serilog:

dotnet add package Sentry.Serilog

Configure the sink after initializing the SDK. The source context becomes the logger name shown in Bugsink, while the two level settings choose which records become breadcrumbs and which become events:

using var rootLogger = new LoggerConfiguration()
    .WriteTo.Sentry(options =>
    {
        options.MinimumBreadcrumbLevel = LogEventLevel.Information;
        options.MinimumEventLevel = LogEventLevel.Error;
    })
    .CreateLogger();
var logger = rootLogger.ForContext("SourceContext", "Inventory.Shipping");

Normal Serilog calls then record an informational breadcrumb before sending the error with its structured shipment identifier and original exception:

logger.Information("Loading shipment {ShipmentId}", shipmentId);
try
{
    ProcessOrder(shipmentId, 0);
}
catch (OrderQuantityException exception)
{
    logger.Error(exception, "Shipment {ShipmentId} failed", shipmentId);
}

Bugsink preview: Serilog record
Bugsink preview

NLog

NLog records can become Bugsink events through the Sentry target while your application keeps using its normal logger calls. Informational records become breadcrumbs, while error records preserve the logger, message template, structured properties, and attached exception.

Add the integration package to an application which already uses NLog:

dotnet add package Sentry.NLog

Add the target after initializing the SDK. The target creates a rule which passes both informational and error records to Sentry, while the two level settings decide which become breadcrumbs and which become events:

var configuration = new NLog.Config.LoggingConfiguration();
NLog.ConfigurationExtensions.AddSentry(configuration, options =>
{
    options.MinimumBreadcrumbLevel = NLog.LogLevel.Info;
    options.MinimumEventLevel = NLog.LogLevel.Error;
});
NLog.LogManager.Configuration = configuration;
var logger = NLog.LogManager.GetLogger("Inventory.Warehouse");

Normal NLog calls then record an informational breadcrumb before sending the error with its structured order identifier and original exception:

logger.Info("Loading restock {OrderId}", orderId);
try
{
    ProcessOrder(orderId, 0);
}
catch (OrderQuantityException exception)
{
    logger.Error(exception, "Restock {OrderId} failed", orderId);
}

Bugsink preview: NLog record
Bugsink preview

log4net

Log4net records can become Bugsink events through SentryAppender without changing the calls your application already makes. Informational records become breadcrumbs, while errors preserve the logger, rendered message, and attached exception.

Add the integration alongside a current log4net release. If your application already references log4net, only the second command is new:

dotnet add package log4net
dotnet add package Sentry.Log4Net

Add the appender after initializing the SDK. Threshold chooses the lowest level which becomes a breadcrumb, while MinimumEventLevel chooses which records also become Bugsink events:

var appender = new Sentry.Log4Net.SentryAppender
{
    Threshold = log4net.Core.Level.Info,
    MinimumEventLevel = log4net.Core.Level.Error,
};
appender.ActivateOptions();
var repository = log4net.LogManager.GetRepository();
log4net.Config.BasicConfigurator.Configure(repository, appender);
var logger = log4net.LogManager.GetLogger(repository.Name, "Inventory.Supplier");

Normal log4net calls then record an informational breadcrumb before sending the error with its original exception:

logger.Info($"Checking supplier order {orderId}");
try
{
    ProcessOrder(orderId, 0);
}
catch (OrderQuantityException exception)
{
    logger.Error($"Supplier order {orderId} failed", exception);
}

Bugsink preview: log4net record
Bugsink preview

Messages without exceptions

A captured message creates a Bugsink event without an exception. Use CaptureMessage() for an exceptional condition such as an unresponsive queue, and pass the severity Bugsink should show. It has no exception stack, so prefer an exception or normal logging when either fits:

SentrySdk.CaptureMessage("Order queue is not responding", SentryLevel.Error);

Bugsink preview: captured message
Bugsink preview

Add useful context

An exception tells you what failed; context helps explain why. Context added to the current scope is attached to subsequent events.

Tags

Tags make events searchable by short key/value pairs. Bugsink already adds tags such as environment and release; add your own for a component, region, plan, or feature flag. SetTag() below attaches component:orders to later events in the current scope, so you can find order failures:

scope.SetTag("component", "orders");

Bugsink preview: component tag
Bugsink preview

Structured context

Structured context adds a named group of details to an event. Use it for values you want to inspect but not search, such as the order or job being processed. Assigning the order context creates an Order section containing its identifier and quantity:

scope.Contexts["order"] = new { id = orderId, quantity };

Bugsink preview: structured context
Bugsink preview

Breadcrumbs record what happened before an error. The SDK adds some automatically; call AddBreadcrumb() for steps it cannot know about, such as starting checkout or retrying an external call. It records the step without creating an event; the next error includes it:

SentrySdk.AddBreadcrumb(
    "Starting order processing",
    category: "order",
    data: new Dictionary<string, string> { ["order_id"] = orderId });

Bugsink preview: breadcrumb
Bugsink preview

Releases

A release identifies the version of your application which produced an event. Use the version your build or deployment already assigns; this makes it easier to tell when an error appeared or disappeared. Set it during initialization so every event from that process gets the same value:

options.Release = "inventory-dotnet@1.0.0";

Limitations

Bugsink receives .NET filenames and line numbers, but it does not yet process uploaded portable or Windows PDB files to add source context. That work is tracked in Bugsink issue #206.

The setup above covers the base SDK, Microsoft.Extensions.Logging, Serilog, NLog, and log4net on Linux. Desktop UI frameworks, functions, and MAUI use separate integrations and are not covered on this page.

.NET hosts and scripting

Host integrations capture failures through their normal application lifecycle and add the relevant request or scripting context.