Docs Platforms .NET ASP.NET Core
bugsnag.com Start Free Trial

ASP.NET Core integration guide

Add BugSnag to your ASP.NET Core applications to automatically capture and report exceptions in production.

New to BugSnag? Create an account

Looking for performance monitoring? See our performance guide

Installation

Manual installation

  • Download the latest DLLs.
  • Reference Bugsnag.dll and Bugsnag.AspNet.Core.dll in your project.

The latest available version of Bugsnag.AspNet.Core is v3.1.0.

Compatibility

  • .NET Framework 4.6.1+
  • .NET Core 1.x, 2.x and 3.x
  • .NET 5+

For more information, see the Compatibility guide.

Basic configuration

  1. Import the Bugsnag.AspNet.Core namespace into Startup.cs

    using Bugsnag.AspNet.Core;

  2. Add the BugSnag service to your application

    public void ConfigureServices(IServiceCollection services)
{
  services.AddBugsnag(configuration => {
    configuration.ApiKey = "your-api-key-goes-here";
  });
}

    You can find your API key in Project Settings from your BugSnag dashboard.

Further configuration

If you’d like to configure BugSnag further, check out the configuration options reference.

Reporting unhandled exceptions

After completing installation and basic configuration, unhandled exceptions will be automatically reported to your BugSnag dashboard.

Reporting handled exceptions

If you would like to send non-fatal exception to BugSnag, you can pass any object that inherits from System.Exception to the Notify method. The BugSnag client will be injected into your classes where you declare the IClient dependency.

public class HomeController : Microsoft.AspNetCore.Mvc.Controller
{
  private readonly Bugsnag.IClient _bugsnag;

  public HomeController(Bugsnag.IClient client)
  {
    _bugsnag = client;
  }

  public Microsoft.AspNetCore.Mvc.IActionResult Index()
  {
    try
    {
      throw new System.Exception("Error!");
    }
    catch (System.Exception exception)
    {
      _bugsnag.Notify(exception);
    }

    return View();
  }
}

Sending diagnostic data

Automatically captured diagnostics

As well as a full stacktrace for every exception, BugSnag will automatically capture the following diagnostic data:

  • Request information, including ip, headers, URL, HTTP method, and HTTP params
  • Hostname
  • Locale
  • OS Name
  • Timezone
  • Time

Custom diagnostics

It can often be helpful to attach application-specific diagnostic data to exception reports. This can be accomplished as follows:

using System.Collections.Generic;

// ...

try
{
  throw new System.Exception("Error!");
}
catch (System.Exception ex)
{
    _bugsnag.Notify(ex, (report) => {
        report.Event.Metadata.Add("account", new Dictionary<string, string> {
            { "company", "Acme Co." },
            { "id", "4425" },
        });
    });
}

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your BugSnag dashboard.

You can set this information using a callback as follows:

_bugsnag.BeforeNotify(report =>
{
    report.Event.User = new Bugsnag.Payload.User
    {
        Id = "45556",
        Name = "Bob Smith",
        Email = "bob@example.com"
    };
});

For more information, see Customizing error reports.

Logging breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. The last 25 breadcrumbs are attached to an error report to help diagnose what events lead to the error. Captured breadcrumbs are shown on your BugSnag dashboard as a part of the error report.

You can leave manual breadcrumbs via the Breadcrumbs property on the client object.

_bugsnag.Breadcrumbs
  .Leave("Something happened!");

You can optionally attach a type and metadata to a breadcrumb for additional context into the state of the application when the breadcrumb was captured.

_bugsnag.Breadcrumbs
  .Leave("Something happened!", Bugsnag.BreadcrumbType.Navigation, null);

With additional diagnostic metadata:

var metadata = new Dictionary<string, string> { { "foo", "bar" } }
_bugsnag.Breadcrumbs
  .Leave("Something happened!", Bugsnag.BreadcrumbType.State, metadata);

Session tracking

BugSnag can track the number of “sessions” that happen in your application. This enables BugSnag to provide and compare stability scores between releases to help you understand the quality of your releases.

This functionality is disabled by default and can be controlled through the AutoCaptureSessions configuration value:

configuration.AutoCaptureSessions = true;

Using this option, BugSnag will report a session each time a request is received.

If you want control over what is deemed a session, rather than using the AutoCaptureSessions option, you can call the following when appropriate for your application.

_bugsnag.SessionTracking.CreateSession();

Symbolication guide

Stacktraces from .NET platforms will be automatically populated with line numbers and file names for dlls that the runtime can find symbols for. This usually means that you should deploy the .pdb files alongside your dlls so that BugSnag is able to retrieve this information.

Next steps