Asp.Net Web Api Global Exception Handling Using Middleware And Filters Complete Guide

ASP.NET Web API Global Exception Handling using Middleware and Filters

Global exception handling plays a crucial role in ensuring that an ASP.NET Web API application can gracefully handle errors and provide meaningful feedback to the client. Without robust exception handling, your application might expose sensitive information or simply fail to respond appropriately when exceptions occur, leading to poor user experience and potential security vulnerabilities.

In ASP.NET Core (which includes ASP.NET Web API), there are two main mechanisms for handling exceptions globally: Middleware and Filters. Each approach has its own advantages and is suited for different scenarios. This article will delve into both methods, explaining their usage with code examples and highlighting important considerations.

Exception Handling Middleware

Middleware components in ASP.NET Core perform operations on HTTP requests and responses. One of the most versatile uses of middleware is for global exception handling in Web APIs. The Exception Handling Middleware allows you to catch exceptions that occur during the processing of HTTP requests, log them, and return a custom error response.

Basic Usage

To implement global exception handling using middleware, follow these steps:

1. Create a Custom Middleware: Define a middleware class that handles exceptions by wrapping the request pipeline.
2. Add Middleware to the Pipeline: Configure the middleware to be used in the request pipeline in Startup.cs.
3. Log Exceptions: Optionally, integrate logging to record exceptions for debugging and monitoring purposes.
4. Return Custom Responses: Format and send an appropriate HTTP response to the client upon catching an exception.

Custom Middleware Example

public class ExceptionHandlerMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlerMiddleware> _logger;

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

    public async Task InvokeAsync(HttpContext httpContext)
    {
        try
        {
            await _next(httpContext);
        }
        catch (Exception ex)
        {
            _logger.LogError($"Something went wrong: {ex}");
            await HandleExceptionAsync(httpContext, ex);
        }
    }

    private static Task HandleExceptionAsync(HttpContext context, Exception exception)
    {
        context.Response.ContentType = "application/json";
        context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;

        return context.Response.WriteAsync(new ErrorDetails()
        {
            StatusCode = context.Response.StatusCode,
            Message = "Internal Server Error from the custom middleware."
        }.ToString());
    }
}

public class ErrorDetails
{
    public int StatusCode { get; set; }
    public string Message { get; set; }

    public override string ToString()
    {
        return JsonConvert.SerializeObject(this);
    }
}

Configuring Middleware in Startup.cs or Program.cs (for .NET 6+)

// For older versions (.NET Core 3.x):
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    // Order is important here
    app.UseMiddleware<ExceptionHandlerMiddleware>();
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

// For .NET 6+:
public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        var app = builder.Build();

        if (app.Environment.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseMiddleware<ExceptionHandlerMiddleware>();
        app.UseRouting();

        app.UseAuthorization();

        app.MapControllers();

        app.Run();
    }
}

Key Points

• Simplicity: Exception Handler Middleware provides a straightforward and centralized way to handle exceptions globally.
• Flexibility: It allows you to handle a variety of exceptions using custom logic.
• Performance: Since middleware operates at the lowest level of the ASP.NET Core request pipeline, it minimizes the overhead associated with handling exceptions.

However, middleware does not provide as fine-grained control over the exception handling process as filters do, particularly when handling exceptions that are thrown within attribute routing or model binding contexts.

Exception Filters

Exception filters are part of the MVC execution pipeline and allow you to handle exceptions specifically thrown during the execution of actions in ASP.NET Web API controllers. They offer more granular control compared to middleware but are primarily intended for MVC-based applications rather than pure Web APIs.

Using Exception Filters

To use an exception filter, create a class that inherits from the IExceptionFilter interface and override the OnException method. You can then apply this filter globally across all controllers or target specific controllers or actions.

Creating a Custom Exception Filter

public class GlobalExceptionFilter : IExceptionFilter
{
    private readonly ILogger<GlobalExceptionFilter> _logger;

    public GlobalExceptionFilter(ILogger<GlobalExceptionFilter> logger)
    {
        _logger = logger;
    }

    public void OnException(ExceptionContext context)
    {
        // Log the exception details
        _logger.LogError($"Exception while executing action: {context.Exception.Message}");

        var result = new ObjectResult(new ErrorDetails
        {
            StatusCode = context.Exception is FileNotFoundException ? 
                         (int)HttpStatusCode.NotFound : 
                         (int)HttpStatusCode.InternalServerError,
            Message = "Server error occurred."
        })
        {
            StatusCode = (int)HttpStatusCode.InternalServerError,
        };

        // Assign the result to the context.Result
        context.Result = result;

        // Indicate that the exception has been handled
        context.ExceptionHandled = true;
    }
}

public class ErrorDetails
{
    public int StatusCode { get; set; }
    public string Message { get; set; }
}

Registering the Exception Filter Globally

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options => 
    {
        options.Filters.Add(typeof(GlobalExceptionFilter));
    });

    services.AddLogging();
}

Applying an Exception Filter to a Specific Controller

[ApiController]
[Route("api/[controller]")]
[ServiceFilter(typeof(GlobalExceptionFilter))]
public class SampleController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(int id)
    {
        throw new Exception("Sample controller exception.");
    }
}

Key Points

• Granularity: Exception filters enable more precise control over the exception handling process, including access to metadata about the action being executed.
• Integration: They integrate seamlessly with the MVC framework and other ASP.NET Core features such as dependency injection.
• Specificity: Filters can be applied globally or to specific controllers/actions, offering a high degree of flexibility.

One downside of using exception filters is that they won’t catch exceptions thrown before the MVC framework starts executing, such as those occurring in middleware or during URL routing.

Comparing Middleware and Filters

Both middleware and filters serve the purpose of handling exceptions in ASP.NET Core applications, but they differ in their level of abstraction and applicability.

| Aspect | Middleware | Filters | |--------------------|----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------| | Invocation Time| Early in the request pipeline, before model binding and action selection. | During the action execution phase, after model binding and action selection. | | Flexibility | High – suitable for low-level pipeline operations and cross-cutting concerns. | Medium to High – fine-grained control over the exception handling process within specific actions. | | Use Cases | Handling exceptions thrown outside the MVC layer, e.g., in authentication/authorization middleware. | Handling exceptions within controller actions, providing more flexibility in response formatting. | | Performance | Lower performance impact due to operating at the lowest level of the pipeline. | Higher performance impact due to the additional execution layers provided by MVC. | | Error Details | Less detailed by default – can only access HTTP context. | More detailed – has access to action metadata, routing information, etc. |

Choosing Between Middleware and Filters

When it comes to choosing between middleware and filters for global exception handling, consider the following:

• Scope: If you need to handle exceptions that occur before reaching the MVC layer, such as during authentication, middleware is the better choice.
• Granularity: Filters provide finer control over how exceptions are handled per controller or action, making them ideal for applications requiring extensive customization.
• Performance: Middleware generally imposes less overhead, which can be a deciding factor in high-performance scenarios.
• Integration: If your application is heavy on MVC features and benefits from dependency injection, leveraging filters might be more beneficial.

For most ASP.NET Web API applications, a combination of both approaches is often recommended to ensure comprehensive exception handling. Middleware can capture lower-level exceptions, while filters can handle MVC-specific errors with greater detail.

Implementing a Combination Middleware and Filters Approach

Here’s an example combining both middleware and filters for effective exception handling:

Custom Middleware for General Exceptions

public class ExceptionHandlerMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlerMiddleware> _logger;

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

    public async Task InvokeAsync(HttpContext httpContext)
    {
        try
        {
            await _next(httpContext);
        }
        catch (Exception ex)
        {
            _logger.LogError($"Middleware caught an exception: {ex}");
            await HandleExceptionAsync(httpContext, ex);
        }
    }

    private static Task HandleExceptionAsync(HttpContext context, Exception exception)
    {
        context.Response.ContentType = "application/json";
        context.Response.StatusCode = StatusCodes.Status500InternalServerError;

        return context.Response.WriteAsync(
            new ErrorDetails()
                {
                    StatusCode = context.Response.StatusCode,
                    Message = "Error from Exception Handler Middleware."
                }.ToString());
    }
}

Custom Filter for MVC-Specific Exceptions

public class GlobalExceptionFilter : IExceptionFilter
{
    private readonly ILogger<GlobalExceptionFilter> _logger;

    public GlobalExceptionFilter(ILogger<GlobalExceptionFilter> logger)
    {
        _logger = logger;
    }

    public void OnException(ExceptionContext context)
    {
        _logger.LogError($"Exception filter caught an exception: {context.Exception.Message}");
        context.ExceptionHandled = true;

        context.Result = new JsonResult(new ErrorDetails()
            {
                StatusCode = context.HttpContext.Response.StatusCode,
                Message = "Error from Global Exception Filter."
            })
            { StatusCode = StatusCodes.Status500InternalServerError };
    }
}

Registering Both in Startup.cs or Program.cs

// For .NET Core 3.x
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options => 
    {
        options.Filters.Add(typeof(GlobalExceptionFilter));
    });

    services.AddLogging();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseMiddleware<ExceptionHandlerMiddleware>();
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

// For .NET 6+
public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddControllers(options => 
        {
            options.Filters.Add(typeof(GlobalExceptionFilter));
        });
        builder.Services.AddLogging();

        var app = builder.Build();

        if (app.Environment.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseMiddleware<ExceptionHandlerMiddleware>();
        app.UseRouting();
        app.UseAuthorization();
        app.MapControllers();
        app.Run();
    }
}

Handling Different Types of Exceptions

In real-world applications, it’s often necessary to handle different types of exceptions differently. For instance, validation errors might warrant a 400 Bad Request response, whereas a database connection failure should trigger a 503 Service Unavailable response.

You can achieve differentiated exception handling by:

• Checking the Exception Type: In both middleware and filters, inspect the type of the exception to determine the appropriate course of action.
• Mapping Exceptions to Status Codes: Create a mapping between particular exceptions and corresponding HTTP status codes for more standardized responses.
• Returning Detailed Information: Depending on the environment (development vs. production), return more detailed information about the error in development builds.

Here’s an improved version of the middleware to handle different types of exceptions:

Differentiated Middleware Example

private async Task HandleExceptionAsync(HttpContext context, Exception exception)
{
    var code = HttpStatusCode.InternalServerError; // 500 if unexpected

    if (exception is ValidationException) code = HttpStatusCode.BadRequest;
    else if (exception is NotFoundHttpException) code = HttpStatusCode.NotFound;
    else if (exception is UnauthorizedAccessException) code = HttpStatusCode.Unauthorized;
    // Add more mappings as needed

    context.Response.ContentType = "application/json";
    context.Response.StatusCode = (int)code;

    await context.Response.WriteAsync(
        JsonConvert.SerializeObject(
            new ErrorDetails()
            {
                StatusCode = (int)code,
                Message = $"Error from Exception Handler Middleware: {exception.Message}"
            }));
}

Logging Exceptions

Exception logging is critical for diagnosing issues and improving the reliability of your application. ASP.NET Core’s built-in logging system supports various providers and configurations, allowing you to choose the best fit for your needs.

Logging in Middleware

private async Task HandleExceptionAsync(HttpContext context, Exception exception)
{
    context.Response.ContentType = "application/json";
    context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;

    // Log the exception
    _logger.LogCritical(exception, "Critical exception caught!");

    await context.Response.WriteAsync(
        JsonConvert.SerializeObject(
            new ErrorDetails()
            {
                StatusCode = (int)HttpStatusCode.InternalServerError,
                Message = "Critical server error occurred."
            }));
}

Logging in Filters

public void OnException(ExceptionContext context)
{
    _logger.LogCritical(context.Exception, "Critical exception caught by filter!");

    context.ExceptionHandled = true;

    context.Result = new JsonResult(new ErrorDetails()
        {
            StatusCode = context.HttpContext.Response.StatusCode,
            Message = "Error from Global Exception Filter."
        })
        { StatusCode = StatusCodes.Status500InternalServerError };
}

Logging Providers

ASP.NET Core supports multiple logging providers, including:

• Console: Output logs to the console; useful during development.
• Debug: Send logs to the debug output window, typically via Visual Studio's "Output" panel.
• EventSource/EventLog: Use Windows EventLog or ETW for tracking application events.
• Serilog/NLog: Third-party logging libraries that offer advanced features such as asynchronous logging, structured data, and configurable sinks.

Configuring Logging Providers

public void ConfigureServices(IServiceCollection services)
{
    services.AddLogging(loggingBuilder =>
    {
        loggingBuilder.ClearProviders(); // Clear existing providers
        loggingBuilder.AddConsole();      // Use Console provider
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, ILogger<Startup> logger)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseMiddleware<ExceptionHandlerMiddleware>();

    // Additional pipeline configuration
}

Returning Custom JSON Responses

When catching exceptions, returning a consistent JSON response format can significantly improve the maintainability and usability of your Web API. Here’s how you can format and return custom JSON responses:

Error Details Model

public class ErrorDetails
{
    public int StatusCode { get; set; }
    public string Message { get; set; }
    public List<string> Errors { get; set; } // To include specific validation errors, etc.
}

Returning Custom JSON in Middleware

private async Task HandleExceptionAsync(HttpContext context, Exception exception)
{
    context.Response.ContentType = "application/json";
    context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;

    await context.Response.WriteAsync(JsonConvert.SerializeObject(new ErrorDetails()
    {
        StatusCode = (int)HttpStatusCode.InternalServerError,
        Message = exception.Message,
        Errors = exception is ValidationException ? ((ValidationException)exception).Errors : null
    }));
}

Returning Custom JSON in Filters

public void OnException(ExceptionContext context)
{
    var result = new JsonResult(new ErrorDetails()
    {
        StatusCode = context.HttpContext.Response.StatusCode,
        Message = context.Exception.Message,
        Errors = context.Exception is ValidationException ? ((ValidationException)context.Exception).Errors : null
    })
    {
        StatusCode = StatusCodes.Status500InternalServerError,
    };

    context.Result = result;
    context.ExceptionHandled = true;
}

Using Problem Details (RFC 7807 Standard)

To adhere to modern standards for error reporting, consider using Problem Details. Problem Details is defined in RFC 7807 and provides a more structured format for error responses.

Problem Details Model

public class ProblemDetails
{
    [JsonPropertyName("type")]
    public Uri? Type { get; set; }

    [JsonPropertyName("title")]
    public string Title { get; set; }

    [JsonPropertyName("status")]
    public int? Status { get; set; }

    [JsonPropertyName("detail")]
    public string? Detail { get; set; }

    [JsonPropertyName("instance")]
    public Uri? Instance { get; set; }

    [JsonExtensionData]
    public IDictionary<string, object?> Extensions { get; set; } = new Dictionary<string, object?>();
}

Returning Problem Details in Middleware

private async Task HandleExceptionAsync(HttpContext context, Exception exception)
{
    var code = HttpStatusCode.InternalServerError; // Default
    var problemDetails = new ProblemDetails()
    {
        Title = "An error occurred",
        Status = (int)code,
        Detail = exception.Message,
        Instance = context.Request.Path,
    };

    if (exception is ValidationException)
    {
        problemDetails.Title = "Your request contains validation errors.";
        problemDetails.Type = new Uri("https://httpstatuses.com/400");
        problemDetails.Status = (int)HttpStatusCode.BadRequest;
        problemDetails.Extensions["errors"] = ((ValidationException)exception).Errors;
    }
    else if (exception is UnauthorizedAccessException)
    {
        problemDetails.Title = "You don't have the required authorization.";
        problemDetails.Status = (int)HttpStatusCode.Unauthorized;
        problemDetails.Type = new Uri("https://httpstatuses.com/401");
    }

    context.Response.ContentType = "application/problem+json";
    context.Response.StatusCode = (int)problemDetails.Status;

    await context.Response.WriteAsync(JsonConvert.SerializeObject(problemDetails));
}

Returning Problem Details in Filters

public void OnException(ExceptionContext context)
{
    var code = HttpStatusCode.InternalServerError; // Default
    var problemDetails = new ProblemDetails()
    {
        Title = "An error occurred",
        Status = (int)code,
        Detail = context.Exception.Message,
        Instance = context.HttpContext.Request.Path,
    };

    if (context.Exception is ValidationException)
    {
        problemDetails.Title = "Your request contains validation errors.";
        problemDetails.Type = new Uri("https://httpstatuses.com/400");
        problemDetails.Status = (int)HttpStatusCode.BadRequest;
        problemDetails.Extensions["errors"] = ((ValidationException)context.Exception).Errors;
    }
    else if (context.Exception is UnauthorizedAccessException)
    {
        problemDetails.Title = "You don't have the required authorization.";
        problemDetails.Status = (int)HttpStatusCode.Unauthorized;
        problemDetails.Type = new Uri("https://httpstatuses.com/401");
    }

    var jsonResponse = new ContentResult()
    {
        StatusCode = (int)problemDetails.Status!,
        ContentType = "application/problem+json",
        Content = JsonConvert.SerializeObject(problemDetails),
    };

    context.Result = jsonResponse;
    context.ExceptionHandled = true;
}

Preventing Sensitive Information Leakage

In production environments, it’s essential to prevent the leakage of sensitive information through error messages. Instead of displaying detailed exception messages to the end-user, return generic error messages and log the sensitive details for internal debugging purposes.

Example of Suppressing Sensitive Information

private async Task HandleExceptionAsync(HttpContext context, Exception exception)
{
    context.Response.ContentType = "application/problem+json";
    context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;

    var problemDetails = new ProblemDetails()
    {
        Title = "An error occurred.",
        Status = (int)HttpStatusCode.InternalServerError,
        Detail = (!context.HostingEnvironment.IsProduction()) ? exception.Message : "Unexpected server error.",
        Instance = context.Request.Path,
    };

    _logger.LogCritical(exception, "Critical exception caught!");

    await context.Response.WriteAsync(JsonConvert.SerializeObject(problemDetails));
}

Conclusion

Mastering global exception handling in ASP.NET Web API applications is vital for building robust, user-friendly, and secure web services. By leveraging the strengths of middleware and filters, you can effectively manage exceptions and return appropriate responses based on different error scenarios.

• Middleware offers a simple and efficient mechanism for handling exceptions early in the request pipeline and is suitable for handling exceptions that occur outside the MVC framework.
• Filters provide enhanced control over exceptions within MVC actions, making them ideal for applications heavily utilizing the MVC functionalities and requiring granular exception handling rules.

Combining both approaches ensures that your application can handle a wide range of exceptions gracefully, providing consistent and detailed error reporting.