Obsługa błędów w interfejsach API ASP.NET Core

Uwaga / Notatka

Nie jest to najnowsza wersja tego artykułu. Aby uzyskać bieżącą wersję, zobacz artykuł w wersji .NET 10.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz .NET i .NET Core Support Policy. Aby uzyskać bieżącą wersję, zobacz artykuł w wersji .NET 10.

W tym artykule opisano sposób obsługi błędów w interfejsach API ASP.NET Core. Wybrano dokumentację dla minimalnych interfejsów API. Aby wyświetlić dokumentację interfejsów API opartych na kontrolerach, wybierz kartę Controllers. Aby uzyskać wskazówki dotyczące obsługi błędów Blazor, zobacz Obsługi błędów w ASP.NET Core Blazor apps.

W tym artykule opisano sposób obsługi błędów w interfejsach API ASP.NET Core. Wybrano dokumentację interfejsów API opartych na kontrolerze. Aby zapoznać się z dokumentacją Minimal APIs, wybierz kartę Minimal APIs. Aby uzyskać wskazówki dotyczące obsługi błędów Blazor, zobacz sekcję Handle errors in ASP.NET Core Blazor aplikacje.

Strona wyjątku dla deweloperów

Strona wyjątków dewelopera wyświetla szczegółowe informacje o nieobsłużonych wyjątkach żądań. Używa go do przechwytywania synchronicznych i asynchronicznych wyjątków z potoku HTTP i generowania odpowiedzi o błędach. Strona wyjątku dla deweloperów jest uruchamiana na wczesnym etapie pipeline'u pośredniczącego, dzięki czemu może przechwytywać nieobsługiwane wyjątki zgłaszane w oprogramowaniu pośredniczącym, które następuje.

Aplikacje ASP.NET Core włączają domyślnie stronę wyjątków dla deweloperów, gdy spełnione są oba poniższe warunki:

• Działanie w środowisku.
• Aplikacja została utworzona przy użyciu bieżących szablonów, to znaczy, że zastosowano .

Aplikacje utworzone przy użyciu wcześniejszych szablonów, czyli przy użyciu metody , mogą włączyć stronę wyjątku dla deweloperów, wywołując metodę .

Ostrzeżenie

Nie włączaj strony wyjątków dewelopera, chyba że aplikacja jest uruchomiona w środowisku. Nie udostępniaj publicznie szczegółowych informacji o wyjątkach, gdy aplikacja działa w środowisku produkcyjnym. Aby uzyskać więcej informacji na temat konfigurowania środowisk, zobacz ASP.NET Core środowiska uruchomieniowe.

Strona wyjątku dewelopera może zawierać następujące informacje o wyjątku i żądaniu:

• Ślad stosu
• Parametry ciągu zapytania, jeśli istnieją
• Pliki cookie, jeśli istnieją
• Nagłówki
• Metadane punktu końcowego, jeśli istnieją

Strona wyjątków dla deweloperów nie gwarantuje, że poda jakiekolwiek informacje. Użyj logowania, aby uzyskać pełne informacje o błędzie.

Na poniższej ilustracji przedstawiono przykładową stronę wyjątków dla deweloperów z animacją pokazującą karty oraz prezentowane informacje.

Animowana strona wyjątku dla deweloperów, aby wyświetlić każdą wybraną kartę.

W odpowiedzi na żądanie z nagłówkiem HTTP, strona wyjątków dewelopera zwraca zwykły tekst zamiast HTML. Przykład:

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

Aby wyświetlić stronę wyjątków dla deweloperów w Minimal API:

• Uruchom przykładową aplikację w środowisku.
• Przejdź do punktu końcowego .

W tej sekcji opisano następującą przykładową aplikację, aby zademonstrować sposoby obsługi wyjątków w minimalnym interfejsie API. Zgłasza wyjątek w przypadku żądania punktu końcowego :

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

Aby wyświetlić Stronę Wyjątku Programisty w interfejsie API opartym na kontrolerze:

• Dodaj następującą akcję kontrolera do interfejsu API opartego na kontrolerze. Akcja generuje wyjątek, gdy żądany jest punkt końcowy.

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

• Uruchom aplikację w środowisku deweloperów.

• Przejdź do punktu końcowego zdefiniowanego przez akcję kontrolera.

Mechanizm obsługi wyjątków

W środowiskach nieprodukcyjnych użyj Middleware obsługi wyjątków, aby wygenerować komunikat błędu.

Aby skonfigurować metodę , wywołaj metodę . Na przykład, poniższy kod zmienia aplikację, aby odpowiadała klientowi ładunkiem zgodnym z RFC 7807. Aby uzyskać więcej informacji, zobacz sekcję Szczegóły problemu w dalszej części tego artykułu.

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. W pliku , wywołaj metodę , aby dodać middleware do obsługi wyjątków:

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

2. Skonfiguruj akcję kontrolera w celu reagowania na trasę:

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

Poprzednia akcja wysyła ładunek zgodny ze specyfikacją RFC 7807 do klienta.

Ostrzeżenie

Nie oznaczaj metody akcji procedury obsługi błędów z atrybutami metody HTTP, takimi jak . Explicitne czasowniki uniemożliwiają dotarcie niektórych żądań do metody działania.

W przypadku internetowych interfejsów API, które używają struktury Swagger /OpenAPI, oznacz akcję obsługi błędów za pomocą atrybutu [ApiExplorerSettings] i ustaw jego właściwość na . Ta konfiguracja atrybutu wyklucza akcję obsługi błędów ze specyfikacji interfejsu OpenAPI aplikacji:

[ApiExplorerSettings(IgnoreApi = true)]

Zezwalaj na anonimowy dostęp do metody, jeśli niezautoryzowani użytkownicy powinni zobaczyć błąd.

Odpowiedzi na błędy klienta i serwera

Rozważmy następującą minimalną aplikację interfejsu 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);

Punkt końcowy tworzy z reprezentacją wartości , gdy jest większa niż , w przeciwnym razie kod stanu bez treści odpowiedzi. Aby uzyskać więcej informacji na temat tworzenia odpowiedzi, zobacz Tworzenie odpowiedzi w minimalnych aplikacjach interfejsu API.

Można je skonfigurować tak, aby tworzyła wspólną zawartość treści, gdy jest pusta, dla wszystkich odpowiedzi klienta HTTP () lub serwera (). Oprogramowanie pośredniczące jest konfigurowane przez wywołanie metody rozszerzenia UseStatusCodePages .

Na przykład w poniższym przykładzie zmienia się działanie aplikacji, aby odpowiadała za pomocą ładunku zgodnego ze specyfikacją RFC 7807 do klienta dla wszystkich odpowiedzi serwera i klienta, w tym błędy routingu (na przykład ). Aby uzyskać więcej informacji, zobacz sekcję Szczegóły problemu .

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

W przypadku interfejsów API opartych na kontrolerze można skonfigurować odpowiedź o błędzie na jeden z następujących sposobów:

1. Korzystanie z usługi szczegółów problemu
2. Implementowanie elementu ProblemDetailsFactory
3. Korzystanie z opcji ApiBehaviorOptions.ClientErrorMapping

Wynik błędu jest definiowany jako wynik z kodem stanu HTTP 400 lub wyższym. W przypadku kontrolerów internetowego interfejsu API MVC przekształca wynik błędu w celu wygenerowania odpowiedniego wyniku.

Automatyczne tworzenie kodu stanu błędu jest domyślnie włączone.

Szczegóły problemu

Szczegóły problemu nie są jedynym formatem odpowiedzi opisujący błąd interfejsu API HTTP, jednak są one często używane do zgłaszania błędów dla interfejsów API HTTP.

Usługa szczegółów problemu implementuje interfejs IProblemDetailsService, który obsługuje tworzenie szczegółów problemu w ASP.NET Core. Metoda rozszerzenia w systemie rejestruje domyślną implementację.

W aplikacjach ASP.NET Core następujące middleware generuje szczegóły dotyczące problemów w odpowiedziach HTTP po wywołaniu AddProblemDetails, z wyjątkiem sytuacji, gdy nagłówek żądania HTTP Accept nie zawiera jednego z typów zawartości obsługiwanych przez zarejestrowany IProblemDetailsWriter (domyślnie: application/json):

• generuje odpowiedź z detalami problemu, gdy niestandardowa obsługa nie jest zdefiniowana.
• : domyślnie generuje odpowiedź ze szczegółami problemu.
• : generuje odpowiedź ze szczegółami problemu w środowisku programistycznym, gdy nagłówek żądania HTTP nie zawiera elementu .

Minimalne aplikacje interfejsu API można skonfigurować do generowania odpowiedzi zawierających szczegóły problemu dla wszystkich błędów klienta HTTP i serwera, które jeszcze nie mają treści, przy użyciu metody rozszerzenia.

Poniższy kod konfiguruje aplikację w celu wygenerowania szczegółów problemu:

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

Aby uzyskać więcej informacji na temat korzystania z programu , zobacz Szczegóły problemu

Zapasowa usługa IProblemDetailsService

W poniższym kodzie zwraca błąd, jeśli implementacja nie może wygenerować elementu :

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

Poprzedni kod:

• Zapisuje komunikat o błędzie z kodem rezerwowym, jeśli program nie może napisać elementu . Na przykład punkt końcowy, w którym nagłówek żądania Accept określa typ nośnika, którego nie obsługuje.
• Używa pośrednika obsługi wyjątków.

Uwaga / Notatka

Obsługuje następujące typy mediów w nagłówku żądania:

• application/json
• application/problem+json
• Typy symboli wieloznacznych, takie jak i

Typy nośników innych niż JSON, takie jak lub , nie są obsługiwane i wyzwalają zachowanie rezerwowe.

Poniższy przykład jest podobny do powyższego z tą różnicą, że wywołuje metodę .

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

Usługa szczegółów problemu

ASP.NET Core obsługuje tworzenie Problem Details dla interfejsów API HTTP przy użyciu IProblemDetailsService.

Poniższy kod konfiguruje aplikację tak, aby wygenerowała odpowiedź na szczegóły problemu dla wszystkich odpowiedzi na błędy klienta HTTP i serwera, które nie mają jeszcze zawartości treści:

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

Należy wziąć pod uwagę kontroler interfejsu API z poprzedniej sekcji, który zwraca wartość, gdy dane wejściowe są nieprawidłowe:

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

Odpowiedź ze szczegółami problemu jest generowana przy użyciu poprzedniego kodu, gdy ma zastosowanie dowolny z następujących warunków:

• Podano nieprawidłowe dane wejściowe.
• Identyfikator URI nie ma pasującego punktu końcowego.
• Występuje nieobsługiwany wyjątek.

Dostosowywanie szczegółów problemu za pomocą systemu

Poniższy kod używa funkcji, aby ustawić :

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

Wdrożyć

Funkcja MVC używa metody do tworzenia wszystkich wystąpień elementów i . Ta fabryka jest używana do:

• Odpowiedzi na błędy klienta
• Odpowiedzi na błędy niepowodzenia walidacji
• i

Aby dostosować odpowiedź ze szczegółami problemu, zarejestruj niestandardową implementację w :

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

Użyj

Użyj właściwości , aby skonfigurować zawartość odpowiedzi. Na przykład następujący kod aktualizuje właściwość dla odpowiedzi na błędy 404:

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

Dodatkowe funkcje obsługi błędów

Migracja z kontrolerów do minimalnych interfejsów API

Jeśli migrujesz z interfejsów API opartych na kontrolerach do minimalnych interfejsów API:

1. Zastępowanie filtrów akcji filtrami punktów końcowych lub oprogramowaniem pośredniczącym
2. Zamień walidację modelu na walidację ręczną lub powiązanie niestandardowe
3. Zastępowanie filtrów wyjątków oprogramowaniem pośredniczącym obsługującym wyjątki
4. Konfiguracja szczegółów problemu w celu uzyskania spójnych odpowiedzi na błędy

Kiedy należy używać obsługi błędów opartych na kontrolerze

W razie potrzeby rozważ użycie interfejsów API opartych na kontrolerze:

• Złożone scenariusze weryfikacji modelu
• Scentralizowana obsługa wyjątków na wielu kontrolerach
• Szczegółowa kontrola nad formatowaniem odpowiedzi na błędy
• Integracja z funkcjami MVC, takimi jak filtry i konwencje

Aby uzyskać więcej szczegółowych informacji na temat obsługi błędów opartych na kontrolerze, w tym błędów walidacji, dostosowywania szczegółów problemu i filtrów wyjątków, zapoznaj się z sekcjami w zakładce 'Kontrolery'.

Odpowiedź na błąd niepowodzenia walidacji

W przypadku kontrolerów internetowego interfejsu API MVC odpowiada określonym typem odpowiedzi, gdy walidacja modelu zakończy się niepowodzeniem. MvC używa wyników do konstrukcji odpowiedzi o błędzie w przypadku niepowodzenia weryfikacji. Poniższy przykład zastępuje domyślną factory implementacją, która obsługuje również formatowanie odpowiedzi 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();

Modyfikowanie odpowiedzi przy użyciu wyjątków

Zawartość odpowiedzi można zmodyfikować spoza kontrolera przy użyciu wyjątku niestandardowego i filtru akcji:

1. Utwórz dobrze znany typ wyjątku o nazwie :

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

2. Utwórz filtr akcji o nazwie :

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

   Powyższy filtr określa maksymalną wartość całkowitą minus 10. Umożliwia to uruchamianie innych filtrów na końcu potoku.

3. W pliku dodaj filtr akcji do kolekcji filtrów:

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

Kluczowe różnice dla kontrolerów

• Automatyczna walidacja modelu: kontrolery automatycznie weryfikują stan modelu i zwracają odpowiedzi pod kątem błędów walidacji
• Filtry wyjątków: użyj filtrów akcji i filtrów wyjątków do scentralizowanej obsługi błędów
• Wbudowane szczegóły problemu: Skonfiguruj dla ustandaryzowanych odpowiedzi na błędy
• Niestandardowe odpowiedzi na błędy: zastąpianie niestandardowego formatowania błędu walidacji

Dodatkowe zasoby

• Jak użyć weryfikacji stanu modelu w internetowym interfejsie API ASP.NET Core
• View lub pobierz przykładowy kod
• Hellang.Middleware.ProblemDetails