Zpracování chyb v rozhraních API ASP.NET Core

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi článku pro technologie .NET 10 najdete v .

Výstraha

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v technologie .NET a technologie .NET základních zásadách podpory. Aktuální verzi článku pro technologie .NET 10 najdete v .

Tento článek popisuje, jak zpracovávat chyby v rozhraních API ASP.NET Core. Je vybraná dokumentace k minimálním rozhraním API. Pokud chcete zobrazit dokumentaci k rozhraním API založeným na kontroleru, vyberte kartu Controllers. Pokyny ke zpracování chyb Blazor najdete v tématu Chyba chyb v ASP.NET Core Blazor aplikacích.

Tento článek popisuje, jak zpracovávat chyby v rozhraních API ASP.NET Core. Je vybrána dokumentace pro rozhraní API založená na kontroleru. Pokud chcete zobrazit dokumentaci pro Minimal API, vyberte kartu Minimal API. Pokyny ke zpracování chyb Blazor najdete v tématu Dalši chyby v aplikacích ASP.NET Core Blazor.

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á 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 pro vývojářské výjimky se spouští v rané fázi middleware kanálu, aby bylo možné zachytit neošetřené výjimky vyvolané v následujícím middleware.

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

• Běží v prostředí.
• Aplikace byla vytvořena s aktuálními šablonami, tj. pomocí .

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

Výstraha

Nepovolujte stránku výjimky vývojáře , pokud aplikace není spuštěná v 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 ASP.NET Core runtime prostředí.

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é
• Headers
• Metadata koncového bodu, pokud existuje

Na stránce výjimky pro vývojáře není zaručeno, že poskytne jakékoli informace. Použijte protokolování pro získání úplných informací o chybě.

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

Stránka výjimky vývojáře animována pro zobrazení vybrané karty.

V reakci na požadavek s hlavičkou vrátí stránka výjimky vývojáře místo HTML prostý text. Napří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

Pokud chcete zobrazit stránku výjimky vývojáře v minimálním rozhraní API:

• Spusťte ukázkovou aplikaci v prostředí.
• Přejděte na koncový bod.

Tato část odkazuje na následující ukázkovou aplikaci, která demonstruje způsoby zpracování výjimek v minimálním rozhraní API. Při vyžádání koncového bodu dojde k výjimce:

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

Zobrazení stránky výjimek pro vývojáře v rozhraní API založeném na kontroleru:

• Do rozhraní API založeného na kontroleru přidejte následující akci kontroleru. Akce vyvolá výjimku, když je požadován koncový bod.

  [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 pro zpracování výjimek k vytvoření chybového hlášení.

Chcete-li provést konfiguraci, zavolejte na metodu. Například následující kód změní aplikaci tak, aby odpovídala klientovi s datovou částí ve formátu kompatibilním s RFC 7807. Další informace najdete v části Podrobnosti o problému dále v tomto článku.

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. Ve volání přidejte middleware pro 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 :

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

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

Výstraha

Neoznačte metodu akce obslužné rutiny chyby atributy metody HTTP, jako je například . 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 vlastnost na požadovanou hodnotu. Tato konfigurace atributu vylučuje akci zpracování chyb ze specifikace OpenAPI aplikace:

[ApiExplorerSettings(IgnoreApi = true)]

Povolte anonymní přístup k metodě, pokud by neověření uživatelé měli vidět chybu.

Odpovědi na chyby klienta a serveru

Zvažte následující minimální aplikaci API.

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

Koncový bod vytvoří reprezentaci, když je větší než , jinak vrátí stavový kód bez těla odpovědi. Další informace o vytvoření odpovědi najdete v tématu Vytváření odpovědí v minimálních aplikacích API.

Dá se nakonfigurovat tak, aby vytvářel společný základní obsah, pokud je prázdný, pro všechny odpovědi klienta HTTP () nebo serveru (). Middleware je nakonfigurován voláním rozšiřující metody UseStatusCodePages.

Následující příklad například změní aplikaci tak, aby reagovala na datovou část kompatibilní se standardem RFC 7807 pro klienta pro všechny odpovědi klienta a serveru, včetně chyb směrování (například ). Další informace najdete v části Podrobnosti o problému .

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

V případě rozhraní API založených na kontroleru je možné nakonfigurovat chybovou odpověď jedním z následujících způsobů:

1. Použijte službu detailů problému
2. Implementovat ProblemDetailsFactory
3. Použijte ApiBehaviorOptions.ClientErrorMapping

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 .

Automatické vytvoření stavových kódů chyb je ve výchozím nastavení povolené.

Podrobnosti o problému

Podrobnosti o problému nejsou jediným formátem odpovědi, který popisuje chybu rozhraní HTTP API, ale běžně se používají k hlášení chyb pro rozhraní HTTP API.

Služba podrobností problému implementuje rozhraní IProblemDetailsService, které podporuje vytváření podrobností o problému v ASP.NET Core. Metoda rozšíření při registraci výchozí implementace.

V aplikacích ASP.NET Core následující middleware generuje odpovědi HTTP s podrobnostmi o problému, když je zavoláno AddProblemDetails, s výjimkou případů, kdy Accept HTTP hlavička požadavku neobsahuje jeden z typů obsahu podporovaných registrovaným IProblemDetailsWriter (výchozí: application/json):

• : Vygeneruje odpověď na podrobnosti o problému, pokud není definována vlastní obslužná rutina.
• : Ve výchozím nastavení vygeneruje odpověď podrobností o problému.
• : Vygeneruje odpověď na podrobnosti o problému při vývoji, pokud hlavička HTTP požadavku neobsahuje .

Minimální aplikace API je možné nakonfigurovat tak, aby generovaly odpověď na podrobnosti o problému pro všechny odpovědi na chyby klienta HTTP a serveru, které ještě nemají základní obsah pomocí metody rozšíření.

Následující kód nakonfiguruje aplikaci tak, aby vygenerovala podrobnosti o problému:

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

Další informace o použití naleznete v tématu Podrobnosti o problému.

Náhradní služba IProblemDetailsService

V následujícím kódu vrátí chybu, pokud implementace nemůže vygenerovat :

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

Předchozí kód:

• Zapíše chybovou zprávu s náhradním kódem, pokud není schopen napsat . Například koncový bod, kde hlavička požadavku Accept určuje typ média, který server nepodporuje.
• Používá middleware pro obsluhu výjimek.

Poznámka:

V hlavičce požadavku podporuje následující typy médií:

• application/json
• application/problem+json
• Typy zástupných znaků, jako jsou například a

Typy médií bez formátu JSON, například nebo , nejsou podporovány a aktivují náhradní chování.

Následující ukázka je podobná té předchozí s tím rozdílem, že volá .

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

Služba podrobností o problému

ASP.NET Core podporuje vytváření Problem Details pro rozhraní HTTP API pomocí IProblemDetailsService.

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í , 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.

Přizpůsobte podrobnosti problému pomocí

Následující kód používá k nastavení :

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

Implementovat

MVC používá k vytvoření všech instancí a . Tato továrna se používá pro:

• Odpovědi na chyby klienta
• Odpovědi na chyby způsobené selháním ověřování
• a

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

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

Použijte

Pomocí vlastnosti můžete nakonfigurovat obsah odpovědi. Například následující kód aktualizuje danou vlastnost pro odpovědi 404:

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

Další funkce zpracování chyb

Migrace z kontrolerů na minimální rozhraní API

Pokud migrujete z rozhraní API založených na kontroleru na minimální rozhraní API:

1. Nahraďte filtry akcí filtry koncových bodů nebo middlewarem.
2. Nahrazení validace modelu ručním ověřením nebo vlastní vazbou
3. Nahrazení filtrů výjimek middlewarem zpracování výjimek
4. Nakonfigurujte podrobnosti problémů pro konzistentní odpovědi na chyby

Kdy použít zpracování chyb na základě kontroleru

Pokud potřebujete, zvažte rozhraní API založená na kontroleru:

• Scénáře komplexního ověřování modelu
• Centralizované zpracování výjimek napříč několika kontrolery
• Jemně odstupňovaná kontrola nad formátováním odpovědí na chyby
• Integrace s funkcemi MVC, jako jsou filtry a konvence

Podrobné informace o zpracování chyb založené na kontrolerech, včetně chyb ověření, přizpůsobení detailů problému a výjimkových filtrů, najdete v sekcích záložky 'Kontrolery'.

Odpověď na chybu ověření

U řadičů webového rozhraní API MVC odpoví typem odpovědi, když se ověření modelu nezdaří. MVC používá výsledky k vytvoření chybové odpovědi pro selhání ověření. Následující příklad nahrazuje výchozí objekt factory implementací, která také podporuje formátování odpovědí jako XML:

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

Ú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 :

   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 :

   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 maximální celočíselnou hodnotu minus 10. To umožňuje spuštění dalších filtrů na konci kanálu.

3. Do kolekce filtrů přidejte filtr akcí:

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

Hlavní rozdíly pro kontrolery

• Automatické ověření modelu: Kontrolery automaticky ověřují stav modelu a vrací odpovědi na chyby ověření.
• Filtry výjimek: Použití filtrů akcí a filtrů výjimek pro centralizované zpracování chyb
• Předdefinované podrobnosti o problému: Konfigurace standardizovaných chybových odpovědí
• Vlastní odpovědi na chyby: Přizpůsobení vlastního formátování chyb ověřování

Dodatečné zdroje

• Jak použít ověření ModelState ve webovém rozhraní API ASP.NET Core
• Zobrazit nebo stáhnout ukázkový kód
• Hellang.Middleware.ProblemDetails