Zpracování chyb ve webových rozhraních API založených na řadiči jádra ASP.NET

Tento článek popisuje, jak zpracovávat chyby a přizpůsobit zpracování chyb ve webových rozhraních API založených na řadiči ASP.NET Core. Informace o zpracování chyb v minimálních rozhraních API najdete v tématu Zpracování chyb v ASP.NET Core a Zpracování chyb v minimálních rozhraních API.

Stránka výjimky pro vývojáře

Na stránce výjimka pro vývojáře se zobrazují podrobné informace o neošetřených výjimkách požadavků. Používá DeveloperExceptionPageMiddleware se k zaznamenání synchronních a asynchronních výjimek z kanálu HTTP a k vygenerování chybových odpovědí. Stránka výjimky vývojáře se spouští v rané fázi kanálu middlewaru, aby bylo možné zachytit neošetřené výjimky vyvolané v middlewaru, které následuje.

ASP.NET aplikace Core ve výchozím nastavení povolí stránku výjimky pro vývojáře, pokud jsou obě:

• Běží ve vývojovém prostředí.
• Aplikace byla vytvořena s aktuálními šablonami, tj. pomocí .WebApplication.CreateBuilder

Aplikace vytvořené pomocí dřívějších šablon, tj. pomocí WebHost.CreateDefaultBuilder, mohou povolit stránku výjimky vývojáře voláním app.UseDeveloperExceptionPage.

Upozorňující

Nepovolujte stránku výjimek vývojáře, pokud aplikace není spuštěná ve vývojovém prostředí. Nesdílejte podrobné informace o výjimce veřejně, když aplikace běží v produkčním prostředí. Další informace o konfiguraci prostředí najdete v tématu Použití více prostředí v ASP.NET Core.

Stránka výjimky pro vývojáře může obsahovat následující informace o výjimce a požadavku:

• Trasování zásobníku
• Parametry řetězce dotazu, pokud nějaké
• Soubory cookie, pokud nějaké
• Hlavičky
• Metadata koncového bodu, pokud existuje

Na stránce výjimky pro vývojáře není zaručeno, že poskytnete žádné informace. Protokolování slouží k úplným informacím o chybě.

Následující obrázek ukazuje ukázkovou stránku výjimky vývojáře s animací, která zobrazuje karty a zobrazené informace:

V reakci na požadavek s hlavičkou Accept: text/plain vrátí stránka výjimky vývojáře místo HTML prostý text. Příklad:

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

Zobrazení stránky výjimky pro vývojáře:

• Do rozhraní API založeného na kontroleru přidejte následující akci kontroleru. Akce vyvolá výjimku při vyžádání koncového bodu.

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

• Spusťte aplikaci ve vývojovém prostředí.

• Přejděte na koncový bod definovaný akcí kontroleru.

Obslužná rutina výjimky

V prostředích, která nejsou vývojová, použijte middleware zpracování výjimek k vytvoření datové části chyby:

1. UseExceptionHandler Voláním Program.cspřidejte middleware zpracování výjimek:

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

2. Nakonfigurujte akci kontroleru, která bude reagovat na trasu /error :

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

Předchozí HandleError akce odešle klientovi datovou část kompatibilní s dokumentem RFC 7807.

Upozorňující

Neoznačí metodu akce obslužné rutiny chyby s atributy metody HTTP, například HttpGet. Explicitní příkazy brání některým požadavkům v dosažení metody akce.

U webových rozhraní API, která používají Swagger / OpenAPI, označte akci obslužné rutiny chyby atributem [ApiExplorerSettings] a nastavte jeho IgnoreApi vlastnost na true. Tato konfigurace atributu vylučuje akci obslužné rutiny chyby ze specifikace OpenAPI aplikace:

[ApiExplorerSettings(IgnoreApi = true)]

Povolte anonymní přístup k metodě, pokud by se měla zobrazit chyba neověřených uživatelů.

Middleware zpracování výjimek je možné použít také ve vývojovém prostředí k vytvoření konzistentního formátu datové části ve všech prostředích:

1. Zaregistrujte Program.csinstance middlewaru specifické pro prostředí:

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

   V předchozím kódu je middleware zaregistrovaný v:

   • /error-development Trasa ve vývojovém prostředí.
   • Trasa /error v prostředích, která nejsou vývojová.

2. Přidejte akce kontroleru pro trasy vývoje i pro jiné než vývojové trasy:

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

Úprava odpovědi pomocí výjimek

Obsah odpovědi lze upravit mimo kontroler pomocí vlastní výjimky a filtru akcí:

1. Vytvořte známý typ výjimky s názvem 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. Vytvořte filtr akcí s názvem 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;
           }
       }
   }
   

   Předchozí filtr určuje Order maximální celočíselnou hodnotu minus 10. To Order umožňuje spuštění dalších filtrů na konci kanálu.

3. Do Program.cskolekce filtrů přidejte filtr akcí:

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

Odpověď na chybu ověření

U řadičů webového rozhraní API MVC odpoví typem ValidationProblemDetails odpovědi, když se ověření modelu nezdaří. MVC používá výsledky InvalidModelStateResponseFactory k vytvoření chybové odpovědi pro selhání ověření. Následující příklad nahrazuje výchozí továrnu implementací, která také podporuje formátování odpovědí jako XML, v 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();

Odpověď na chybu klienta

Výsledek chyby je definován jako výsledek se stavovým kódem HTTP 400 nebo vyšší. U řadičů webového rozhraní API MVC transformuje výsledek chyby tak, aby vytvořil ProblemDetails.

Automatické vytvoření stavových ProblemDetails kódů chyb je ve výchozím nastavení povolené, ale odpovědi na chyby je možné nakonfigurovat jedním z následujících způsobů:

1. Použití služby podrobností o problému
2. Implementace ProblemDetailsFactory
3. Použití apiBehaviorOptions.ClientErrorMapping

Odpověď s výchozími podrobnostmi o problému

Program.cs Následující soubor vygenerovaly šablony webových aplikací pro kontrolery rozhraní API:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Vezměte v úvahu následující kontroler, který vrátí BadRequest , když je vstup neplatný:

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

Odpověď s podrobnostmi o problému se vygeneruje s předchozím kódem, pokud platí některá z následujících podmínek:

• Koncový /api/values2/divide bod se volá s nulovým jmenovatelem.
• Koncový /api/values2/squareroot bod se volá s paprsky menší než nula.

Výchozí text odpovědi s podrobnostmi o problému obsahuje následující typetitlehodnoty a status hodnoty:

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

Služba podrobností o problému

ASP.NET Core podporuje vytváření podrobností o problému pro rozhraní HTTP API pomocí rozhraní IProblemDetailsService. Další informace najdete ve službě Podrobnosti o problému.

Následující kód nakonfiguruje aplikaci tak, aby vygenerovala odpověď na podrobnosti o problému pro všechny odpovědi na chyby klienta HTTP a serveru, které ještě nemají základní obsah:

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

Vezměte v úvahu kontroler rozhraní API z předchozí části, který se vrátí BadRequest , když je vstup neplatný:

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

Odpověď s podrobnostmi o problému se vygeneruje s předchozím kódem, pokud platí některá z následujících podmínek:

• Je zadán neplatný vstup.
• Identifikátor URI nemá žádný odpovídající koncový bod.
• Dojde k neošetřené výjimce.

Automatické vytvoření ProblemDetails pro stavové kódy kódů chyb je zakázáno, pokud je vlastnost SuppressMapClientErrors nastavená na 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();

Při použití předchozího kódu se při návratu kontroleru rozhraní API vrátí BadRequeststav odpovědi HTTP 400 bez textu odpovědi. SuppressMapClientErrorsProblemDetails zabraňuje vytvoření odpovědi i při volání WriteAsync koncového bodu kontroleru rozhraní API. WriteAsync je vysvětleno dále v tomto článku.

V další části se dozvíte, jak přizpůsobit text odpovědi s podrobnostmi o problému pomocí příkazu CustomizeProblemDetails, aby se vrátila užitečnější odpověď. Další možnosti přizpůsobení najdete v tématu Přizpůsobení podrobností o problému.

Přizpůsobení podrobností o problému pomocí CustomizeProblemDetails

Následující kód používá ProblemDetailsOptions k nastavení 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();

Aktualizovaný kontroler rozhraní API:

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

}

Následující kód obsahuje MathErrorFeature kód, MathErrorTypekterý se používá s předchozím vzorem:

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

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

Odpověď s podrobnostmi o problému se vygeneruje s předchozím kódem, pokud platí některá z následujících podmínek:

• Koncový /divide bod se volá s nulovým jmenovatelem.
• Koncový /squareroot bod se volá s paprsky menší než nula.
• Identifikátor URI nemá žádný odpovídající koncový bod.

Text odpovědi s podrobnostmi o problému obsahuje následující informace, pokud je volán některý squareroot koncový bod s radikandou menší než nula:

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

Zobrazení nebo stažení ukázkového kódu

Implementovat ProblemDetailsFactory

MVC používá Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory k vytvoření všech instancí ProblemDetails a ValidationProblemDetails. Tato továrna se používá pro:

• Odpovědi na chyby klienta
• Odpovědi na chyby selhání ověřování
• ControllerBase.Problem a ControllerBase.ValidationProblem

Pokud chcete přizpůsobit odpověď na podrobnosti problému, zaregistrujte vlastní implementaci ProblemDetailsFactory v Program.cs:

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

Použití ApiBehaviorOptions.ClientErrorMapping

ClientErrorMapping Pomocí vlastnosti můžete nakonfigurovat obsah ProblemDetails odpovědi. Například následující kód v Program.cs aktualizaci Link vlastnosti pro odpovědi 404:

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

Další materiály

• Použití ověřování ModelState ve webovém rozhraní API ASP.NET Core
• Zobrazení nebo stažení ukázkového kódu
• Hellang.Middleware.ProblemDetails