Middleware-based Exception Handling in .NET

Exception handling is a crucial aspect of developing reliable and robust applications. In .NET 6 APIs, implementing effective exception handling using middlewares can greatly enhance error reporting, application stability, and overall user experience. This blog post focuses on implementing exception handling in .NET 6 Web API using custom middlewares and provides practical examples for a better understanding.

Exception Handling Middleware in .NET Web API

Middlewares are components that process HTTP requests and responses in a pipeline. Exception handling middlewares intercept exceptions, allowing developers to handle them gracefully. Follow the steps below to implement exception handling.

Create a Custom Exception Middleware

Create a custom middleware class that will handle exceptions globally. This middleware will catch any unhandled exceptions and perform the necessary actions. Inside the InvokeAsync method of the custom exception middleware, you can define the actions to be performed when an exception occurs. These actions may include logging the exception details and returning an appropriate response to the client. Here's an example:

public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger _logger;

    public ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task Invoke(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception exception)
        {
            var response = context.Response;
            response.ContentType = "application/json";

            switch (exception)
            {
                case AppException ex:
                    response.StatusCode = StatusCodes.Status400BadRequest;
                    break;
                case ArgumentException ex:
                    response.StatusCode = StatusCodes.Status400BadRequest;
                    break;
                case NotFoundException ex:
                    response.StatusCode = StatusCodes.Status404NotFound;
                    break;
                default:
                    // Unhandled error
                    _logger.LogError(exception, exception.Message);
                    response.StatusCode = StatusCodes.Status500InternalServerError;
                    break;
            }

            var resultContent = JsonSerializer.Serialize(new { message = exception.Message });
            await response.WriteAsync(resultContent);
        }
    }
}

In the above example, based on different types of exceptions, a corresponding HTTP status code is returned to the client along with the exception message. You can add more exception types here to be globally handled. If the exception does not match any specified type, the default behavior is to return an Internal Server Error (500) HTTP status code.

Register Middleware

In the Startup.cs (or Program.cs since .NET 7) file, configure the custom exception middleware to handle exceptions globally. This middleware should be added to the pipeline before any other middlewares to ensure proper exception handling. Here's an example of configuring the middleware:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseMiddleware<ExceptionHandlingMiddleware>();

    // Remaining configurations...
}

Now, whenever an exception is thrown by the controllers or their underlying implementation, the exceptions will be processed by the middleware.

Summary

Implementing exception handling in .NET Web APIs using middlewares is a powerful technique for improving error reporting, maintaining application stability, and enhancing the overall user experience. By creating a custom exception middleware and configuring it in the pipeline, you can capture exceptions and perform necessary actions such as logging and returning appropriate responses to the client.

DotNetWay