ASP.NET Web API integration guide

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

New to BugSnag? Create an account


Manual installation

  • Download the latest DLLs.
  • Reference Bugsnag.dll, Bugsnag.AspNet.dll, Bugsnag.AspNet.WebApi.dll and Bugsnag.ConfigurationSection.dll in your project.

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


  • .NET Framework 4.0 (Web API 1)
  • .NET Framework 4.5+ (Web Api 2.2)

Basic configuration

  1. Configure the BugSnag integration inside your Web.config file

        <section name="bugsnag"
                 type="Bugsnag.ConfigurationSection.Configuration, Bugsnag.ConfigurationSection" />
      <bugsnag apiKey="your-api-key-goes-here" />

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

  2. Configure Web API with BugSnag where you configure your other Web API configuration.

    using System.Web.Http;
    using Bugsnag.AspNet.WebApi;
    public static void Register(HttpConfiguration config)
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional }

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

using System.Web.Http;
using Bugsnag.AspNet.WebApi;

public class ApiController : ApiController
  public void Delete(int id)
      .Notify(new System.Exception("Error!"));

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;

// ...

  throw new System.Exception("Error!");
catch (System.Exception ex)
    Request.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:

Request.Bugsnag().BeforeNotify(report =>
    report.Event.User = new Bugsnag.Payload.User
        Id = "45556",
        Name = "Bob Smith",
        Email = ""

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.

  .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.

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

With additional diagnostic metadata:

var metadata = new Dictionary<string, string> { { "foo", "bar" } }
  .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.


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