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 Sentrydotnet 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"; });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/1export 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");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
System.InvalidOperationException
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); }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
OrderQuantityException
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.Loggingdotnet 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");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");
error Inventory.Payments Payment provider ExamplePay unavailable Payment provider {Provider} unavailableBugsink preview: formatted error log
Log Entry
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.Serilogdotnet 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");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); }logger.Information("Loading shipment {ShipmentId}", shipmentId); try { ProcessOrder(shipmentId, 0); } catch (OrderQuantityException exception) { logger.Error(exception, "Shipment {ShipmentId} failed", shipmentId); }
error Inventory.Shipping Shipment "shipment-4001" failed Shipment {ShipmentId} failedBugsink preview: Serilog record
Log Entry
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.NLogdotnet 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");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); }logger.Info("Loading restock {OrderId}", orderId); try { ProcessOrder(orderId, 0); } catch (OrderQuantityException exception) { logger.Error(exception, "Restock {OrderId} failed", orderId); }
error Inventory.Warehouse Restock "restock-7001" failed Restock {OrderId} failedBugsink preview: NLog record
Log Entry
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.Log4Netdotnet 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");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); }logger.Info($"Checking supplier order {orderId}"); try { ProcessOrder(orderId, 0); } catch (OrderQuantityException exception) { logger.Error($"Supplier order {orderId} failed", exception); }
error Inventory.Supplier Supplier order supplier-9001 failedBugsink preview: log4net record
Log Entry
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);SentrySdk.CaptureMessage("Order queue is not responding", SentryLevel.Error);
error Order queue is not respondingBugsink preview: captured message
Log Entry
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");scope.SetTag("component", "orders");
ordersBugsink preview: component tag
Tags
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 };scope.Contexts["order"] = new { id = orderId, quantity };
dotnet-handled 0Bugsink preview: structured context
Contexts
ORDER
Breadcrumbs
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 });SentrySdk.AddBreadcrumb( "Starting order processing", category: "order", data: new Dictionary<string, string> { ["order_id"] = orderId });
Bugsink preview: breadcrumb
order
Starting order processing
event time
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";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.
