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

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.

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

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

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

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.

Aby skonfigurować exception handler middleware, wywołaj UseExceptionHandler. Na przykład poniższy kod zmienia działanie aplikacji tak, aby odpowiadała klientowi treścią zgodną ze specyfikacją 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 Program.cs wywołaj UseExceptionHandler, aby dodać middleware 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 tak, aby odpowiadała na trasę /error:

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

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

[ApiExplorerSettings(IgnoreApi = true)]

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 /users zwraca 200 OK z reprezentacją json elementu User, gdy id jest większe niż 0, w przeciwnym razie kod stanu 400 BAD REQUEST bez treści odpowiedzi. Aby uzyskać więcej informacji na temat tworzenia odpowiedzi, zobacz Tworzenie odpowiedzi w minimalnych aplikacjach interfejsu API.

Element Status Code Pages middleware można skonfigurować tak, aby generował wspólną treść komunikatu, gdy jest ona pusta, dla wszystkich odpowiedzi HTTP klienta (400-499) lub serwera (500 -599). Oprogramowanie pośredniczące jest konfigurowane przez wywołanie metody rozszerzenia UseStatusCodePages .

Na przykład poniższy przykład zmienia aplikację tak, aby zwracała klientowi ładunek zgodny z RFC 7807 dla wszystkich odpowiedzi po stronie klienta i serwera, w tym błędów routingu (na przykład 404 NOT FOUND). 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. Zaimplementować ProblemDetailsFactory
3. Użyj ApiBehaviorOptions.ClientErrorMapping

Za wynik błędu uznaje się wynik z kodem stanu HTTP 400 lub wyższym. W przypadku kontrolerów interfejsu API sieci Web platforma MVC przekształca wynik błędu, tak aby utworzyć element ProblemDetails.

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

Aplikacje Minimal API można skonfigurować tak, aby generowały odpowiedzi ze szczegółami problemu dla wszystkich odpowiedzi błędów klienta i serwera HTTP, które nie zawierają jeszcze treści odpowiedzi, za pomocą metody rozszerzającej AddProblemDetails.

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 AddProblemDetails, zobacz Szczegóły problemu

Zapasowa usługa IProblemDetailsService

W poniższym kodzie httpContext.Response.WriteAsync("Fallback: An error occurred.") zwraca błąd, jeśli implementacja IProblemDetailsService nie jest w stanie wygenerować obiektu 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();

Poprzedni kod:

• Zapisuje komunikat o błędzie z kodem zastępczym, jeśli problemDetailsService nie może zapisać elementu ProblemDetails. Na przykład punkt końcowy, w którym nagłówek żądania Accept określa typ multimediów, którego element DefaultProblemDetailsWriter nie obsługuje.
• Używa middleware obsługi wyjątków.

Poniższy przykład jest podobny do poprzedniego, z wyjątkiem tego, że wywołuje 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);

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 BadRequest 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ą polecenia CustomizeProblemDetails

Poniższy kod używa ProblemDetailsOptions do ustawienia 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();

Zaimplementuj ProblemDetailsFactory

MVC używa metody Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory do tworzenia wszystkich instancji ProblemDetails i ValidationProblemDetails. Ta fabryka jest używana do:

• Odpowiedzi na błędy klienta
• Odpowiedzi na błędy niepowodzenia walidacji
• ControllerBase.Problem i ControllerBase.ValidationProblem

Aby dostosować odpowiedź zawierającą szczegóły problemu, zarejestruj niestandardową implementację ProblemDetailsFactory w Program.cs:

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

Użyj ApiBehaviorOptions.ClientErrorMapping

Użyj właściwości ClientErrorMapping, aby skonfigurować zawartość odpowiedzi ProblemDetails. Na przykład poniższy kod w pliku Program.cs aktualizuje właściwość Link dla odpowiedzi 404:

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

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. Zastąp walidację modelu walidacją ręczną lub niestandardowym wiązaniem
3. Zastępowanie filtrów wyjątków oprogramowaniem pośredniczącym obsługującym wyjątki
4. Konfigurowanie szczegółów problemu przy użyciu AddProblemDetails() funkcji 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ć szczegółowe informacje 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, zobacz sekcje kart Kontrolery .

Odpowiedź na błąd niepowodzenia walidacji

W przypadku kontrolerów internetowego interfejsu API platforma MVC zwraca odpowiedź typu ValidationProblemDetails, gdy walidacja modelu zakończy się niepowodzeniem. MVC używa wyników z InvalidModelStateResponseFactory, aby utworzyć odpowiedź błędu w przypadku niepowodzenia walidacji. Poniższy przykład zastępuje domyślną fabrykę implementacją, która obsługuje również formatowanie odpowiedzi jako XML w pliku 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();

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 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. Utwórz filtr akcji o nazwie 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;
           }
       }
   }
   

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

3. W pliku Program.cs 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ą 400 Bad Request 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: Konfigurowanie ApiBehaviorOptions dla ustandaryzowanych odpowiedzi na błędy
• Niestandardowe odpowiedzi na błędy: zastąp InvalidModelStateResponseFactory, aby niestandardowo formatować błędy walidacji