Come gestire gli errori nelle app per le API minime

  • Articolo

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere Criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

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:

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:

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:

Pagina delle eccezioni per gli sviluppatori animata per visualizzare ogni scheda selezionata.

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):

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

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:

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.Map("/exception", () 
    => { throw new InvalidOperationException("Sample 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:

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.Map("/exception", () 
    => { throw new InvalidOperationException("Sample 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.Map("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

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.Map("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

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):

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.Map("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

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

app.Run();

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