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. Per informazioni sulla gestione degli errori nelle API basate su controller, vedere Gestire gli errori in ASP.NET Core e Gestire gli errori nelle API Web basate su controller di base ASP.NET.

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 di esempio seguente per illustrare i modi per gestire le eccezioni in un'API minima. 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

Nella pagina Eccezioni sviluppatore vengono visualizzate informazioni dettagliate sulle eccezioni di richiesta non gestite. DeveloperExceptionPageMiddleware Usa per acquisire eccezioni sincrone e asincrone dalla pipeline HTTP e per generare risposte di errore. La pagina delle eccezioni dello sviluppatore viene eseguita nelle prime fasi della pipeline middleware, in modo che possa rilevare eccezioni non gestite generate nel middleware che segue.

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

• Esecuzione nell'ambiente di sviluppo.
• L'app è stata creata con i modelli correnti, ovvero usando WebApplication.CreateBuilder.

Le app create usando i modelli precedenti, ovvero usando WebHost.CreateDefaultBuilder, possono abilitare la pagina delle eccezioni per sviluppatori chiamando app.UseDeveloperExceptionPage.

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.

La pagina Delle eccezioni per sviluppatori può includere le informazioni seguenti sull'eccezione e sulla richiesta:

• Analisi dello stack
• Parametri della stringa di query, se presenti
• Cookie, se presenti
• Intestazioni
• Metadati dell'endpoint, se presenti

La pagina Delle eccezioni per gli sviluppatori non fornisce alcuna informazione. Usare Registrazione per informazioni complete sull'errore.

L'immagine seguente mostra una pagina di eccezioni per sviluppatori di esempio con animazione per visualizzare le schede e le informazioni visualizzate:

In risposta a una richiesta con un'intestazione Accept: text/plain , la pagina eccezioni sviluppatore restituisce testo normale anziché HTML. Ad esempio:

Status: 500 Internal Server Error
Time: 9.39 msSize: 480 bytes
FormattedRawHeadersRequest
Body
text/plain; charset=utf-8, 480 bytes
System.InvalidOperationException: Sample Exception
   at WebApplicationMinimal.Program.<>c.<Main>b__0_0() in C:\Source\WebApplicationMinimal\Program.cs:line 12
   at lambda_method1(Closure, Object, HttpContext)
   at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddlewareImpl.Invoke(HttpContext context)

HEADERS
=======
Accept: text/plain
Host: localhost:7267
traceparent: 00-0eab195ea19d07b90a46cd7d6bf2f

Per visualizzare la pagina delle eccezioni per sviluppatori:

• Eseguire l'app di esempio nell'ambiente di sviluppo.
• Passare all'endpoint /exception .

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 più avanti in questo articolo.

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(IServiceCollection) 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 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);