Obsługa błędów w internetowych interfejsach API opartych na kontrolerze ASP.NET Core

W tym artykule opisano sposób obsługi błędów i dostosowywania obsługi błędów w internetowych interfejsach API opartych na kontrolerze ASP.NET Core. Aby uzyskać informacje o obsłudze błędów w minimalnych interfejsach API, zobacz Obsługa błędów w ASP.NET Core i Obsługa błędów w minimalnych interfejsach API.

Strona wyjątku dla deweloperów

Na stronie wyjątku dewelopera są wyświetlane szczegółowe informacje o nieobsługiwanych wyjątkach żądań. Używa DeveloperExceptionPageMiddleware 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 potoku oprogramowania pośredniczącego, dzięki czemu może przechwytywać nieobsługiwane wyjątki zgłaszane w następujący sposób oprogramowania pośredniczącego.

aplikacje ASP.NET Core domyślnie włączają stronę wyjątku dla deweloperów, gdy obie te aplikacje:

• Uruchamianie w środowisku programistycznym.
• Aplikacja została utworzona przy użyciu bieżących szablonów, czyli przy użyciu polecenia WebApplication.CreateBuilder.

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

Ostrzeżenie

Nie włączaj strony wyjątku dla deweloperów, chyba że aplikacja jest uruchomiona w środowisku dewelopera. 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 Używanie wielu środowisk w programie ASP.NET Core.

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ą
• Cookies, jeśli istnieją
• Nagłówki
• Metadane punktu końcowego, jeśli istnieją

Strona wyjątku dla deweloperów nie jest gwarantowana, aby podać żadne informacje. Użyj rejestrowania , aby uzyskać pełne informacje o błędzie.

Na poniższej ilustracji przedstawiono przykładową stronę wyjątku dla deweloperów z animacją, aby wyświetlić karty i wyświetlane informacje:

W odpowiedzi na żądanie z nagłówkiem Accept: text/plain strona wyjątku dewelopera zwraca zwykły tekst zamiast HTML. Na 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ątku dla deweloperów:

• Dodaj następującą akcję kontrolera do interfejsu API opartego na kontrolerze. Akcja zgłasza wyjątek w przypadku żądania punktu końcowego.

  [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.

Procedura obsługi wyjątków

W środowiskach nieprodukcyjnych użyj oprogramowania pośredniczącego obsługi wyjątków, aby wygenerować ładunek błędu:

1. W Program.cspliku wywołaj metodę UseExceptionHandler , aby dodać oprogramowanie pośredniczące 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 /error na trasę:

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

HandleError 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 HttpGet. Jawne czasowniki uniemożliwiają dotarcie niektórych żądań do metody akcji.

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 IgnoreApi właściwość na true. Ta konfiguracja atrybutu wyklucza akcję obsługi błędów ze specyfikacji interfejsu OpenAPI aplikacji:

[ApiExplorerSettings(IgnoreApi = true)]

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

Oprogramowanie pośredniczące obsługi wyjątków może być również używane w środowisku programistycznym do tworzenia spójnego formatu ładunku we wszystkich środowiskach:

1. W Program.csprogramie zarejestruj wystąpienia oprogramowania pośredniczącego obsługi wyjątków specyficzne dla środowiska:

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

   W poprzednim kodzie oprogramowanie pośredniczące jest zarejestrowane za pomocą:

   • Trasa /error-development w środowisku programistycznym.
   • Trasa /error w środowiskach nieprogramowania.

2. Dodaj akcje kontrolera zarówno dla tras programistycznych, jak i nieprogramowania:

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

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. Umożliwia to Order uruchamianie innych filtrów na końcu potoku.

3. W Program.cspliku dodaj filtr akcji do kolekcji filtrów:

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

Odpowiedź na błąd niepowodzenia walidacji

W przypadku kontrolerów internetowego interfejsu API mvC odpowiada za pomocą typu odpowiedzi, gdy walidacja modelu zakończy się niepowodzeniem ValidationProblemDetails . MvC używa wyników polecenia InvalidModelStateResponseFactory , aby skonstruować odpowiedź o błędzie dla błędu weryfikacji. 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();

Odpowiedź na błąd klienta

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

Automatyczne tworzenie ProblemDetails kodu stanu błędu jest domyślnie włączone, ale odpowiedzi na błędy można skonfigurować na jeden z następujących sposobów:

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

Domyślna odpowiedź na szczegóły problemu

Program.cs Następujący plik został wygenerowany przez szablony aplikacji internetowej dla kontrolerów interfejsu API:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Rozważmy następujący kontroler, 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:

• Punkt /api/values2/divide końcowy jest wywoływany z mianownikiem zerowym.
• Punkt /api/values2/squareroot końcowy jest wywoływany z promieniem mniejszym niż zero.

Domyślna treść odpowiedzi szczegółów problemu ma następujące typewartości , titlei status :

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

Usługa szczegółów problemu

ASP.NET Core obsługuje tworzenie szczegółów problemu dla interfejsów API HTTP przy użyciu polecenia IProblemDetailsService. Aby uzyskać więcej informacji, zobacz usługę Szczegóły problemu.

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.

Automatyczne tworzenie informacji ProblemDetails dla kodu stanu błędu jest wyłączone, gdy właściwość SuppressMapClientErrors jest ustawiona 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();

Korzystając z powyższego kodu, gdy kontroler interfejsu API zwraca BadRequestwartość , zwracany jest stan odpowiedzi HTTP 400 bez treści odpowiedzi. SuppressMapClientErrorsProblemDetails uniemożliwia utworzenie odpowiedzi, nawet podczas wywoływania WriteAsync punktu końcowego kontrolera interfejsu API. WriteAsync w dalszej części tego artykułu wyjaśniono.

W następnej sekcji pokazano, jak dostosować treść odpowiedzi szczegółów problemu przy użyciu polecenia CustomizeProblemDetails, aby zwrócić bardziej pomocną odpowiedź. Aby uzyskać więcej opcji dostosowywania, zobacz Dostosowywanie szczegółów problemu.

Dostosowywanie szczegółów problemu za pomocą polecenia CustomizeProblemDetails

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

Zaktualizowany kontroler interfejsu 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));
    }

}

Poniższy kod zawiera elementy MathErrorFeature i MathErrorType, które są używane z poprzednim przykładem:

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

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

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

• Punkt /divide końcowy jest wywoływany z mianownikiem zerowym.
• Punkt /squareroot końcowy jest wywoływany z promieniem mniejszym niż zero.
• Identyfikator URI nie ma pasującego punktu końcowego.

Treść odpowiedzi szczegółów problemu zawiera następujące elementy, gdy jeden squareroot z punktów końcowych jest wywoływany z promieniem mniejszym niż zero:

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

Wyświetlanie lub pobieranie przykładowego kodu

Narzędzie ProblemDetailsFactory

Funkcja MVC używa Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory metody do tworzenia wszystkich wystąpień elementów 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ź ze szczegółami problemu, zarejestruj niestandardową implementację ProblemDetailsFactory elementu w pliku Program.cs:

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

Korzystanie z polecenia ApiBehaviorOptions.ClientErrorMapping

ClientErrorMapping Użyj właściwości , aby skonfigurować zawartość ProblemDetails odpowiedzi. Na przykład następujący kod w Program.cs pliku aktualizuje Link właściwość 404 odpowiedzi:

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

Dodatkowe zasoby

• How to Use ModelState Validation in ASP.NET Core Web API
• Wyświetlanie lub pobieranie przykładowego kodu
• Hellang.Middleware.ProblemDetails