Gestire gli errori nelle API di ASP.NET Core

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

Questo articolo descrive come gestire gli errori nelle API di ASP.NET Core. La documentazione per le API basate su controller è stata selezionata. Per visualizzare la documentazione per Minimal APIs, selezionare la scheda Minimal APIs. Per indicazioni sulla gestione degli errori di Blazor, vedere Gestire gli errori nelle app ASP.NET Core Blazor.

Per visualizzare la pagina Delle eccezioni per sviluppatori in un'API minima:

• Eseguire l'applicazione di esempio nell'ambienteDevelopment.
• Passare all'endpoint /exception .

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

Per visualizzare la pagina delle eccezioni dello sviluppatore in un'API basata su controller:

• Aggiungere la seguente azione del controller a un'API basata su controller. L'azione genera un'eccezione quando viene richiesto l'endpoint.

  [HttpGet("Throw")]
  public IActionResult Throw() =>
      throw new Exception("Sample exception.");
  

• Eseguire l'app nell'ambiente di sviluppo.

• Passare all'endpoint definito dall'azione del controller.

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

1. In Program.cschiamare UseExceptionHandler per aggiungere il middleware di gestione delle eccezioni:

   var app = builder.Build();
   
   app.UseHttpsRedirection();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error");
   }
   
   app.UseAuthorization();
   
   app.MapControllers();
   
   app.Run();
   

2. Configurare un'azione del controller per rispondere alla /error route:

   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

L'azione precedente HandleError invia un payload conforme a RFC 7807 al client.

[ApiExplorerSettings(IgnoreApi = true)]

Si consideri la seguente app per API minimale.

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 restituisce 200 OK con una rappresentazione json di User quando id è maggiore di 0, altrimenti un codice di stato 400 BAD REQUEST senza 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 predefinito comune, quando è vuoto, per tutte le risposte del client HTTP (400-499) o del 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);

Per le API basate su controller, la risposta di errore può essere configurata in uno dei modi seguenti:

1. Usare il servizio dettagli del problema
2. Implementare ProblemDetailsFactory
3. Usa ApiBehaviorOptions.ClientErrorMapping

Un risultato di errore viene definito come risultato con un codice di stato HTTP pari a 400 o superiore. Per i controller API Web, MVC trasforma un risultato di errore per produrre un oggetto ProblemDetails.

La creazione automatica di un ProblemDetails per i codici di stato di errore è abilitata per impostazione predefinita.

Le app Minimal API possono essere configurate per generare una risposta con i dettagli del problema per tutte le risposte di errore HTTP del client e del server che non contengono ancora un corpo tramite il metodo di estensione AddProblemDetails.

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 ulteriori informazioni sull'uso di AddProblemDetails, 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 problemDetailsService non è in grado di scrivere un ProblemDetails. Ad esempio, un endpoint in cui l'intestazione della richiesta Accept specifica un tipo di contenuto multimediale che DefaultProblemDetailsWriter non supporta.
• Usa il middleware di gestione delle eccezioni.

L'esempio seguente è simile al precedente, tranne per il fatto che chiama il 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);

Servizio dettagli problema

ASP.NET Core supporta la creazione di Dettagli del Problema per le API HTTP utilizzando il IProblemDetailsService.

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:

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

Si consideri il controller API della sezione precedente, che restituisce BadRequest quando l'input non è valido:

[Route("api/[controller]/[action]")]
[ApiController]
public class Values2Controller : ControllerBase
{
    // /api/values2/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values2 /squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            return BadRequest();
        }

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

Quando si applica una delle condizioni seguenti, viene generata una risposta ai dettagli del problema con il codice precedente:

• Viene fornito un input non valido.
• L'URI non ha alcun endpoint corrispondente.
• Si verifica un'eccezione non gestita.

Personalizzare i dettagli del problema con CustomizeProblemDetails

Il codice seguente usa ProblemDetailsOptions per impostare CustomizeProblemDetails:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddProblemDetails(options =>
        options.CustomizeProblemDetails = (context) =>
        {

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

                context.ProblemDetails.Type = details.Type;
                context.ProblemDetails.Title = "Bad Input";
                context.ProblemDetails.Detail = details.Detail;
            }
        }
    );

var app = builder.Build();

app.UseHttpsRedirection();

app.UseStatusCodePages();

app.UseAuthorization();

app.MapControllers();

app.Run();

Implementare ProblemDetailsFactory

MVC usa Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory per produrre tutte le istanze di ProblemDetails e ValidationProblemDetails. Questa fabbrica viene usata per:

• Risposte di errore client
• Risposte di errore per mancata convalida
• ControllerBase.Problem e ControllerBase.ValidationProblem

Per personalizzare la risposta ai dettagli del problema, registrare un'implementazione personalizzata di ProblemDetailsFactory in Program.cs:

builder.Services.AddControllers();
builder.Services.AddTransient<ProblemDetailsFactory, SampleProblemDetailsFactory>();

Utilizzare ApiBehaviorOptions.ClientErrorMapping.

Utilizzare la ClientErrorMapping proprietà per configurare il contenuto della ProblemDetails risposta. Ad esempio, il codice seguente in Program.cs aggiorna la Link proprietà per le risposte 404:

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

Migrazione da Controller a API minime

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

1. Sostituire i filtri di azione con filtri di 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 .

Risposta all'errore di convalida

Per i controller API Web, MVC risponde con un ValidationProblemDetails tipo di risposta quando la convalida del modello ha esito negativo. MVC usa i risultati di InvalidModelStateResponseFactory per costruire la risposta di errore per una convalida non riuscita. Nell'esempio seguente la factory predefinita viene sostituita con un'implementazione che supporta anche la formattazione delle risposte come XML, in Program.cs:

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.InvalidModelStateResponseFactory = context =>
            new BadRequestObjectResult(context.ModelState)
            {
                ContentTypes =
                {
                    // using static System.Net.Mime.MediaTypeNames;
                    Application.Json,
                    Application.Xml
                }
            };
    })
    .AddXmlSerializerFormatters();

Usare le eccezioni per modificare la risposta

Il contenuto della risposta può essere modificato dall'esterno del controller usando un'eccezione personalizzata e un filtro azione:

1. Creare un tipo di eccezione noto denominato HttpResponseException:

   public class HttpResponseException : Exception
   {
       public HttpResponseException(int statusCode, object? value = null) =>
           (StatusCode, Value) = (statusCode, value);
   
       public int StatusCode { get; }
   
       public object? Value { get; }
   }
   

2. Creare un filtro di azione denominato HttpResponseExceptionFilter:

   public class HttpResponseExceptionFilter : IActionFilter, IOrderedFilter
   {
       public int Order => int.MaxValue - 10;
   
       public void OnActionExecuting(ActionExecutingContext context) { }
   
       public void OnActionExecuted(ActionExecutedContext context)
       {
           if (context.Exception is HttpResponseException httpResponseException)
           {
               context.Result = new ObjectResult(httpResponseException.Value)
               {
                   StatusCode = httpResponseException.StatusCode
               };
   
               context.ExceptionHandled = true;
           }
       }
   }
   

   Il filtro precedente specifica un Order valore intero massimo meno 10. Questo Order consente ad altri filtri di essere eseguiti alla fine della pipeline.

3. In Program.csaggiungere il filtro azione alla raccolta di filtri:

   builder.Services.AddControllers(options =>
   {
       options.Filters.Add<HttpResponseExceptionFilter>();
   });
   

Differenze principali per i controller

• Convalida automatica del modello: i controller convalidano automaticamente lo stato del modello e restituiscono 400 Bad Request risposte per gli errori di convalida
• Filtri eccezioni: usare filtri azione e filtri eccezioni per la gestione centralizzata degli errori
• Dettagli del problema predefinito: configurare ApiBehaviorOptions per le risposte agli errori standardizzate
• Risposte di errore personalizzate: Sostituisci InvalidModelStateResponseFactory per personalizzare la formattazione degli errori di convalida