One of the most common things that I have seen developers working with ASP.NET Core struggle with, is the way to centrally and consistently handle application errors and input validation. Those seemingly different topics are really two sides of the same coin.

More often than not, exceptions are just allowed to bubble all the way up and left unhandled, leaving the framework the responsibility to convert them to a generic 500 errors. In many other situations, exception handling is fragmented and happens in certain individual controllers only. With regard to input validation, we often have completely customized ways of notifying the client about input issues or – at best – we leave everything to the framework and let it work its defaults via the ModelState functionality.

What I wanted to show you today is how you can introduce a consistent, centralized way of handling exceptions and request validation in an ASP.NET Core web application.

Problem Details

One of the key things about building usable HTTP APIs is consistency. Having consistent responses in similar situations is absolutely crucial when building a maintainable, usable and predictable API.

As usually in life, there is no need to re-invent the wheel here. RFC7808 actually defines a problem detail type “as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs”, so it would be a good idea to just embrace that. And that applies both to input validation (4xx responses) and server errors (5xx responses).

What’s even better, is that the ASP.NET Core MVC framework, since version 2.1, actually ships with a built-in POCO for that RFC, called (surprise) ProblemDetails. The comments in the code explain nicely what each property is intended to do, so that you don’t have to read the RFC anymore 😃

In short, we can think about problem details in the following manner:

The RFC is pretty clear that the Type should be a general purpose URI that links to an HTML site describing the problem. This is generally not too useful for the purpose of HTTP APIs, as they would often be invoked without a watchful human agent overseeing the process, therefore it’s not unreasonable to skip this in APIs. An alternative is to simply direct there to a general error description section you might have i.e. in a Swagger UI page. That said, the spec mentions that: “when this member is not present, its value is assumed to be about:blank.” Therefore for the purpose of this article we will just skip it completely, and configure our JSON serializer to omit the property altogether.

Instance is also supposed to be URI but the spec is less relaxed about it, as it doesn’t force us to point to an HTML page. You may of course use it to link to some page where individual error details (for this particular occurrence) could be obtained. But, for example, since it is a URI (not URL) you can also interpret it as simply a way for you to convey an occurrence ID (a URN), rather than a physical link that can be visited. This would allow the caller to easily correlate an error received on the client side with the logs, or allows the end user to use that error ID when dealing with customer support. More about that later.

In a case of dealing with exceptions in an API, we could use the Title property to pass some general text, for example “An unexpected error occurred!”. It shouldn’t change from occurrence to occurrence so it’s a good bet. Similarly for input validation, we could say something like “Input validation failed”. In the Detail we will provide extra information, but we will handle this differently depending on whether we are dealing with an exception or input validation failure.

Exception handling

Let’s start with exception handling. ASP.NET Core exposes a feature called IExceptionHandlerFeature which you can use to globally handle exceptions. To wire in such a global exception handler you need to call UseExceptionHandler() method on the IApplicationBuilder:

UseExceptionHandler() allows you to register a de-facto sub-application to handle your application’s exceptions – the delegate you will be registering gives you access to a child IApplicationBuilder. This is hardly ever needed though, and the typical usage scenario would be to simply register a single, lone middleware component there, that handles the exception and returns a relevant response to the caller.

This is shown in the next snippet.

What’s next, is deciding how we actually would like to format the response to the caller in a standardized way. I have seen many HTTP APIs invent their own ways of doing that – which may not be desirable, but if it is at least consistent in the scope of a given system, it’s not that bad.

However, since this is a blog post about the Problem Detail RFC, we’ll be incorporating that. Most of the stuff has already been laid out in the previous section, so it should be clear, but specifically for the Detail part of the response we will do two things:

Of course it is entirely up to you how you consider to structure your errors, interpret the given RFC properties, refine them to make sense for your applications and what would you like to convey in them – this article is merely an illustration of the technique and how you might want to get started.

Anyway, at code level it all could look as follows:

The IsTrusted() is a hypothetical extension method that you could create for yourself to determine whether or not you want to share exception details with the caller. I also used Ben’s excellent demystifier library to process and format the exception nicely into a string. As Instance we use a generic organizational URI, combined with GUID.

In order to flush the response, we use a helper extension method. As a reminder – the Type property is going to be omitted by design, so we will use the setting NullValueHandling.Ignore in the JSON serializer.

We are very close now, as we are finally flushing the response to the caller. We could start testing this with some exceptions being thrown in our application, and bubbling up all the way to the surface – they should be converted into this nice standardized error format.

One extra thing we still need to handle, are special “bad request” Kestrel exceptions. These are related to low-server-level issues with the request, for example an HTTP method not being allowed at server level, too large headers or even too large payload body (which, by the way, is configurable, and commonly used to prevent i.e. too large files being uploaded). In those cases, Kestrel will throw BadHttpRequestException which will pass through our error handler. The problem is we shouldn’t convert it into a 500, like we do at the moment, because those errors are not 500s – for example a request body that is too large should result in HTTP Status Code 413.

The solution is to special case our handler to be able to deal with those Kestrel’s BadHttpRequestException. It will unfortunately require us to reach into some reflection tricks, as certain crucial information is internal only.

Here is our, slightly restructured, final version of the error handler:

The end result is the following – if we have a “regular” unhandled exception from our code, the returned payload looks like this (provided you are allowed to see the exception details):

For the Kestrel request validation error, the response looks like this:

Input validation

So we have configured everything that is needed for error handling. The one thing that we haven’t tackled yet is doing request validation. That is, for example, doing the regular validation of the payload submitted to our API. This is definitely something we should look at – as a standardized Problem Details response would make a lot of sense here. After all, input validation failures are probably a lot more common than unhandled exceptions.

The best way to approach this would be to create a dedicated IActionResult, which we can return in case a malformed (bad) request is submitted by the caller to our API. However, before we do it, a few words about extending the ProblemDetails, because as we have seen, it is nice and standardized, but also a bit constraining, if we just consider its few basic properties.

The RFC actually allows for additional members (“extension members”) to be defined alongside the standard properties. Clients consuming the response are explicitly required to ignore the members it can’t understand allowing the possibility for the payload to additively evolve over time.

Imagine that we’d like to have an additional property related to our request validation errors. The MVC framework already captures validation errors into a ModelStateDictionary, so we could project information from there into our extended ProblemDetails. The outline of that is shown in the next snippet:

We will be projecting the MVC framework’s ModelStateDictionary into a collection of ValidationError to simplify presentation. With all that in place, we can proceed towards setting up our custom IActionResult, the ValidationProblemDetails, which is shown next.

As our action result is executed, we can reach into the ModelState and extract the relevant errors. There is a bit of custom logic there, which we don’t necessarily need to go into that deeply. The gist of it is that if the whole request has some fundamental problems (for example a JSON body is missing at all), then ModelState would normally contain a single error entry, that is keyed against an empty string. In that case, we want to convey that error to the caller in the Detail property of our ValidationProblemDetails. When that happens, the ValidationErrors property will be an empty array, and that is OK.

In all other cases, we simply pick up the errors from the model state dictionary and put them into the ValidationErrors property. In that case, the Detail message of our response is going to be a generic text, something like “See ValidationErrors for details”.

In either situation, the value of Instance, is, similarly to our earlier efforts, a URN – formatted accordingly: “urn:myorganization:badrequest:{Guid.NewGuid()}”. The Status is always 400 and the Title is also a static “Request Validation Error”.

The question now, is how to actually best consume this action result? The easiest way would be to just manually return ValidationProblemDetails from the action. Let’s imagine having a following model:

We could, for example, do the inline ModelState validity check and return the ValidationProblemDetails manually:

If someone, for example, skips the Name property or uses a Rating value outside of the defined range, then the caller will get a relevant Problem Details response.

Such usage pattern is IMHO not very elegant, but it would work. Probably a better way would be to incorporate our ValidationProblemDetails into the ApiControllerAttribute feature of ASP.NET Core 2.1. The way it works, is that if we put an [ApiController] attribute on our controller, a bunch of nice things will happen, including automatic validation of model state. This is great, but of course if the model state validation happens automatically, and the response is automatically produced by the framework, how can we make our ValidationProblemDetails part of that?

Turns out you can register a custom IActonResult factory that will be used in case of validation failures, which is exactly what we need. This is done in the Startup class.

With that in place, we can no write our controllers in a very clean way, with only the so called “happy path” inline in the actions, as all of the stuff related to request validation is centrally managed and handled by the combination of the [ApiController] functionality and our ValidationProblemDetails.

For the record, this is how our response would look like, if the request is completely malformed (for example a 0 length body is sent by the caller):

Now, in case of invalid contents of the JSON payload, the model state validation kicks in, and the individual details are convey via our extension property.

And this is it. Obviously you can take this concept even further – I only wanted to show 2 common scenarios today, both of which are designed around centralized handling of matters – dealing with unhandled exceptions and dealing with request validation.

In real life, you will probably have some extra validation requirements that may not map very easily to the concept of ModelState and its projection onto our general purpose responses. In such situations, you’d like be subclassing ProblemDetails on your own and building your own customized IActionResult to handle that.

The same applies for having customized status codes – it’s not difficult to envision use cases for status codes like 409 (Conflict) or 410 (Gone). You could even enrich 404 payloads with the “Problem Details” approach.

However, I hope this article will help you get started, and nudge you in a right direction.