Exception handing in .NET - standardize exceptions using ProblemDetails

.NET ProblemDetails Error Handling: Understanding the Standard Error Response Format

Error handling is an important aspect of any software application, and it’s crucial that it’s done in a standard way so that clients and API consumers know how to handle it. In ASP.NET Core, the standard error response format is represented by the ProblemDetails model. In this article, we will discuss the ProblemDetails model and how it’s used for error handling in .NET applications.

What is ProblemDetails in .NET?

ProblemDetails is a model in ASP.NET Core that represents an error response in a standard format. It provides a convenient way to return errors to API consumers and clients, and it’s designed to be machine-readable and human-readable at the same time. The ProblemDetails model is based on the IETF standard called “Problem Details for HTTP APIs”. This standard defines a way to represent errors in a common format that can be understood by both machines and humans.

The ProblemDetails model has several properties that are used to describe the error, such as:

• Type: This property is a URI that identifies the problem type. It can be used to categorize the error into different groups.
• Title: This property provides a brief description of the error.
• Status: This property represents the HTTP status code of the error.
• Detail: This property contains a more detailed description of the error.
• Instance: This property is a URI that provides more information about the error.

How to Use ProblemDetails for Error Handling in .NET

ProblemDetails is used in ASP.NET Core to handle errors in a standard way. When an error occurs in an application, it can be returned as a ProblemDetails object. The following is an example of how to return a ProblemDetails object in an action method:

[HttpGet("{id}")]
public IActionResult Get(int id)
{
    if (id == 0)
    {
        var problemDetails = new ProblemDetails
        {
            Type = "https://example.com/errors/invalid-id",
            Title = "Invalid ID",
            Status = 400,
            Detail = "The ID provided is invalid.",
            Instance = "https://example.com/errors/instance/1"
        };

        return BadRequest(problemDetails);
    }

    // code to return a valid response
}

Using ProblemDetails Middleware

In ASP.NET Core, middleware is a component that sits between the server and the application, and it’s responsible for handling requests and responses. Middleware can be used to handle errors in a standard way, by returning a ProblemDetails object when an error occurs.

Here’s an example of how to use ProblemDetails in middleware:

public class ExceptionMiddleware
{
    private readonly RequestDelegate _next;

    public ExceptionMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            var problemDetails = new ProblemDetails
            {
                Type = "https://example.com/errors/internal-server-error",
                Title = "Internal Server Error",
                Status = 500,
                Detail = ex.Message,
                Instance = "https://example.com/errors/instance/1"
            };

            context.Response.StatusCode = 500;
            context.Response.ContentType = "application/problem+json";

            await context.Response.WriteAsync(JsonSerializer.Serialize(problemDetails));
        }
    }
}

In this example, the middleware component is a class called ExceptionMiddleware. The middleware is registered in the Startup.cs file, in the Configure method, like this:

app.UseMiddleware<ExceptionMiddleware>();

By using middleware for error handling, you can ensure that your application returns errors in a standard format, even if the error occurs outside of a controller action. This makes it easier to understand and handle errors, and it also makes your application more user-friendly.

ProblemDetail Generic error Customization

In ASP.NET Core, you can use the AddProblemDetails extension method to add custom handling for ProblemDetails objects in your application. The AddProblemDetails method allows you to register custom handlers for specific exception types, so that you can return customized ProblemDetails objects for different types of errors.

Here’s an example of how to use AddProblemDetails to add custom handling:

  
// in the main 
// builder.Services.AddProblemDetails(ConfigureProblemDetails).AddProblemDetailsConventions();


private static void ConfigureProblemDetails(ProblemDetailsOptions options)
        {
            // inclustion of Exception
            options.IncludeExceptionDetails = (httpContext, exception) => exception is not ValidationException &&
                                                                          exception is not NotFoundException;
            options.MapNotFoundException(); // Custom error mapping
            options.ValidationProblemStatusCode = StatusCodes.Status400BadRequest;
            options.MapToStatusCode<NotFoundException>(StatusCodes.Status404NotFound);
            options.MapToStatusCode<Exception>(StatusCodes.Status500InternalServerError);
            options.OnBeforeWriteDetails = (ctx, pr) =>
            {
                // Serilog message logging
                Log.Logger.Error("The error {@Error}", pr);
            };
        }

    public static class ProblemDetailsOptionsExtensions
    {
        public static void MapNotFoundException(this ProblemDetailsOptions options) =>
        options.Map<NotFoundException>((ctx, ex) =>
        {
            var factory = ctx.RequestServices.GetRequiredService<ProblemDetailsFactory>();

            return factory.CreateProblemDetails(ctx, statusCode: StatusCodes.Status404NotFound, detail: ex.Message);
        });
    }

Conclusion

In conclusion, ProblemDetails is a model in ASP.NET Core that represents an error response in a standard format. It provides a convenient way to return errors to API consumers and clients, and it’s designed to be machine-readable and human-readable at the same time. By using ProblemDetails for error handling in your .NET application, you can ensure that your application returns errors in a standard format, making it easier to understand and handle errors.