Gestire gli errori nelle API Web basate su controller di base ASP.NET

Questo articolo descrive come gestire gli errori e personalizzare la gestione degli errori nelle API Web di base ASP.NET controller. Per informazioni sulla gestione degli errori nelle API minime, vedere Gestire gli errori in ASP.NET Core e Gestire gli errori nelle API minime.

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:

• Aggiungere l'azione controller seguente 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.

Gestore di eccezioni

Negli ambienti non di sviluppo usare il middleware di gestione delle eccezioni per produrre un payload di errore:

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.

Avviso

Non contrassegnare il metodo di azione del gestore degli errori con attributi del metodo HTTP, ad esempio HttpGet. I verbi espliciti impediscono ad alcune richieste di raggiungere il metodo di azione.

Per le API Web che usano Swagger/OpenAPI, contrassegnare l'azione del gestore degli errori con l'attributo [ApiExplorerSettings] e impostarne la IgnoreApi proprietà su true. Questa configurazione dell'attributo esclude l'azione del gestore errori dalla specifica OpenAPI dell'app:

[ApiExplorerSettings(IgnoreApi = true)]

Consentire l'accesso anonimo al metodo se gli utenti non autenticati dovrebbero visualizzare l'errore.

Il middleware di gestione delle eccezioni può essere usato anche nell'ambiente di sviluppo per produrre un formato di payload coerente in tutti gli ambienti:

1. In Program.csregistrare istanze middleware di gestione delle eccezioni specifiche dell'ambiente:

   if (app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error-development");
   }
   else
   {
       app.UseExceptionHandler("/error");
   }
   

   Nel codice precedente il middleware viene registrato con:

   • Route di nell'ambiente di /error-development sviluppo.
   • Route di /error in ambienti non di sviluppo.

2. Aggiungere azioni del controller per le route sviluppo e non di sviluppo:

   [Route("/error-development")]
   public IActionResult HandleErrorDevelopment(
       [FromServices] IHostEnvironment hostEnvironment)
   {
       if (!hostEnvironment.IsDevelopment())
       {
           return NotFound();
       }
   
       var exceptionHandlerFeature =
           HttpContext.Features.Get<IExceptionHandlerFeature>()!;
   
       return Problem(
           detail: exceptionHandlerFeature.Error.StackTrace,
           title: exceptionHandlerFeature.Error.Message);
   }
   
   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

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. Ciò Order consente l'esecuzione di altri filtri alla fine della pipeline.

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

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

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 per costruire la risposta di InvalidModelStateResponseFactory errore per un errore di convalida. 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();

Risposta di errore del client

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 per ProblemDetails i codici di stato degli errori è abilitata per impostazione predefinita, ma le risposte agli errori possono essere configurate in uno dei modi seguenti:

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

Risposta dei dettagli del problema predefinita

Il file seguente Program.cs è stato generato dai modelli di applicazione Web per i controller API:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Si consideri il controller seguente, 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:

• L'endpoint /api/values2/divide viene chiamato con un denominatore zero.
• L'endpoint /api/values2/squareroot viene chiamato con una radice e minore di zero.

Il corpo della risposta dei dettagli del problema predefinito include i valori , titlee status seguentitype:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}

Servizio dettagli problema

ASP.NET Core supporta la creazione di dettagli del problema per le API HTTP tramite .IProblemDetailsService Per altre informazioni, vedere il servizio Dettagli problema.

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.

La creazione automatica di ProblemDetails per i codici di stato di errore è disabilitata quando la proprietà SuppressMapClientErrors è impostata su true:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressMapClientErrors = true;
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Usando il codice precedente, quando un controller API restituisce BadRequest, viene restituito uno stato di risposta HTTP 400 senza corpo della risposta. SuppressMapClientErrors impedisce la creazione di una ProblemDetails risposta, anche quando si chiama WriteAsync un endpoint del controller API. WriteAsync viene spiegato più avanti in questo articolo.

La sezione successiva illustra come personalizzare il corpo della risposta ai dettagli del problema, usando CustomizeProblemDetails, per restituire una risposta più utile. Per altre opzioni di personalizzazione, vedere Personalizzazione dei dettagli del problema.

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

Controller API aggiornato:

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

}

Il codice seguente contiene e MathErrorFeature MathErrorType, che vengono usati con l'esempio precedente:

// Custom Http Request Feature
class MathErrorFeature
{
    public MathErrorType MathError { get; set; }
}

// Custom math errors
enum MathErrorType
{
    DivisionByZeroError,
    NegativeRadicandError
}

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

• L'endpoint /divide viene chiamato con un denominatore zero.
• L'endpoint /squareroot viene chiamato con una radice e minore di zero.
• L'URI non ha alcun endpoint corrispondente.

Il corpo della risposta ai dettagli del problema contiene quanto segue quando uno squareroot dei due endpoint viene chiamato con una radice e minore di zero:

{
  "type": "https://en.wikipedia.org/wiki/Square_root",
  "title": "Bad Input",
  "status": 400,
  "detail": "Negative or complex numbers are not allowed."
}

Visualizzare o scaricare codice di esempio

Implementare ProblemDetailsFactory

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

• Risposte di errore client
• Risposte di errore di 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.

Usare la proprietà ClientErrorMapping per configurare il contenuto della risposta ProblemDetails. 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";
    });

Risorse aggiuntive

• Come usare la convalida modelstate nell'API Web di base di ASP.NET
• Visualizzare o scaricare codice di esempio
• Hellang.Middleware.ProblemDetails