Exception handling as a convention in ASP.NET Core request pipeline
C# PowerShell Shell
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Global Exception Handling for ASP.NET Core

Build status

GlobalExceptionHandlerDotNet allows you to configure exception handling as a convention with your ASP.NET Core application pipeline as opposed to explicitly handling them within each controller action. This could be particularly helpful in the following circumstances:

  • Reduce boiler plate try-catch logic in your controllers
  • Catch and appropriately handle exceptions outside of the ASP.NET Core framework
  • You don't want error codes being visible by consuming APIs (return 500 for every exception)

This middleware targets the ASP.NET Core pipeline with an optional dependency on the MVC framework for content negotiation if so desired.

Installation

GlobalExceptionHandler is available on NuGet and can be installed via the below commands depending on your platform:

$ Install-Package GlobalExceptionHandler

or via the .NET Core CLI:

$ dotnet add package GlobalExceptionHandler

Bare Bones Setup

Version 2 now hangs off of the ASP.NET Core UseExceptionHandler() endpoint, adding a convention based API around it via the WithConventions() call:

// Startup.cs

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseExceptionHandler().WithConventions(x => {
        x.ContentType = "application/json";
        x.MessageFormatter(s => JsonConvert.SerializeObject(new
        {
            Message = "An error occurred whilst processing your request"
        }));
    });
    
    app.Map("/error", x => x.Run(y => throw new Exception()));
}

Any exception thrown by your application will result in the follow response:

HTTP/1.1 500 Internal Server Error
Date: Fri, 24 Nov 2017 09:17:05 GMT
Content-Type: application/json
Server: Kestrel
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Expires: -1

{
  "Message": "An error occurred whilst processing your request"
}

Handling specific exceptions

You can explicitly handle exceptions like so:

app.UseExceptionHandler().WithConventions(x => {
    x.ContentType = "application/json";
    x.MessageFormatter(s => JsonConvert.SerializeObject(new
    {
        Message = "An error occurred whilst processing your request"
    }));

    x.ForException<RecordNotFoundException>().ReturnStatusCode(StatusCodes.Status404NotFound);
});
HTTP/1.1 404 Not Found
Date: Sat, 25 Nov 2017 01:47:51 GMT
Content-Type: application/json
Server: Kestrel
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Expires: -1

{
  "Message": "An error occurred whilst processing your request"
}

Per exception responses

Or provide a custom error response for the exception type thrown:

app.UseExceptionHandler().WithConventions(x => {
    x.ContentType = "application/json";
    x.MessageFormatter(s => JsonConvert.SerializeObject(new
    {
        Message = "An error occurred whilst processing your request"
    }));

    x.ForException<RecordNotFoundException>().ReturnStatusCode(StatusCodes.Status404NotFound)
        .UsingMessageFormatter((ex, context) => JsonConvert.SerializeObject(new {
            Message = "Record could not be found"
        }));
});

Response:

HTTP/1.1 404 Not Found
...
{
  "Message": "Record could not be found"
}

Alternatively you could output the exception content if you prefer:

app.UseExceptionHandler().WithConventions(x => {
    x.ContentType = "application/json";
    x.MessageFormatter(s => JsonConvert.SerializeObject(new
    {
        Message = "An error occurred whilst processing your request"
    }));

    x.ForException<RecordNotFoundException>().ReturnStatusCode(StatusCodes.Status404NotFound)
        .UsingMessageFormatter((ex, context) => JsonConvert.SerializeObject(new {
            Message = ex.Message
        }));
});

Content Negotiation

GlobalExceptionHandlerDotNet plugs into the .NET Core pipeline, meaning you can also take advantage of content negotiation provided by the ASP.NET Core MVC framework, enabling the clients to dictate the preferred content type.

To enable content negotiation against ASP.NET Core MVC you will need to include the GlobalExceptionHandler.ContentNegotiation.Mvc package.

Note: Content negotiation is handled by ASP.NET Core MVC so this takes a dependency on MVC.

//Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvcCore().AddXmlSerializerFormatters();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseExceptionHandler().WithConventions(x =>
    {
        x.ForException<RecordNotFoundException>().ReturnStatusCode(StatusCodes.Status404NotFound)
            .UsingMessageFormatter(e => new ErrorResponse
            {
                Message = e.Message
            });
    });

    app.Map("/error", x => x.Run(y => throw new RecordNotFoundException("Record could not be found")));
}

Now when an exception is thrown and the consumer has provided the Accept header:

GET /api/demo HTTP/1.1
Host: localhost:5000
Accept: text/xml

The response will be formatted according to the Accept header value:

HTTP/1.1 404 Not Found
Date: Tue, 05 Dec 2017 08:49:07 GMT
Content-Type: text/xml; charset=utf-8
Server: Kestrel
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Expires: -1

<ErrorResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Message>Record could not be found</Message>
</ErrorResponse>

Logging

Under most circumstances you'll want to keep a log of any exceptions thrown in your log aggregator of choice. You can do this via the OnError endpoint:

x.OnError((exception, httpContext) =>
{
    _logger.Error(exception.Message);
    return Task.CompletedTask;
});

Configuration Options:

  • ContentType
    Specify the returned content type (default is application/json).

  • MessageFormatter(...)
    Set a default message formatter that any unhandled exception will trigger.

x.MessageFormatter((ex, context) => {
    return "Oops, something went wrong! Check the logs for more information.";
});
  • DebugMode Enabling debug mode will cause GlobalExceptionHandlerDotNet to return the full exception thrown. This is disabled by default and should not be set in production.