rfc7807

HttpExceptions updated for .NET Core 3.0

HttpExceptions has been updated to version 2.3 for use with the new .NET Core 3.0.

Build Status NuGet Badge License: MIT

HttpExceptions?

HttpExceptions lets you return exceptions over HTTP e.g. as ASP.NET Core Problem Details, and has HTTP-specific exception classes that enable ASP.NET to generate exception information.

Getting started

In ASP.NET Core 3.0 you add the HttpExceptions services and the middleware in the Startup.cs of your application. The change from 2.x to 3.0 is that you now add it to AddControllers() instead of to AddMvcCore().

public void ConfigureServices(IServiceCollection services)
{
    ...
    services.AddControllers().AddHttpExceptions();
    ...
}

Then you can add the HttpExceptions middleware using the application builder. UseHttpExceptions should be the first middleware component added to the pipeline. That way the UseHttpExceptions Middleware catches any exceptions that occur in later calls. When using HttpExceptions you don't need to use UseExceptionHandler or UseDeveloperExceptionPage.

public void Configure(IApplicationBuilder app)
{
    app.UseHttpExceptions(); // this is the first middleware component added to the pipeline
    ...
}

InvalidModelStateResponseFactory API behavior

From this release on HttpExceptions always overrides the default Microsoft.AspNetCore.Mvc.ApiBehaviorOptions.InvalidModelStateResponseFactory and related settings and will use the configured ExceptionMappers. The SuppressInvalidModelStateResponseFactoryOverride has been removed.

Where can I get it?

The code can be found on GitHub at: github.com/ofpinewood/http-exceptions. And there is also a sample project you can have a look at.

You can install the Opw.HttpExceptions and Opw.HttpExceptions.AspNetCore NuGet packages from the package manager console:

PM> Install-Package Opw.HttpExceptions
PM> Install-Package Opw.HttpExceptions.AspNetCore

Returning exceptions as ASP.NET Core Problem Details

Problem Details are a machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807. By providing more specific machine-readable error responses, the API clients can react to errors more effectively and it also makes the APIs much more reliable from the REST API testing perspective and the clients as well.

Some background

For years I have been building WebAPIs for different projects and every time I have written similar code, or copied and updated code form a previous project, to return exceptions over HTTP in a uniform way.
In the end of 2016 I updated my code to return RFC 7807 Problem Details for HTTP APIs compatible responses. And then with the release of ASP.NET Core 2.1 when Problem Details where introduced into the framework I updated the code to use the default Microsoft.AspNetCore.Mvc.ProblemDetails.
When I recently started a new project and I was doing that same implementation again for the umpteenth time, I decided to make a package out of it. And I thought it would be fun to create an OSS project, my first one ;)

The project consists of two parts HttpExceptions and extensions for returning exceptions as ASP.NET Core Problem Details. Both can be found on GitHub at: github.com/ofpinewood/http-exceptions.

Opw.HttpExceptions.AspNetCore

This packages has extensions for returning exceptions as ASP.NET Core Problem Details.

NuGet Badge

Opw.HttpExceptions

This package contains HTTP-specific exception classes that enable ASP.NET to generate exception information. These classes can be used by themselves or as base classes for your own HttpExceptions.

NuGet Badge

Getting started

Add the HttpExceptions services and the middleware in the Startup.cs of your application. First add the required services to the services collection.

public void ConfigureServices(IServiceCollection services)
{
    ...
    services.AddHttpExceptions();
    ...
}

Then you can add the HttpExceptions middleware using the application builder. UseHttpExceptions should be the first middleware component added to the pipeline. That way the UseHttpExceptions Middleware catches any exceptions that occur in later calls. When using HttpExceptions you don't need to use UseExceptionHandler or UseDeveloperExceptionPage.

public void Configure(IApplicationBuilder app)
{
    app.UseHttpExceptions(); // this is the first middleware component added to the pipeline
    ...
}

Configuring the HttpExceptions middleware

You can extend or override the default behavior through the configuration options, HttpExceptionsOptions.

Include exception details

Whether or not to include the full exception details in the response. The default behavior is only to include exception details in a development environment.

services.AddHttpExceptions(options =>
{
    // This is the same as the default behavior; only include exception details in a development environment.
    options.IncludeExceptionDetails = context => context.RequestServices.GetRequiredService<IHostingEnvironment>().IsDevelopment();
});

Is Exception Response

Is the response an exception and should it be handled by the HttpExceptions middleware.

services.AddHttpExceptions(options =>
{
    // This is a simplified version of the default behavior; only include exception details for 4xx and 5xx responses.
    options.IsExceptionResponse = context => (context.Response.StatusCode < 400 && context.Response.StatusCode >= 600);
});

Custom ExceptionMappers

Set the ExceptionMapper collection that will be used during mapping. You can override and/or add ExceptionMappers for specific exception types. The ExceptionMappers are called in order so make sure you add them in the right order.

By default there is one ExceptionMapper configured, that ExceptionMapper catches all exceptions.

services.AddHttpExceptions(options =>
{
    // Override and or add ExceptionMapper for specific exception types, the default ExceptionMapper catches all exceptions.
    options.ExceptionMapper<BadRequestException, BadRequestExceptionMapper>();
    options.ExceptionMapper<ArgumentException, ExceptionMapper<ArgumentException>>();
    // The last ExceptionMapper should be a catch all, for type Exception.
    options.ExceptionMapper<Exception, MyCustomExceptionMapper>();
});

Where can I get it?

The code can be found on GitHub at: github.com/ofpinewood/http-exceptions. And there is also a sample project you can have a look at.

You can install the Opw.HttpExceptions and Opw.HttpExceptions.AspNetCore NuGet packages from the package manager console:

PM> Install-Package Opw.HttpExceptions
PM> Install-Package Opw.HttpExceptions.AspNetCore