Custom error handling in .NET6

[thoma01]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

In the releases of v6.x.x of this package, IErrorResponseProvider was removed in favor of ProblemDetails.

All the examples show how to .AddProblemDetails() but unfortunately, they all target .NET7.

How is this supposed to be handled in .NET6? I need to be able to support backwards compatibility for my error messages, but this change does not really explain how to achieve this?

Expected Behavior

No response

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

6

Anything else?

No response

[commonsensesoftware]

In .NET 6 and, hence, 6.x there was no common interface for Problem Details. Unfortunately, this meant I had to create my own, but it was quickly fixed and supplanted in .NET 7.

What you are looking for is the IProblemDetailsFactory service. The change and customization will depend on whether you are using Minimal APIs or MVC Core. The DefaultProblemDetailsFactory is used for Minimal APIs, whereas MvcProblemDetailsFactory provides a decorated adapter over ProblemDetailsFactory which was only available for MVC Core.

ProblemDetails exists across the board and should be the same for .NET 6+. The only difference is how you customize their generation. If you've already customized MVC Core, then it should just work; otherwise, you can choose whether to replace IProblemDetailsFactory, ProblemDetailsFactory, or potential both.

[commonsensesoftware]

This question has been asked before, but I guess it's not in the documentation. There have never been any specific examples for changing the behavior. I've updated the Error Responses topic in the wiki to highlight the differences.

[thoma01]

Actually the reason that I ask is, I am looking for a way to customize the error response format to continue following the Microsoft REST Guidelines error response format, as we have already released our v1 API using this format.

In earlier versions, the error responses bodies complied with the Microsoft REST Guidelines error response format, which is itself the error response format used by the OData protocol (see OData JSON Format §21.1). There wasn't a broad standard at that time, which made any common error response format sensible.

We are using OData so we are unable to use the official Microsoft versioning package. We tried to switch to this package, but we lost the ability to register our implementation of IErrorResponseProvider which we were using to format our errors before.

We were hoping to not have to use Problem Details as that would break our API compatibility for existing customers in our v1. Is it possible to intercept/override something to continue to format the errors to match the Microsoft REST Guidelines.

[commonsensesoftware]

I'm not sure I follow:

We are using OData so we are unable to use the official Microsoft versioning package

There is no other package or project for ASP.NET API Versioning. This is the one and only. You can thank Microsoft for the name change. ☹️What is the specific issue or gap with OData?

Now that I know what you are trying to achieve, let me see if I can't provide an example of how to achieve the results you're looking for. 😄

[commonsensesoftware]

It was surprisingly easier than I thought it would be. Here is a rough solution that would work:

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;
using System.Text.Json;
using System.Text.Json.Serialization;

public class ErrorObjectConverter : JsonConverter<ProblemDetails>
{
    public override void Write(
        Utf8JsonWriter writer,
        ProblemDetails value,
        JsonSerializerOptions options )
    {
        if ( IsSupported( value ) )
        {
            WriteErrorObject( writer, value, options );
        }
        else
        {
            options = new JsonSerializerOptions( options );
            options.Converters.Remove( this );
            JsonSerializer.Serialize( writer, value, options );
        }
    }

    protected virtual void WriteErrorObject(
        Utf8JsonWriter writer,
        ProblemDetails problemDetails,
        JsonSerializerOptions options )
    {
        writer.WriteStartObject();
        writer.WriteStartObject( "error" );

        if ( problemDetails.Extensions.TryGetValue( "code", out var value ) )
        {
            writer.WriteString( "code", value.ToString() );
        }

        writer.WriteString( "message", problemDetails.Title );

        if ( !string.IsNullOrEmpty( problemDetails.Instance ) )
        {
            writer.WriteString( "target", problemDetails.Instance );
        }

        if ( !string.IsNullOrEmpty( problemDetails.Detail ) )
        {
            writer.WriteStartArray( "details" );
            writer.WriteStringValue( problemDetails.Detail );
            writer.WriteEndArray();
        }

        writer.WriteEndObject();
        writer.WriteEndObject();
    }

    public override ProblemDetails Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options ) => throw new NotSupportedException();

    private static bool IsSupported( ProblemDetails problemDetails )
    {
        if ( problemDetails.Type == ProblemDetailsDefaults.Unsupported.Type )
        {
            return true;
        }

        if ( problemDetails.Type == ProblemDetailsDefaults.Unspecified.Type )
        {
            return true;
        }

        if ( problemDetails.Type == ProblemDetailsDefaults.Invalid.Type )
        {
            return true;
        }

        if ( problemDetails.Type == ProblemDetailsDefaults.Ambiguous.Type )
        {
            return true;
        }

        return false;
    }
}

There are a few ways you can register the converter, but the simplest method would look like:

// CAUTION: note the ambiguity between:
// - Microsoft.AspNetCore.Http.Json.JsonOptions
// - Microsoft.AspNetCore.Mvc.JsonOptions
//
// You need the former as that is purely routing without any part of MVC
builder.Services.Configure<Microsoft.AspNetCore.Http.Json.JsonOptions>(
    options => options.SerializerOptions.Converters.Insert( 0, new ErrorObjectConverter() ) );

// this should not be necessary, but note that you can cover MVC Core paths with the same converter
// builder.Services.Configure<Microsoft.AspNetCore.Mvc.JsonOptions>(
//    options => options.JsonSerializerOptions.Converters.Insert( 0, new ErrorObjectConverter() ) );

Let's say a client requests https://localhost:5001/api/values?api-version=42.0. This would normally produce the response:

{
    "type": "https://docs.api-versioning.org/problems#unsupported",
    "title": "Unsupported API version",
    "status": 400,
    "detail": "The HTTP resource that matches the request URI 'https://localhost:5001/api/values' does not support the API version '42.0'.",
    "code": "UnsupportedApiVersion",
    "traceId": "00-9956265f482c96f8478349bb1403427e-f7267eaaa2a7891d-00"
}

However, with the converter in place, it will now produce:

{
    "error":
    {
        "code": "UnsupportedApiVersion",
        "message": "Unsupported API version",
        "details":
        [
            "The HTTP resource that matches the request URI 'https://localhost:5001/api/values' does not support the API version '42.0'."
        ]
    }
}

The example provided will only convert ProblemDetails generated by API Versioning. ProblemDetails produced through other methods will be left unchanged.

I haven't received many requests for it, but this should be a generic solution that can provide a solid backward compatibility story, which - to be honest - is missing. I need a little bit more time to think about the edge cases, configuration, and testing, but this approach should unblock you in the meantime. Any other thoughts or feedback you have are welcome.

[thoma01]

I have tried enabling ProblemDetails in .NET6 by adding Hellang.Middleware.ProblemDetails nuget package. By doing this, when I specify an unsupported/invalid API version, I simply get a response:
{ "type": "https://httpstatuses.io/404", "title": "Not Found", "status": 404, "traceId": "00-5341acdcb4838e1a124c2700a1d20633-4056df7593bf3343-00" }

How are you enabling ProblemDetails for API versioning in .NET 6?

[commonsensesoftware]

Danger Will Robinson! <you are going down the proverbial rabbit hole 😉>

ProblemDetails existed in .NET 6. Despite the namespace, the class in located in the HTTP extensions, not MVC Core:

https://github.com/dotnet/aspnetcore/blob/42af1fe8be1869b034feeec5aaefc0efb561564f/src/Http/Http.Extensions/src/ProblemDetails.cs#L13

This means it was possible to generate ProblemDetails in .NET 6, ASP.NET Core 6, and API Versioning 6.x. Problem Details are generated for all API Versioning Endpoint types. You're getting into the bowels of routing, but it's located here:

aspnet-api-versioning/src/AspNetCore/WebApi/src/Asp.Versioning.Http/Routing/EdgeBuilder.cs

Line 35 in c462195

[EdgeKey.Malformed] = new( capacity: 1 ) { new MalformedApiVersionEndpoint( logger ) },

Unfortunately, this doesn't cover every single edge case because ASP.NET Core itself doesn't provide Problem Details or hooks to provide one for some cases such as 415. As linked above, API Versioning introduced IProblemDetailsFactory so that it didn't have a hard dependency on MVC Core a la the ProblemDetailsFactory abstract class. I presumed the ASP.NET team would fix the issue at some point and they did in .NET 7 (sooner than I expected). The DefaultProblemDetailsFactory (also linked above) essentially does the same thing as the MVC Core implementation, but can be used for Minimal APIs and only requires the core routing system. The detail for each scenario can be found in:

• AmbiguousApiVersionEndpoint.cs
• MalformedApiVersionEndpoint.cs
• NotAcceptableEndpoint.cs
• UnspecifiedApiVersionEndpoint.cs
• UnsupportedApiVersionEndpoint.cs
• UnsupportedMediaTypeEndpoint.cs

If the routing system lands on any one of these endpoints, you'll get a ProblemDetails instance. The MVC extensions replace and decorate DefaultProblemDetailsFactory with MvcProblemDetailsFactory (also linked above). You can see that happen here:

aspnet-api-versioning/src/AspNetCore/WebApi/src/Asp.Versioning.Mvc/DependencyInjection/IApiVersioningBuilderExtensions.cs

Line 79 in c462195

services.TryReplace( typeof( DefaultProblemDetailsFactory ), Singleton<IProblemDetailsFactory, MvcProblemDetailsFactory>() );

The idea is that you may have already changed MVC Core's default implementation of ProblemDetailsFactory or you may just want to completely replace API Versioning's IProblemDetailsFactory. There shouldn't be a need to do both.

Using the JsonConverter<T> that I provided, you have a path to convert the ProblemDetails instances into the Error Object format (from OData) that is used in the Microsoft REST API Guidelines. You can go with that approach at any time. I should have a working out-of-the-box extension that can retain the old behavior that you are looking for in a few days.

[thoma01]

I believe to have found the confusion of why I thought ProblemDetails were not enabled.

In API Versioning 5.x, we were able to set ErrorResponses in ApiVersioningOptions. This allowed us to customize the response format as we saw fit.

In API Versioning 6.x, we no longer have that ability and you are proposing we implement a JsonConverter<T> to intercept these ProblemDetails and write them as we please.

However, when versioning by URL segment only, we get a 404 response, with no body (ie. no ProblemDetails). When we enable the other versioning reader methods (query string and/or http header), we do get ProblemDetails when providing the version by 1 of these methods.

We are only using URL segment versioning, and in API Versioning 5.x we were able to rewrite the errors using the ErrorResponses field from ApiVersioningOptions. Now in API Versioning 6.x, we can no longer do that, and if there are no ProblemDetails for URL segment only versioning responses, then we cannot maintain consistency in our errors. This is a breaking change.

Additionally, the HTTP Status Code has changed between 5.x and 6.x for URL segment only, from 400 to 404. This is also a breaking change.