Condividi tramite

Gestire gli errori nelle API core di ASP.NET

Annotazioni

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

Avvertimento

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

Questo articolo descrive come gestire gli errori nelle API di base di ASP.NET. È selezionata la documentazione relativa alle API minime. Per visualizzare la documentazione per le API basate su controller, selezionare la scheda Controller. Per indicazioni sulla Blazor gestione degli errori, vedere Gestire gli errori nelle app ASP.NET CoreBlazor.

Pagina Eccezioni per 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.

Avvertimento

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 ASP.NET Ambienti di runtime di base.

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
  • Headers
  • 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. Per 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 in un'API minima:

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

Gestore 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 200 OK rappresentazione di quando json è maggiore di User, in caso contrario un id codice di 0 stato senza un 400 BAD REQUEST 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 (400-499) 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 dellaAccept 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:

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

Funzionalità aggiuntive per la gestione degli errori

Migrazione da controller a API minime

Se si esegue la migrazione dalle API basate su controller alle API minime:

  1. Sostituire i filtri azione con filtri endpoint o middleware
  2. Sostituire la convalida del modello con la convalida manuale o l'associazione personalizzata
  3. Sostituire i filtri delle eccezioni con il middleware di gestione delle eccezioni
  4. Configurare i dettagli del problema usando AddProblemDetails() per risposte di errore coerenti

Quando usare la gestione degli errori basata su controller

Se necessario, prendere in considerazione le API basate su controller:

  • Scenari di convalida dei modelli complessi
  • Gestione centralizzata delle eccezioni tra più controller
  • Controllo granulare sulla formattazione della risposta di errore
  • Integrazione con funzionalità MVC come filtri e convenzioni

Per informazioni dettagliate sulla gestione degli errori basata sul controller, inclusi gli errori di convalida, la personalizzazione dei dettagli del problema e i filtri delle eccezioni, vedere le sezioni della scheda Controller .

Risorse aggiuntive

  • Last updated on