Come gestire gli errori nelle app per le API minime

Con i contributi di David Acker

Questo articolo descrive come gestire gli errori nelle app per le API minime.

Eccezioni

In un'app per le API minima sono disponibili due meccanismi centralizzati predefiniti diversi per gestire le eccezioni non gestite:

• Middleware della pagina eccezioni per sviluppatori (solo per l'uso nell'ambiente di sviluppo).
• Middleware del gestore eccezioni

Questa sezione fa riferimento all'app per le API minima seguente per illustrare i modi per gestire le eccezioni. Genera un'eccezione quando viene richiesto l'endpoint /exception :

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/exception", () => 
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

Pagina delle eccezioni per gli sviluppatori

La pagina Eccezioni sviluppatore mostra analisi dettagliate dello stack per gli errori del server. DeveloperExceptionPageMiddleware Usa per acquisire eccezioni sincrone e asincrone dalla pipeline HTTP e per generare risposte di errore.

ASP.NET App core abilitano la pagina delle eccezioni per sviluppatori per impostazione predefinita quando entrambe:

• Esecuzione nell'ambiente di sviluppo.
• L'app usa WebApplication.CreateBuilder.

Per altre informazioni sulla configurazione del middleware, vedere Middleware nelle app per le API minime.

Usando l'app per le API minima precedente, quando rileva un'eccezione Developer Exception Page non gestita, genera una risposta di testo normale predefinita simile all'esempio seguente:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8
Date: Thu, 27 Oct 2022 18:00:59 GMT
Server: Kestrel
Transfer-Encoding: chunked

    System.InvalidOperationException: Sample Exception
    at Program.<>c.<<Main>$>b__0_1() in ....:line 17
    at lambda_method2(Closure, Object, HttpContext)
    at Microsoft.AspNetCore.Routing.EndpointMiddleware.Invoke(HttpContext httpContext)
    --- End of stack trace from previous location ---
    at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddlewareImpl.Invoke(HttpContext context)
HEADERS
=======
Accept: */*
Connection: keep-alive
Host: localhost:5239
Accept-Encoding: gzip, deflate, br

Avviso

Non abilitare la pagina eccezioni per sviluppatori a meno che l'app non sia in esecuzione nell'ambiente di sviluppo. Non condividere pubblicamente informazioni dettagliate sulle eccezioni quando l'app viene eseguita nell'ambiente di produzione. Per altre informazioni sulla configurazione degli ambienti, vedere Usare più ambienti in ASP.NET Core.

Gestore di eccezioni

Negli ambienti non di sviluppo usare il middleware del gestore eccezioni per generare un payload di errore. Per configurare Exception Handler Middleware, chiamare UseExceptionHandler.

Ad esempio, il codice seguente modifica l'app per rispondere con un payload conforme a RFC 7807 al client. Per altre informazioni, vedere la sezione Dettagli problema.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseExceptionHandler(exceptionHandlerApp 
    => exceptionHandlerApp.Run(async context 
        => await Results.Problem()
                     .ExecuteAsync(context)));

app.MapGet("/exception", () => 
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

Risposte di errore client e server

Si consideri l'app per le API minima seguente.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)));

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

L'endpoint /users produce con una json rappresentazione di quando id è maggiore di 0, in caso contrario un 400 BAD REQUEST codice di User stato senza un 200 OK corpo della risposta. Per altre informazioni sulla creazione di una risposta, vedere Creare risposte nelle app per le API minime.

Status Code Pages middleware Può essere configurato per produrre un contenuto del corpo comune, se vuoto, per tutte le risposte client HTTP (499-400) o server ().500 -599 Il middleware viene configurato chiamando il metodo di estensione UseStatusCodePages .

Ad esempio, l'esempio seguente modifica l'app in modo che risponda con un payload conforme a RFC 7807 al client per tutte le risposte client e server, inclusi gli errori di routing (ad esempio, 404 NOT FOUND). Per altre informazioni, vedere la sezione Dettagli problema.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseStatusCodePages(async statusCodeContext 
    => await Results.Problem(statusCode: statusCodeContext.HttpContext.Response.StatusCode)
                 .ExecuteAsync(statusCodeContext.HttpContext));

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Dettagli del problema

I dettagli del problema non sono l'unico formato di risposta per descrivere un errore dell'API HTTP, ma vengono comunemente usati per segnalare errori per le API HTTP.

Il servizio dettagli problema implementa l'interfaccia , che supporta la IProblemDetailsService creazione dei dettagli del problema in ASP.NET Core. Il AddProblemDetails metodo di estensione in IServiceCollection registra l'implementazione predefinita IProblemDetailsService .

In ASP.NET app Core, il middleware seguente genera risposte HTTP con dettagli del problema quando AddProblemDetails viene chiamato, tranne quando l'intestazione HTTP della Accept richiesta non include uno dei tipi di contenuto supportati dal registrato IProblemDetailsWriter (impostazione predefinita: application/json):

• ExceptionHandlerMiddleware: genera una risposta ai dettagli del problema quando un gestore personalizzato non è definito.
• StatusCodePagesMiddleware: genera una risposta ai dettagli del problema per impostazione predefinita.
• DeveloperExceptionPageMiddleware: genera una risposta ai dettagli del problema durante lo sviluppo quando l'intestazione HTTP della Accept richiesta non include text/html.

Le app per le API minime possono essere configurate per generare la risposta ai dettagli del problema per tutte le risposte di errore del client HTTP e del server che non hanno ancora un contenuto del corpo usando il AddProblemDetails metodo di estensione.

Il codice seguente configura l'app per generare i dettagli del problema:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)));

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

Per altre informazioni sull'uso AddProblemDetailsdi , vedere Dettagli del problema

Fallback IProblemDetailsService

Nel codice seguente restituisce httpContext.Response.WriteAsync("Fallback: An error occurred.") un errore se l'implementazione IProblemDetailsService non è in grado di generare :ProblemDetails

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler(exceptionHandlerApp =>
{
    exceptionHandlerApp.Run(async httpContext =>
    {
        var pds = httpContext.RequestServices.GetService<IProblemDetailsService>();
        if (pds == null
            || !await pds.TryWriteAsync(new() { HttpContext = httpContext }))
        {
            // Fallback behavior
            await httpContext.Response.WriteAsync("Fallback: An error occurred.");
        }
    });
});

app.MapGet("/exception", () =>
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

Il codice precedente:

• Scrive un messaggio di errore con il codice di fallback se non problemDetailsService è in grado di scrivere un oggetto ProblemDetails. Ad esempio, un endpoint in cui l'intestazione Accetta richiesta specifica un tipo di supporto non DefaulProblemDetailsWriter supportato da .
• Usa il middleware del gestore eccezioni.

L'esempio seguente è simile a quello precedente, ad eccezione del fatto che chiama .Status Code Pages middleware

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseStatusCodePages(statusCodeHandlerApp =>
{
    statusCodeHandlerApp.Run(async httpContext =>
    {
        var pds = httpContext.RequestServices.GetService<IProblemDetailsService>();
        if (pds == null
            || !await pds.TryWriteAsync(new() { HttpContext = httpContext }))
        {
            // Fallback behavior
            await httpContext.Response.WriteAsync("Fallback: An error occurred.");
        }
    });
});

app.MapGet("/users/{id:int}", (int id) =>
{
    return id <= 0 ? Results.BadRequest() : Results.Ok(new User(id));
});

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);