Gestire gli errori in ASP.NET Core

Tom Dykstra

Questo articolo illustra gli approcci comuni alla gestione degli errori nelle app Web di ASP.NET Core. Vedere anche Gestire gli errori nelle API Web basate su controller di base ASP.NET e Gestire gli errori nelle API minime.

Per Blazor indicazioni sulla gestione degli errori, che aggiunge o sostituisce le indicazioni contenute in questo articolo, vedere Gestire gli errori nelle app ASP.NET CoreBlazor.

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

Pagina del gestore di eccezioni

Per configurare una pagina di gestione degli errori personalizzata per l'ambiente di produzione, chiamare UseExceptionHandler. Questo middleware per la gestione delle eccezioni:

• Rileva e registra eccezioni non gestite.
• Esegue nuovamente la richiesta in una pipeline alternativa usando il percorso indicato. La richiesta non viene eseguita nuovamente se la risposta è stata avviata. Il codice generato dal modello esegue nuovamente la richiesta usando il /Error percorso.

Avviso

Se la pipeline alternativa genera un'eccezione propria, il middleware di gestione delle eccezioni genera nuovamente l'eccezione originale.

Poiché questo middleware può eseguire nuovamente la pipeline di richiesta:

• I middleware devono gestire la reentrancy con la stessa richiesta. Questo significa in genere pulire il proprio stato dopo aver chiamato _next o memorizzare nella cache l'elaborazione HttpContext su per evitare di ripeterlo. Quando si usa il corpo della richiesta, ciò significa memorizzare nel buffer o memorizzare nella cache i risultati, ad esempio il lettore di moduli.
• Per l'overload UseExceptionHandler(IApplicationBuilder, String) usato nei modelli, viene modificato solo il percorso della richiesta e i dati della route vengono cancellati. I dati delle richieste, ad esempio intestazioni, metodo ed elementi, vengono riutilizzati così come sono.
• I servizi con ambito rimangono invariati.

Nell'esempio seguente viene UseExceptionHandler aggiunto il middleware di gestione delle eccezioni in ambienti non di sviluppo:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

Il Razor modello di app Pages fornisce una pagina Di errore () e PageModel una classe (.cshtmlErrorModel) nella cartella Pages. Per un'app MVC, il modello di progetto include un Error metodo di azione e una visualizzazione Errore per il Home controller.

Il middleware di gestione delle eccezioni esegue nuovamente la richiesta usando il metodo HTTP originale . Se un endpoint del gestore errori è limitato a un set specifico di metodi HTTP, viene eseguito solo per tali metodi HTTP. Ad esempio, un'azione del controller MVC che usa l'attributo [HttpGet] viene eseguita solo per le richieste GET. Per assicurarsi che tutte le richieste raggiungano la pagina di gestione degli errori personalizzata, non limitarle a un set specifico di metodi HTTP.

Per gestire le eccezioni in modo diverso in base al metodo HTTP originale:

• Per Razor Pages creare più metodi del gestore. Ad esempio, usare OnGet per gestire le eccezioni GET e usare OnPost per gestire le eccezioni POST.
• Per MVC, applicare attributi verbi HTTP a più azioni. Ad esempio, usare [HttpGet] per gestire le eccezioni GET e usare [HttpPost] per gestire le eccezioni POST.

Per consentire agli utenti non autenticati di visualizzare la pagina di gestione degli errori personalizzata, assicurarsi che supporti l'accesso anonimo.

Accedere all'eccezione

Usare IExceptionHandlerPathFeature per accedere all'eccezione e al percorso della richiesta originale in un gestore errori. Nell'esempio seguente viene IExceptionHandlerPathFeature usato per ottenere altre informazioni sull'eccezione generata:

[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
[IgnoreAntiforgeryToken]
public class ErrorModel : PageModel
{
    public string? RequestId { get; set; }

    public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);

    public string? ExceptionMessage { get; set; }

    public void OnGet()
    {
        RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;

        var exceptionHandlerPathFeature =
            HttpContext.Features.Get<IExceptionHandlerPathFeature>();

        if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
        {
            ExceptionMessage = "The file was not found.";
        }

        if (exceptionHandlerPathFeature?.Path == "/")
        {
            ExceptionMessage ??= string.Empty;
            ExceptionMessage += " Page: Home.";
        }
    }
}

Avviso

Non fornire informazioni sugli errori sensibili ai client. Fornire informazioni sugli errori rappresenta un rischio di sicurezza.

Espressione lambda per il gestore di eccezioni

Un'alternativa a una pagina di gestione delle eccezioni personalizzata consiste nel fornire un'espressione lambda a UseExceptionHandler. L'uso di un'espressione lambda consente l'accesso all'errore prima di restituire la risposta.

Il codice seguente usa un'espressione lambda per la gestione delle eccezioni:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler(exceptionHandlerApp =>
    {
        exceptionHandlerApp.Run(async context =>
        {
            context.Response.StatusCode = StatusCodes.Status500InternalServerError;

            // using static System.Net.Mime.MediaTypeNames;
            context.Response.ContentType = Text.Plain;

            await context.Response.WriteAsync("An exception was thrown.");

            var exceptionHandlerPathFeature =
                context.Features.Get<IExceptionHandlerPathFeature>();

            if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
            {
                await context.Response.WriteAsync(" The file was not found.");
            }

            if (exceptionHandlerPathFeature?.Path == "/")
            {
                await context.Response.WriteAsync(" Page: Home.");
            }
        });
    });

    app.UseHsts();
}

Un altro modo per usare un'espressione lambda consiste nell'impostare il codice di stato in base al tipo di eccezione, come nell'esempio seguente:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
    app.UseExceptionHandler(new ExceptionHandlerOptions
    {
        StatusCodeSelector = ex => ex is TimeoutException
            ? StatusCodes.Status503ServiceUnavailable
            : StatusCodes.Status500InternalServerError
    });
}

Avviso

Non fornire informazioni sugli errori sensibili ai client. Fornire informazioni sugli errori rappresenta un rischio di sicurezza.

IExceptionHandler

IExceptionHandler è un'interfaccia che offre allo sviluppatore un callback per la gestione delle eccezioni note in una posizione centrale.

IExceptionHandler le implementazioni vengono registrate chiamando IServiceCollection.AddExceptionHandler<T>. La durata di un'istanza IExceptionHandler è singleton. È possibile aggiungere più implementazioni e vengono chiamate nell'ordine registrato.

Se un gestore eccezioni gestisce una richiesta, può tornare true a interrompere l'elaborazione. Se un'eccezione non viene gestita da alcun gestore eccezioni, il controllo esegue il fallback al comportamento predefinito e alle opzioni del middleware. Metriche e log diversi vengono generati per le eccezioni gestite e non gestite.

L'esempio seguente illustra un'implementazione IExceptionHandler :

using Microsoft.AspNetCore.Diagnostics;

namespace ErrorHandlingSample
{
    public class CustomExceptionHandler : IExceptionHandler
    {
        private readonly ILogger<CustomExceptionHandler> logger;
        public CustomExceptionHandler(ILogger<CustomExceptionHandler> logger)
        {
            this.logger = logger;
        }
        public ValueTask<bool> TryHandleAsync(
            HttpContext httpContext,
            Exception exception,
            CancellationToken cancellationToken)
        {
            var exceptionMessage = exception.Message;
            logger.LogError(
                "Error Message: {exceptionMessage}, Time of occurrence {time}",
                exceptionMessage, DateTime.UtcNow);
            // Return false to continue with the default behavior
            // - or - return true to signal that this exception is handled
            return ValueTask.FromResult(false);
        }
    }
}

L'esempio seguente illustra come registrare un'implementazione IExceptionHandler per l'inserimento delle dipendenze:

using ErrorHandlingSample;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDatabaseDeveloperPageExceptionFilter();
builder.Services.AddRazorPages();
builder.Services.AddExceptionHandler<CustomExceptionHandler>();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Remaining Program.cs code omitted for brevity

Quando il codice precedente viene eseguito nell'ambiente di sviluppo:

• Viene CustomExceptionHandler chiamato prima di tutto per gestire un'eccezione.
• Dopo la registrazione dell'eccezione, il TryHandleAsync metodo restituisce false, in modo che venga visualizzata la pagina delle eccezioni per gli sviluppatori.

In altri ambienti:

• Viene CustomExceptionHandler chiamato prima di tutto per gestire un'eccezione.
• Dopo la registrazione dell'eccezione, il TryHandleAsync metodo restituisce false, in modo che venga visualizzata la /Error pagina .

UseStatusCodePages

Per impostazione predefinita, un'app ASP.NET Core non fornisce una tabella codici di stato per i codici di stato degli errori HTTP, ad esempio 404 - Non trovato. Quando l'app imposta un codice di stato di errore HTTP 400-599 che non ha un corpo, restituisce il codice di stato e un corpo della risposta vuoto. Per abilitare i gestori predefiniti solo testo per i codici di stato di errore comuni, chiamare UseStatusCodePages in Program.cs:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePages();

Chiamare UseStatusCodePages prima del middleware di gestione delle richieste. Ad esempio, chiamare UseStatusCodePages prima del middleware dei file statici e del middleware degli endpoint.

Quando UseStatusCodePages non viene usato, passare a un URL senza un endpoint restituisce un messaggio di errore dipendente dal browser che indica che l'endpoint non è stato trovato. Quando UseStatusCodePages viene chiamato, il browser restituisce la risposta seguente:

Status Code: 404; Not Found

UseStatusCodePages non viene in genere usato nell'ambiente di produzione perché restituisce un messaggio che non è utile per gli utenti.

Nota

Il middleware delle tabelle codici di stato non intercetta le eccezioni. Per fornire una pagina di gestione degli errori personalizzata, usare la pagina del gestore eccezioni.

UseStatusCodePages con stringa di formato

Per personalizzare il tipo di contenuto della risposta e il testo, usare l'overload di UseStatusCodePages che accetta un tipo di contenuto e una stringa di formato:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// using static System.Net.Mime.MediaTypeNames;
app.UseStatusCodePages(Text.Plain, "Status Code Page: {0}");

Nel codice {0} precedente è un segnaposto per il codice di errore.

UseStatusCodePages con una stringa di formato non viene in genere usata nell'ambiente di produzione perché restituisce un messaggio che non è utile agli utenti.

UseStatusCodePages con espressione lambda

Per specificare la gestione degli errori personalizzata e il codice per la scrittura delle risposte, usare l'overload di UseStatusCodePages che accetta un'espressione lambda:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePages(async statusCodeContext =>
{
    // using static System.Net.Mime.MediaTypeNames;
    statusCodeContext.HttpContext.Response.ContentType = Text.Plain;

    await statusCodeContext.HttpContext.Response.WriteAsync(
        $"Status Code Page: {statusCodeContext.HttpContext.Response.StatusCode}");
});

UseStatusCodePages con un'espressione lambda non viene in genere usato nell'ambiente di produzione perché restituisce un messaggio che non è utile agli utenti.

UseStatusCodePagesWithRedirects

Metodo di estensione UseStatusCodePagesWithRedirects:

• Invia un codice di stato 302 - Trovato al client.
• Reindirizza il client all'endpoint di gestione degli errori fornito nel modello di URL. L'endpoint di gestione degli errori visualizza in genere informazioni sugli errori e restituisce HTTP 200.

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePagesWithRedirects("/StatusCode/{0}");

Il modello di URL può includere un {0} segnaposto per il codice di stato, come illustrato nel codice precedente. Se il modello di URL inizia con ~ (tilde), viene ~ sostituito da PathBase. Quando si specifica un endpoint nell'app, creare una visualizzazione o Razor una pagina MVC per l'endpoint.

Questo metodo viene usato comunemente quando l'app:

• Deve reindirizzare il client a un endpoint diverso, in genere nei casi in cui un'altra app elabora l'errore. Per le app Web, la barra degli indirizzi del browser del client riflette l'endpoint reindirizzato.
• Non deve conservare e restituire il codice di stato originale con la risposta di reindirizzamento iniziale.

UseStatusCodePagesWithReExecute

Metodo di estensione UseStatusCodePagesWithReExecute:

• Genera il corpo della risposta eseguendo nuovamente la pipeline delle richieste con un percorso alternativo.
• Non modifica il codice di stato prima o dopo l'esecuzione di nuovo della pipeline.

La nuova esecuzione della pipeline può modificare il codice di stato della risposta, perché la nuova pipeline ha il controllo completo del codice di stato. Se la nuova pipeline non modifica il codice di stato, il codice di stato originale verrà inviato al client.

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePagesWithReExecute("/StatusCode/{0}");

Se viene specificato un endpoint all'interno dell'app, creare una visualizzazione o Razor una pagina MVC per l'endpoint.

Questo metodo viene usato comunemente quando l'app deve:

• Elaborare la richiesta senza il reindirizzamento a un endpoint diverso. Per le app Web, la barra degli indirizzi del browser del client riflette l'endpoint richiesto in origine.
• Conservare e restituire il codice di stato originale con la risposta.

Il modello di URL deve iniziare con / e può includere un segnaposto {0} per il codice di stato. Per passare il codice di stato come parametro di stringa di query, passare un secondo argomento in UseStatusCodePagesWithReExecute. Ad esempio:

var app = builder.Build();  
app.UseStatusCodePagesWithReExecute("/StatusCode", "?statusCode={0}");

L'endpoint che elabora l'errore può ottenere l'URL originale che ha generato l'errore, come illustrato nell'esempio seguente:

[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
public class StatusCodeModel : PageModel
{
    public int OriginalStatusCode { get; set; }

    public string? OriginalPathAndQuery { get; set; }

    public void OnGet(int statusCode)
    {
        OriginalStatusCode = statusCode;

        var statusCodeReExecuteFeature =
            HttpContext.Features.Get<IStatusCodeReExecuteFeature>();

        if (statusCodeReExecuteFeature is not null)
        {
            OriginalPathAndQuery = $"{statusCodeReExecuteFeature.OriginalPathBase}"
                                    + $"{statusCodeReExecuteFeature.OriginalPath}"
                                    + $"{statusCodeReExecuteFeature.OriginalQueryString}";

        }
    }
}

Poiché questo middleware può eseguire nuovamente la pipeline di richiesta:

• I middleware devono gestire la reentrancy con la stessa richiesta. Questo significa in genere pulire il proprio stato dopo aver chiamato _next o memorizzare nella cache l'elaborazione HttpContext su per evitare di ripeterlo. Quando si usa il corpo della richiesta, ciò significa memorizzare nel buffer o memorizzare nella cache i risultati, ad esempio il lettore di moduli.
• I servizi con ambito rimangono invariati.

Disabilitare le tabelle codici di stato

Per disabilitare le tabelle codici di stato per un controller MVC o un metodo di azione, usare l'attributo [SkipStatusCodePages].

Per disabilitare le tabelle codici di stato per richieste specifiche in un Razor metodo del gestore Pages o in un controller MVC, usare IStatusCodePagesFeature:

public void OnGet()
{
    var statusCodePagesFeature =
        HttpContext.Features.Get<IStatusCodePagesFeature>();

    if (statusCodePagesFeature is not null)
    {
        statusCodePagesFeature.Enabled = false;
    }
}

Codice di gestione delle eccezioni

Il codice nelle pagine di gestione delle eccezioni può anche generare eccezioni. Le pagine di errore di produzione devono essere testate accuratamente e prestare particolare attenzione per evitare di generare eccezioni proprie.

Intestazioni della risposta

Dopo l'invio delle intestazioni per una risposta:

• L'app non può modificare il codice di stato della risposta.
• Non è possibile eseguire pagine o gestori delle eccezioni. La risposta deve essere completata o la connessione deve essere interrotta.

Gestione delle eccezioni del server

Oltre alla logica di gestione delle eccezioni in un'app, l'implementazione del server HTTP può gestire alcune eccezioni. Se il server rileva un'eccezione prima dell'invio delle intestazioni di risposta, il server invia una 500 - Internal Server Error risposta senza un corpo della risposta. Se il server rileva un'eccezione dopo l'invio delle intestazioni di risposta, il server chiude la connessione. Le richieste non gestite dall'app vengono gestite dal server. Qualsiasi eccezione che si verifica quando il server sta gestendo la richiesta viene gestita dalla gestione delle eccezioni del server. Eventuali pagine di errore personalizzate dell'app, middleware di gestione delle eccezioni e filtri non hanno effetto su questo comportamento.

Gestione delle eccezioni durante l'avvio

Solo il livello di hosting può gestire le eccezioni che si verificano durante l'avvio dell'app. L'host può essere configurato per acquisire gli errori di avvio e acquisire errori dettagliati.

Il livello di hosting può visualizzare una pagina di errore per un errore di avvio acquisito solo se l'errore si verifica dopo l'associazione indirizzo host/porta. Se si verifica un errore di associazione:

• Il livello di hosting registra un'eccezione critica.
• Si verifica un arresto anomalo del processo di dotnet.
• Non viene visualizzata alcuna pagina di errore quando il server HTTP è Kestrel.

Se durante l'esecuzione in IIS (o servizio app di Azure) o in IIS Express il processo non può essere avviato, viene restituito l'errore 502.5 Errore del processo dal modulo ASP.NET Core. Per altre informazioni, vedere Risolvere i problemi relativi a ASP.NET Core nel servizio app Azure e IIS.

Pagina di errore di database

Il filtro AddDatabaseDeveloperPageExceptionFilter eccezioni della pagina Sviluppo database acquisisce le eccezioni correlate al database che possono essere risolte usando le migrazioni di Entity Framework Core. Quando si verificano queste eccezioni, viene generata una risposta HTML con i dettagli delle possibili azioni per risolvere il problema. Questa pagina è abilitata solo nell'ambiente di sviluppo. Il codice seguente aggiunge il filtro eccezioni della pagina Sviluppo database:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDatabaseDeveloperPageExceptionFilter();
builder.Services.AddRazorPages();

Filtri eccezioni

Nelle app MVC i filtri delle eccezioni possono essere configurati a livello globale o per ogni controller o azione singolarmente. Nelle Razor app Pages possono essere configurate a livello globale o per modello di pagina. Questi filtri gestiscono eventuali eccezioni non gestite che si verificano durante l'esecuzione di un'azione del controller o di un altro filtro. Per altre informazioni, vedere Filtri in ASP.NET Core.

I filtri eccezioni sono utili per intercettare le eccezioni che si verificano all'interno di azioni MVC, ma non sono flessibili come il middleware di gestione delle eccezioni predefinito, UseExceptionHandler. È consigliabile usare UseExceptionHandler, a meno che non sia necessario eseguire la gestione degli errori in modo diverso in base all'azione MVC scelta.

Errori di stato del modello

Per informazioni su come gestire gli errori dello stato del modello, vedere Associazione di modelli e Convalida del modello.

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.

Il codice seguente configura l'app per generare una risposta ai dettagli del problema per tutte le risposte di errore del client HTTP e del server che non hanno ancora contenuto del corpo:

builder.Services.AddProblemDetails();

var app = builder.Build();        

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler();
    app.UseHsts();
}

app.UseStatusCodePages();

Nella sezione successiva viene illustrato come personalizzare il corpo della risposta ai dettagli del problema.

Personalizzare i dettagli del problema

La creazione automatica di un ProblemDetails oggetto può essere personalizzata usando una delle opzioni seguenti:

1. Utilizzare ProblemDetailsOptions.CustomizeProblemDetails.
2. Usare un oggetto personalizzato IProblemDetailsWriter
3. Chiamare in IProblemDetailsService un middleware

CustomizeProblemDetails operazione

I dettagli del problema generati possono essere personalizzati usando CustomizeProblemDetailse le personalizzazioni vengono applicate a tutti i dettagli del problema generati automaticamente.

Il codice seguente usa ProblemDetailsOptions per impostare CustomizeProblemDetails:

builder.Services.AddProblemDetails(options =>
    options.CustomizeProblemDetails = ctx =>
            ctx.ProblemDetails.Extensions.Add("nodeId", Environment.MachineName));

var app = builder.Build();        

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler();
    app.UseHsts();
}

app.UseStatusCodePages();

Ad esempio, un HTTP Status 400 Bad Request risultato dell'endpoint produce il corpo della risposta ai dettagli del problema seguente:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "nodeId": "my-machine-name"
}

IProblemDetailsWriter personalizzato

È possibile creare un'implementazione IProblemDetailsWriter per le personalizzazioni avanzate.

public class SampleProblemDetailsWriter : IProblemDetailsWriter
{
    // Indicates that only responses with StatusCode == 400
    // are handled by this writer. All others are
    // handled by different registered writers if available.
    public bool CanWrite(ProblemDetailsContext context)
        => context.HttpContext.Response.StatusCode == 400;

    public ValueTask WriteAsync(ProblemDetailsContext context)
    {
        // Additional customizations.

        // Write to the response.
        var response = context.HttpContext.Response;
        return new ValueTask(response.WriteAsJsonAsync(context.ProblemDetails));
    }
}

Nota: quando si usa un oggetto personalizzato IProblemDetailsWriter, l'oggetto personalizzato IProblemDetailsWriter deve essere registrato prima di chiamare AddRazorPages, AddControllersAddControllersWithViews, o AddMvc:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTransient<IProblemDetailsWriter, SampleProblemDetailsWriter>();

var app = builder.Build();

// Middleware to handle writing problem details to the response.
app.Use(async (context, next) =>
{
    await next(context);
    var mathErrorFeature = context.Features.Get<MathErrorFeature>();
    if (mathErrorFeature is not null)
    {
        if (context.RequestServices.GetService<IProblemDetailsWriter>() is
            { } problemDetailsService)
        {

            if (problemDetailsService.CanWrite(new ProblemDetailsContext() { HttpContext = context }))
            {
                (string Detail, string Type) details = mathErrorFeature.MathError switch
                {
                    MathErrorType.DivisionByZeroError => ("Divison by zero is not defined.",
                        "https://en.wikipedia.org/wiki/Division_by_zero"),
                    _ => ("Negative or complex numbers are not valid input.",
                        "https://en.wikipedia.org/wiki/Square_root")
                };

                await problemDetailsService.WriteAsync(new ProblemDetailsContext
                {
                    HttpContext = context,
                    ProblemDetails =
                    {
                        Title = "Bad Input",
                        Detail = details.Detail,
                        Type = details.Type
                    }
                });
            }
        }
    }
});

// /divide?numerator=2&denominator=4
app.MapGet("/divide", (HttpContext context, double numerator, double denominator) =>
{
    if (denominator == 0)
    {
        var errorType = new MathErrorFeature
        {
            MathError = MathErrorType.DivisionByZeroError
        };
        context.Features.Set(errorType);
        return Results.BadRequest();
    }

    return Results.Ok(numerator / denominator);
});

// /squareroot?radicand=16
app.MapGet("/squareroot", (HttpContext context, double radicand) =>
{
    if (radicand < 0)
    {
        var errorType = new MathErrorFeature
        {
            MathError = MathErrorType.NegativeRadicandError
        };
        context.Features.Set(errorType);
        return Results.BadRequest();
    }

    return Results.Ok(Math.Sqrt(radicand));
});

app.Run();

Dettagli del problema dal middleware

Un approccio alternativo all'uso ProblemDetailsOptions con CustomizeProblemDetails consiste nell'impostare il ProblemDetails middleware. Una risposta ai dettagli del problema può essere scritta chiamando IProblemDetailsService.WriteAsync:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseStatusCodePages();

// Middleware to handle writing problem details to the response.
app.Use(async (context, next) =>
{
    await next(context);
    var mathErrorFeature = context.Features.Get<MathErrorFeature>();
    if (mathErrorFeature is not null)
    {
        if (context.RequestServices.GetService<IProblemDetailsService>() is
                                                           { } problemDetailsService)
        {
            (string Detail, string Type) details = mathErrorFeature.MathError switch
            {
                MathErrorType.DivisionByZeroError => ("Divison by zero is not defined.",
                "https://en.wikipedia.org/wiki/Division_by_zero"),
                _ => ("Negative or complex numbers are not valid input.", 
                "https://en.wikipedia.org/wiki/Square_root")
            };

            await problemDetailsService.WriteAsync(new ProblemDetailsContext
            {
                HttpContext = context,
                ProblemDetails =
                {
                    Title = "Bad Input",
                    Detail = details.Detail,
                    Type = details.Type
                }
            });
        }
    }
});

// /divide?numerator=2&denominator=4
app.MapGet("/divide", (HttpContext context, double numerator, double denominator) =>
{
    if (denominator == 0)
    {
        var errorType = new MathErrorFeature { MathError =
                                               MathErrorType.DivisionByZeroError };
        context.Features.Set(errorType);
        return Results.BadRequest();
    }

    return Results.Ok(numerator / denominator);
});

// /squareroot?radicand=16
app.MapGet("/squareroot", (HttpContext context, double radicand) =>
{
    if (radicand < 0)
    {
        var errorType = new MathErrorFeature { MathError =
                                               MathErrorType.NegativeRadicandError };
        context.Features.Set(errorType);
        return Results.BadRequest();
    }

    return Results.Ok(Math.Sqrt(radicand));
});

app.MapControllers();

app.Run();

Nel codice precedente, gli endpoint /divide API minimi e /squareroot restituiscono la risposta del problema personalizzata prevista all'input dell'errore.

Gli endpoint del controller API restituiscono la risposta del problema predefinita all'input dell'errore, non la risposta personalizzata al problema. Viene restituita la risposta del problema predefinita perché il controller API ha scritto nel flusso di risposta, Dettagli del problema per i codici di stato degli errori, prima IProblemDetailsService.WriteAsync di chiamare e la risposta non viene scritta di nuovo.

Di seguito ValuesController viene restituito BadRequestResult, che scrive nel flusso di risposta e pertanto impedisce la restituzione della risposta personalizzata al problema.

[Route("api/[controller]/[action]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // /api/values/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.DivisionByZeroError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values/squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.NegativeRadicandError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }

}

Di seguito Values3Controller viene restituito ControllerBase.Problem il risultato del problema personalizzato previsto:

[Route("api/[controller]/[action]")]
[ApiController]
public class Values3Controller : ControllerBase
{
    // /api/values3/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.DivisionByZeroError
            };
            HttpContext.Features.Set(errorType);
            return Problem(
                title: "Bad Input",
                detail: "Divison by zero is not defined.",
                type: "https://en.wikipedia.org/wiki/Division_by_zero",
                statusCode: StatusCodes.Status400BadRequest
                );
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values3/squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.NegativeRadicandError
            };
            HttpContext.Features.Set(errorType);
            return Problem(
                title: "Bad Input",
                detail: "Negative or complex numbers are not valid input.",
                type: "https://en.wikipedia.org/wiki/Square_root",
                statusCode: StatusCodes.Status400BadRequest
                );
        }

        return Ok(Math.Sqrt(radicand));
    }

}

Generare un payload ProblemDetails per le eccezioni

Si consideri l'app seguente:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddProblemDetails();

var app = builder.Build();

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

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.MapControllers();
app.Run();

In ambienti non di sviluppo, quando si verifica un'eccezione, di seguito è riportata una risposta Standard ProblemDetails restituita al client:

{
"type":"https://tools.ietf.org/html/rfc7231#section-6.6.1",
"title":"An error occurred while processing your request.",
"status":500,"traceId":"00-b644<snip>-00"
}

Per la maggior parte delle app, il codice precedente è tutto ciò che è necessario per le eccezioni. Tuttavia, la sezione seguente illustra come ottenere risposte più dettagliate ai problemi.

Un'alternativa a una pagina di gestione delle eccezioni personalizzata consiste nel fornire un'espressione lambda a UseExceptionHandler. L'uso di un'espressione lambda consente l'accesso all'errore e la scrittura di una risposta ai dettagli del problema con IProblemDetailsService.WriteAsync:

using Microsoft.AspNetCore.Diagnostics;
using static System.Net.Mime.MediaTypeNames;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddProblemDetails();

var app = builder.Build();

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

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler(exceptionHandlerApp =>
    {
        exceptionHandlerApp.Run(async context =>
        {
            context.Response.StatusCode = StatusCodes.Status500InternalServerError;
            context.Response.ContentType = Text.Plain;

            var title = "Bad Input";
            var detail = "Invalid input";
            var type = "https://errors.example.com/badInput";

            if (context.RequestServices.GetService<IProblemDetailsService>() is
                { } problemDetailsService)
            {
                var exceptionHandlerFeature =
               context.Features.Get<IExceptionHandlerFeature>();

                var exceptionType = exceptionHandlerFeature?.Error;
                if (exceptionType != null &&
                   exceptionType.Message.Contains("infinity"))
                {
                    title = "Argument exception";
                    detail = "Invalid input";
                    type = "https://errors.example.com/argumentException";
                }

                await problemDetailsService.WriteAsync(new ProblemDetailsContext
                {
                    HttpContext = context,
                    ProblemDetails =
                {
                    Title = title,
                    Detail = detail,
                    Type = type
                }
                });
            }
        });
    });
}

app.MapControllers();
app.Run();

Avviso

Non fornire informazioni sugli errori sensibili ai client. Fornire informazioni sugli errori rappresenta un rischio di sicurezza.

Un approccio alternativo alla generazione dei dettagli del problema consiste nell'usare il pacchetto NuGet di terze parti Hellang.Middleware.ProblemDetails che può essere usato per eseguire il mapping delle eccezioni e degli errori del client ai dettagli del problema.

Risorse aggiuntive

• Visualizzare o scaricare il codice di esempio (procedura per il download)
• Risolvere i problemi di ASP.NET Core in Servizio app di Azure e IIS
• Risoluzione di errori comuni di Servizio app di Azure e IIS con ASP.NET Core
• Gestire gli errori nelle API Web basate su controller di base ASP.NET
• Gestire gli errori nelle API minime.