Handling Global Exceptions in ASP.NET Core

AddProblemDetails and UseExceptionHandler catch every exception an action doesn't, log it, and answer with a tidy 500 problem details response that never shows the stack trace. An IExceptionHandler can answer chosen exceptions with a better status, such as 409 Conflict.

Freelancer · ASP.NET Core · REST API · Updated

By

After this lesson you can

  • Turn unhandled exceptions into problem details responses with AddProblemDetails and UseExceptionHandler
  • Write an IExceptionHandler that answers one kind of exception with its own status code

Key takeaways

  • AddProblemDetails() and UseExceptionHandler() catch every exception an action doesn't, log it, and answer with a 500 problem details response.
  • The stack trace goes to the app's log, never to the client, because it shows strangers how your code is built.
  • Put app.UseExceptionHandler() right after builder.Build(), so it's in front of everything else.
  • An IExceptionHandler, registered with AddExceptionHandler, answers the exceptions it knows, such as SQL error 547 with 409 Conflict, and returns false for the rest.
  • Handle the expected in the action, such as return NotFound();, and the unexpected in one place for the whole API.

In DELETE, deleting a category that still has products sent the client a 500 with the whole SqlException and its stack trace. That's two problems:

  1. It shows too much. A stack trace tells strangers how your code is built: class names, file paths, SQL. That's useful to an attacker and useless to a client.
  2. It says too little. Every other error from this API is problem details JSON that the client knows how to read. This one is a wall of text.

You could put a try and catch in every action. But exceptions you don't expect can happen anywhere, so the answer belongs in one place for the whole API.

One line each

builder.Services.AddProblemDetails();
var app = builder.Build();

app.UseExceptionHandler();
  • AddProblemDetails() makes ASP.NET Core write its error responses as problem details.
  • UseExceptionHandler() adds a step to the start of the request pipeline that catches any exception from anything after it, such as your controllers. It logs the exception, with its stack trace, and answers the client with a 500 problem details response. Put it right after builder.Build(), so it's in front of everything else.

Restart the API, and send Delete Beverages from your Insomnia collection again:

DELETE {{ _.base_url }}/api/categories/1
HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "title": "An error occurred while processing your request.",
  "status": 500
}

The client gets a clean, standard answer. The details haven't vanished: they're in the app's log, which you can see in the console window where the API is running, starting with An unhandled exception has occurred while executing the request. That's where you, not your clients, should look.

Choosing a better answer: IExceptionHandler

A foreign-key conflict isn't really the server's fault: the client asked to delete something that other data still uses. 409 Conflict would say that properly.

An IExceptionHandler gets the first look at each unhandled exception. It answers the ones it knows about, and leaves the rest for the standard 500:

using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Data.SqlClient;

namespace NorthwindApi.Errors;

// Turns a foreign key conflict from SQL Server (error 547) into 409 Conflict.
public class DatabaseConflictHandler : IExceptionHandler
{
    private readonly IProblemDetailsService problemDetailsService;

    public DatabaseConflictHandler(IProblemDetailsService problemDetailsService)
    {
        this.problemDetailsService = problemDetailsService;
    }

    public async ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception exception, CancellationToken cancellationToken)
    {
        if (exception is not SqlException sqlException || sqlException.Number != 547)
        {
            return false;
        }

        httpContext.Response.StatusCode = StatusCodes.Status409Conflict;
        return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = httpContext,
            ProblemDetails = new ProblemDetails
            {
                Status = StatusCodes.Status409Conflict,
                Title = "Conflict",
                Detail = "Other data still uses this item, so it can't be changed or deleted."
            }
        });
    }
}
  • IExceptionHandler is an interface with one method, TryHandleAsync, which gets the exception.
  • It returns false for exceptions it doesn't handle. exception is not SqlException sqlException || ... reads: if it isn't a SqlException, or it's a different SQL error, leave it. SQL Server's error number 547 means a constraint, such as a foreign key, stopped the statement.
  • It returns true once it has written the response: the status code, then a problem details body written by IProblemDetailsService, which it asked for in its constructor.
  • ValueTask<bool> is a lighter cousin of Task<bool>. Treat it the same way: async, and return a bool.

Register it in Program.cs, next to AddProblemDetails():

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<DatabaseConflictHandler>();

Restart the API, and send Delete Beverages once more:

DELETE {{ _.base_url }}/api/categories/1
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Conflict",
  "status": 409,
  "detail": "Other data still uses this item, so it can't be changed or deleted."
}

Every action in every controller now answers a foreign-key conflict with 409, and you didn't touch a single one. Any other exception still gets the standard 500. You can register several handlers; they're asked in the order they were added.

Where each error belongs

Situation Handled by
The body breaks a validation rule [ApiController]: 400, automatically
No item with that id The action: return NotFound();
A rule the action checks, such as a name already taken The action: return Conflict(...);
An exception you can turn into a meaningful status, anywhere in the API An IExceptionHandler: such as 409 for SQL error 547
Anything else UseExceptionHandler(): logged, and a 500 with no details

Do it: choose the status for an exception

DatabaseConflictHandler gets the first look at each exception an action doesn't catch: SQL error 547 becomes 409 Conflict, and anything else is left for the standard 500. Write that choice as a method.

The box has no database, so it has no SqlException either. It gives you a stand-in, DatabaseException, with the same Number property: SQL Server's error number.

The method gets one value:

  • exception: the exception an action threw, an Exception.

For example, Delete Beverages: the database refused with error 547.

Question For new DatabaseException(547)
Is it a DatabaseException? yes
Is its Number 547? yes
The answer 409

So StatusFor(new DatabaseException(547)) returns 409.

Your job: write the method StatusFor(Exception exception) so it returns the status code, an int.

  • When the exception is a DatabaseException whose Number is 547, return 409.
  • For any other exception, return 500. That includes a DatabaseException with another number.

Practiced live on the lesson page: write the C# right there and check it.

Check yourself

2 questions to try on the lesson page.

So what

Handle the expected in the action, and the unexpected in one place. With AddProblemDetails and UseExceptionHandler, every error your API sends is the same tidy shape, the details stay in your log, and an IExceptionHandler can turn a known exception into the right status everywhere at once.

Key terms

Cheat sheets