Sondor.AspNetCore 0.2.0

Prefix Reserved
dotnet add package Sondor.AspNetCore --version 0.2.0
                    
NuGet\Install-Package Sondor.AspNetCore -Version 0.2.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Sondor.AspNetCore" Version="0.2.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Sondor.AspNetCore" Version="0.2.0" />
                    
Directory.Packages.props
<PackageReference Include="Sondor.AspNetCore" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Sondor.AspNetCore --version 0.2.0
                    
#r "nuget: Sondor.AspNetCore, 0.2.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Sondor.AspNetCore@0.2.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Sondor.AspNetCore&version=0.2.0
                    
Install as a Cake Addin
#tool nuget:?package=Sondor.AspNetCore&version=0.2.0
                    
Install as a Cake Tool

Sondor.AspNetCore

One consistent RFC 9457 problem response for an ASP.NET Core API. A failed Sondor.Results Result, an unhandled exception and the framework's own bare 401 or 404 all leave the service with the same shape, a stable error code and a trace id.

It builds on what the framework already provides (ProblemDetails, IExceptionHandler, status code pages) and adds no middleware of its own. It works in minimal APIs and in MVC.

dotnet add package Sondor.AspNetCore
builder.Services.AddSondorProblemDetails();

var app = builder.Build();

app.UseSondorProblemDetails();       // first: exception handler + problem bodies for bare 401/404/...

app.MapGet("/orders/{id}", (Guid id, IOrders orders) => orders.Find(id).ToHttpResult());
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "detail": "No Order was found for the given Id.",
  "instance": "/orders/6f0e...",
  "errorCode": "Resource.NotFound",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

What it does

  • Result to response. result.ToHttpResult() is 204 or 200 with the value on success, and a problem response on failure. The status comes from the error's ErrorType; the errorCode member is its stable Code.
  • Exceptions. An unhandled exception in an API request becomes a generic 500. Its message and stack trace are logged and never sent. Map the exceptions you expect to an Error and they are reported like any other.
  • The framework's own errors. A bare 404, a 401, an unsupported media type or an invalid body get the same shape and an errorCode, so a client handles one format.
  • One code per error, never translated. Clients branch on errorCode. Only title and detail are for people (see Translated text).

If you do not return Result values and are happy with the framework's AddProblemDetails() and an IExceptionHandler of your own, you do not need this package. It is for services where failures are values and every error should look the same.

Using a result

// minimal API
app.MapGet("/orders/{id}", (Guid id, IOrders orders) => orders.Find(id).ToHttpResult());

// something other than 200: you decide what a success looks like
app.MapPost("/orders", (NewOrder order, IOrders orders) =>
    orders.Create(order).ToHttpResult(created => TypedResults.Created($"/orders/{created.Id}", created)));

// MVC: an action may return IResult
[ApiController, Route("orders")]
public sealed class OrdersController(IOrders orders) : ControllerBase
{
    [HttpGet("{id}")]
    public IResult Get(Guid id) => orders.Find(id).ToHttpResult();
}

ToHttpResult() always writes a problem on failure, whatever the caller's Accept header says.

Rejecting a request from a middleware

Code that has no result to return, such as a middleware that refuses a request, reports an Error the same way:

app.Use(async (context, next) =>
{
    if (!context.Request.Headers.ContainsKey("User-Agent"))
    {
        var error = new Error("Request.UserAgentRequired", "A User-Agent header is required.", ErrorType.Validation);

        await error.ToHttpResult().ExecuteAsync(context);

        return;
    }

    await next(context);
});

The framework's rate limiter rejects with 503 by default, which is reported as Request.Unavailable. Set options.RejectionStatusCode = StatusCodes.Status429TooManyRequests and a rejected request is reported as Request.RateLimited. It sends no Retry-After header unless the limiter's OnRejected callback adds one.

Settings

Every setting has a default, so AddSondorProblemDetails() alone is a valid setup. They are validated when the host starts.

builder.Services.AddSondorProblemDetails(options =>
{
    options.TypeUriTemplate = "https://docs.example.com/errors/{code}";   // link each code to its documentation
    options.StatusByType[ErrorType.Validation] = 422;                     // change a status
    options.StatusByCode["Order.Late"] = 410;                             // or one code's status
});

They can also be bound from configuration: services.Configure<ErrorResponseOptions>(configuration.GetSection("Errors")).

Setting Default Meaning
StatusByType validation 400, unauthorized 401, forbidden 403, not found 404, conflict 409, rate limited 429, feature disabled 501, internal and failure 500 Status for each ErrorType. Statuses must be 400 to 599.
StatusByCode none The status of one code; wins over StatusByType.
TypeUriTemplate none The type of a problem, with {code} replaced (URL-escaped). Without it the framework's link to the HTTP status is kept.
ErrorCodeMember errorCode The name of the code member.
CodeByStatus 400 Request.Invalid, 401 Request.Unauthorized, 403 Request.Forbidden, 404 Request.NotFound, 409 Request.Conflict, 415 Request.UnsupportedMediaType, 429 Request.RateLimited, 499 Request.Cancelled, 503 Request.Unavailable, 504 Request.GatewayTimeout The code of a problem the framework made on its own. Other statuses get Request.Failed, or Error.Internal from 500.
HandleExceptions true Answer an unhandled exception with a problem.
WriteStatusCodeBodies true Give a bare error status a problem body.
IncludeExceptionDetails false Put an unexpected exception's message in detail. For development only.
BareTraceId false Use the trace id alone as traceId (handy to paste into a trace viewer) instead of the framework's full traceparent.
TagActivity true Tag the request's Activity with sondor.error.code (not error.type, which ASP.NET Core sets itself from .NET 11), and mark it failed from 500 up.
ClientClosedRequestStatus 499 The status when the caller disconnected before the answer. Never logged as an error.
AppliesTo API requests only Which requests get a problem response (see Pages and views).

Exceptions

An exception that is not mapped is a generic 500 (Error.Internal); the exception is logged with its trace id and the caller sees nothing about it. Map the ones you expect:

builder.Services.AddSondorProblemDetails(options =>
{
    options.Exceptions.Map<PaymentDeclinedException>(exception =>
        new Error("Payment.Declined", exception.Message, ErrorType.Conflict));
});

The error's description becomes detail, so it must be safe to show. A mapping applies to derived types too; the nearest type wins. A single AggregateException or TargetInvocationException is unwrapped first. A request whose caller disconnected is answered with ClientClosedRequestStatus and logged at debug level.

Pages and views

An app that serves Razor Pages or views next to an API keeps its own error pages. The exception handler and the status code bodies only answer requests AppliesTo accepts. By default that is:

  • an [ApiController] action or a minimal API: yes;
  • a Razor Page or a controller that is not an API controller: no;
  • a request with no endpoint yet (an unknown URL): yes, unless its Accept header prefers HTML.

For a request that is declined, register your own handler. UseExceptionHandler("/Error") works next to this package, because exception handlers registered here are asked first. (Do not call UseSondorProblemDetails() in that case: it adds the framework's parameterless UseExceptionHandler(), which answers a declined request itself.)

Extending it

All three are optional, and the package registers none of them.

// The words of a problem (title, detail), for example in the reader's language.
public interface IProblemTextProvider
{
    ProblemText? GetText(Error failure, HttpContext context);       // null: keep the error's English text
}

// More members on a problem, such as per-property validation errors.
public interface IProblemContributor
{
    void Contribute(ProblemContext context);
}

// How an Error becomes a problem at all.
public interface IErrorProblemFactory
{
    ProblemDetails Create(Error failure, HttpContext context, Exception? exception = null);
}

Register your own with services.AddSingleton<IProblemTextProvider, ...>(); register several contributors and each runs, in order. The error Code is never passed through the text provider: it is the contract with your clients.

Translated text

Translated title and detail come from an IProblemTextProvider. Sondor.Results.Localization turns an Error into text in the current culture from your own resources, and ASP.NET Core's request localization sets that culture from Accept-Language. An adapter package that connects the two is planned; until then it is a few lines:

internal sealed class LocalizedProblemText(IErrorLocalizer localizer) : IProblemTextProvider
{
    public ProblemText? GetText(Error failure, HttpContext context)
    {
        var text = localizer.Localize(failure);

        return new ProblemText(text.Title, text.Detail);
    }
}

The response format

These members are a promise. Changing a member's name or meaning is a breaking change, so a client can rely on them.

Member Meaning
type, title, status, detail, instance As in RFC 9457. instance is the request path.
errorCode The stable code of the error, Area.Reason. The name can be changed in the settings. Never translated.
traceId The trace of the request, to quote when reporting a problem.
errors Added by the framework to an invalid body: property name to messages.

The content type is application/problem+json.

Good to know

  • Call UseSondorProblemDetails() early, before routing and authentication, so the exception handler wraps everything after it. An app that wants to place the framework's UseExceptionHandler() and UseStatusCodePages() itself can skip it and call them.

  • AddSondorProblemDetails() calls the framework's AddProblemDetails(). Your own CustomizeProblemDetails still runs, after this package has set the code, so it can adjust it.

  • Headers set before an exception are lost. The framework's exception handler clears the response before it answers, so a header set the ordinary way (a security header, a CORS header, a correlation id) is missing from the problem response of an exception, whether it was set before the handler or after it. Only a header added in a Response.OnStarting callback survives, because that runs when the response starts, after the handler has finished. Set headers that must always be present like this:

    app.Use((context, next) =>
    {
        context.Response.OnStarting(() =>
        {
            context.Response.Headers["X-Content-Type-Options"] = "nosniff";
    
            return Task.CompletedTask;
        });
    
        return next(context);
    });
    
  • An exception thrown after the response has started cannot be answered; the framework handles that case as it always did.

  • Target framework: .NET 10.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Sondor.AspNetCore:

Package Downloads
Sondor.AspNetCore.FluentValidation

FluentValidation for Sondor.AspNetCore: a ValidationException is answered with a 400 problem response whose errors member lists the messages of each property, named as the API names its JSON properties.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.2.0 77 11/16/2026
0.1.0 105 11/13/2026