Обработка ошибок в API ASP.NET Core

Замечание

Это не последняя версия этой статьи. См. версию этой статьи для .NET 10, чтобы узнать о текущем выпуске.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в разделе политика поддержки .NET и .NET Core. См. версию этой статьи для .NET 10, чтобы узнать о текущем выпуске.

Минимальные API

В этой статье описывается обработка ошибок в ASP.NET Core API. Выбрана документация по минимальным API. Чтобы просмотреть документацию по API на основе контроллера, перейдите на вкладку Controllers. Инструкции по обработке ошибок Blazor см. в разделе об ошибках Handle в приложениях ASP.NET Core Blazor.

Controllers

В этой статье описывается обработка ошибок в ASP.NET Core API. Выбрана документация по API с контроллером. Чтобы просмотреть документацию по Minimal APIs, перейдите на вкладку Minimal APIs. Руководство по обработке ошибок Blazor см. в разделе Обработка ошибок в приложениях ASP.NET Core Blazor.

Страница исключений разработчика

Страница исключений для разработчика содержит подробные сведения о необработанных исключениях запросов. Он использует DeveloperExceptionPageMiddleware для записи синхронных и асинхронных исключений из конвейера HTTP и для создания ответов об ошибках. Страница исключений разработчика выполняется в начале конвейера промежуточного ПО, чтобы перехватывать необработанные исключения, возникающие в последующем промежуточном ПО.

ASP.NET Core приложения поддерживают страницу исключений разработчика по умолчанию, если оба:

• Запуск в Development среде.
• Приложение было создано с использованием текущих шаблонов, то есть с помощью WebApplication.CreateBuilder.

Приложения, созданные с использованием более ранних шаблонов, то есть с помощью WebHost.CreateDefaultBuilder, могут включить страницу исключений разработчика, вызвав app.UseDeveloperExceptionPage.

Предупреждение

Не включите страницу исключений разработчика, если приложение не запущено в Development среде. Не делитесь подробными сведениями об исключениях публично при запуске приложения в рабочей среде. Дополнительные сведения о настройке сред см. в разделе ASP.NET Core среды выполнения.

Страница исключений разработчика может содержать следующие сведения об исключении и запросе:

• Трассировка стека
• Параметры строки запроса, если таковые есть
• Файлы cookie, если таковые есть
• Headers
• Метаданные конечной точки, если таковые есть

Страница исключений разработчика не гарантирует предоставления каких-либо сведений. Используйте Ведение журнала для получения полных сведений об ошибке.

На следующем рисунке показана пример страницы исключений разработчика с анимацией для отображения вкладок и отображаемых сведений:

В ответ на запрос с заголовком страница исключений разработчика возвращает обычный Accept: text/plain текст вместо HTML. Рассмотрим пример.

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

Минимальные API

Чтобы просмотреть страницу исключений разработчика в минимальном API:

• Запустите пример приложения в Development среде.
• Перейдите к конечной точке /exception .

В этом разделе приведен пример приложения, демонстрирующий способы обработки исключений в минимальном API. Он создает исключение при запросе конечной точки /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();

Controllers

Чтобы просмотреть страницу исключений разработчика в API на основе контроллера, выполните следующие действия.

• Добавьте следующее действие контроллера в контроллерный API. Действие создает исключение при запросе конечной точки.

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

• Запустите приложение в среде разработки.

• Перейдите к конечной точке, определенной действием контроллера.

Обработчик исключений

В средах, отличных от среды разработки, используйте промежуточное ПО для обработки исключений для формирования данных об ошибке.

Минимальные API

Чтобы настроить exception handler middleware, вызовите UseExceptionHandler. Например, следующий код изменяет приложение так, чтобы оно отправляло клиенту ответ в формате, соответствующем RFC 7807. Дополнительные сведения см. в разделе "Сведения о проблеме" далее в этой статье.

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

Controllers

1. В Program.cs вызовите UseExceptionHandler, чтобы добавить промежуточное ПО для обработки исключений:

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

2. Настройте действие контроллера для обработки маршрута /error:

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

HandleError Предыдущее действие отправляет клиенту полезную нагрузку, соответствующую RFC 7807.

Предупреждение

Не следует помечать метод действия обработки ошибок атрибутами метода HTTP, например HttpGet. Явные глаголы предотвращают некоторые запросы от прохождения до метода действия.

Для веб-API, использующих Swagger / OpenAPI, пометьте действие обработчика ошибок атрибутом [ApiExplorerSettings] и задайте для его свойства IgnoreApiзначениеtrue. Эта конфигурация атрибута исключает действие обработчика ошибок из спецификации OpenAPI приложения:

[ApiExplorerSettings(IgnoreApi = true)]

Разрешить анонимный доступ к методу, если пользователи, не прошедшие проверку подлинности, должны увидеть ошибку.

Ответы на ошибки клиента и сервера

Минимальные API

Рассмотрим следующее минимальное приложение 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);

Эндпоинт /users возвращает 200 OK с представлением json для User, если id больше 0, в противном случае — код состояния 400 BAD REQUEST без тела ответа. Дополнительные сведения о создании ответа см. в статье Создание ответов в приложениях Minimal API.

Status Code Pages middleware можно настроить на формирование единого содержимого тела, если оно пустое, для всех ответов HTTP-клиента (400-499) или сервера (500 -599). ПО промежуточного слоя настраивается путем вызова метода расширения UseStatusCodePages .

Например, в следующем примере приложение настраивается так, чтобы отвечать клиенту полезной нагрузкой, соответствующей RFC 7807, для всех клиентских и серверных ответов, включая ошибки маршрутизации (например, 404 NOT FOUND). Дополнительные сведения см. в разделе "Сведения о проблеме ".

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

Controllers

Для API на основе контроллера ответ об ошибке можно настроить одним из следующих способов:

1. Использование службы сведений о проблеме
2. Реализуйте ProblemDetailsFactory
3. Используйте ApiBehaviorOptions.ClientErrorMapping

Результат ошибки определяется в результате с кодом состояния HTTP 400 или выше. Для контроллеров веб-API MVC преобразует результат ошибки в ProblemDetails.

Автоматическое создание ProblemDetails для кодов состояния ошибок включено по умолчанию.

Сведения о проблеме

Сведения о проблеме — это не единственный формат ответа, описывающий ошибку API HTTP, однако они часто используются для сообщения об ошибках для API HTTP.

Служба сведений о проблеме реализует интерфейс IProblemDetailsService, который поддерживает создание сведений о проблеме в ASP.NET Core. Метод расширения AddProblemDetails(IServiceCollection) на IServiceCollection регистрирует реализацию IProblemDetailsService по умолчанию.

В приложениях ASP.NET Core следующий промежуточный компонент создает HTTP-ответы для сведений о проблемах, когда вызывается AddProblemDetails, за исключением случаев, когда HTTP-заголовок запроса Accept не содержит один из типов контента, поддерживаемых зарегистрированным IProblemDetailsWriter (по умолчанию: application/json):

• ExceptionHandlerMiddleware: формирует ответ с деталями проблемы, когда пользовательский обработчик не определён.
• StatusCodePagesMiddleware: по умолчанию создает ответ с деталями проблемы.
• DeveloperExceptionPageMiddleware: создает ответ сведений о проблеме в разработке, если Accept заголовок HTTP запроса не включает text/html.

Минимальные API

Минимальные приложения API можно настроить на создание ответа с подробностями о проблеме для всех HTTP-ответов с ошибками клиента и сервера, тело которых ещё не содержит данных, с помощью метода расширения AddProblemDetails.

Следующий код настраивает приложение для создания сведений о проблеме:

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

Дополнительные сведения об использовании AddProblemDetailsсм. в разделе "Сведения о проблеме"

Резервный IProblemDetailsService

В следующем коде httpContext.Response.WriteAsync("Fallback: An error occurred.") возвращает ошибку, если реализация IProblemDetailsService не может создать 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();

Предыдущий код:

• Записывает сообщение об ошибке с резервным кодом, если problemDetailsService не удается записать ProblemDetails. Например, конечная точка, в которой заголовок запроса Accept указывает тип носителя, который DefaultProblemDetailsWriter не поддерживается.
• Использует ПО промежуточного слоя обработчика исключений.

Замечание

Поддерживает DefaultProblemDetailsWriter следующие типы носителей в заголовке Accept запроса:

• application/json
• application/problem+json
• Типы с подстановочными знаками, такие как */* и application/*

Типы носителей, отличные от JSON, например application/xml или text/html, не поддерживаются и запускают резервное поведение.

Следующий пример аналогичен предыдущему, за исключением того, что он вызывает 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);

Controllers

Служба сведений о проблеме

ASP.NET Core поддерживает создание Problem Details for HTTP API с помощью IProblemDetailsService.

Следующий код настраивает приложение на создание ответа с подробными сведениями о проблеме для всех ответов с ошибками HTTP-клиента и сервера, которые еще не содержат содержимого тела:

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

Рассмотрим контроллер API из предыдущего раздела, который возвращает BadRequest , когда входные данные недопустимы:

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

Ответ с информацией о проблеме создается в показанном выше коде при выполнении любого из следующих условий.

• Подаются недопустимые данные.
• Универсальный код ресурса (URI) не имеет соответствующей конечной точки.
• Возникает необработанное исключение.

Настройка сведений о проблеме с помощью CustomizeProblemDetails

В следующем коде для задания ProblemDetailsOptions используется 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();

Реализуйте ProblemDetailsFactory

MVC использует Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory для создания всех экземпляров ProblemDetails и ValidationProblemDetails. Эта фабрика используется для:

• Ответы на ошибки клиента
• Ответы на ошибки проверки
• ControllerBase.Problem и ControllerBase.ValidationProblem.

Чтобы настроить ответ с подробными сведениями о проблеме, зарегистрируйте пользовательскую реализацию ProblemDetailsFactory в Program.cs:

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

Используйте ApiBehaviorOptions.ClientErrorMapping

Используйте свойство ClientErrorMapping для настройки содержимого ответа ProblemDetails. Например, следующий код в Program.cs обновляет свойство Link для ответов 404:

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

Дополнительные функции обработки ошибок

Минимальные API

Миграция с контроллеров на минимальные API

Если вы мигрируете с API на основе контроллера на минимальные API:

1. Замените фильтры действий на фильтры конечных точек или промежуточное ПО
2. Замена проверки модели ручной проверкой или пользовательской привязкой
3. Замените фильтры исключений на промежуточное ПО для обработки исключений
4. Настройте подробные сведения о проблеме с помощью AddProblemDetails() для единообразных ответов об ошибках

Когда следует использовать обработку ошибок на основе контроллера

При необходимости рассмотрите api на основе контроллера:

• Сложные сценарии проверки моделей
• Централизованная обработка исключений между несколькими контроллерами
• Точное управление форматированием ответа на ошибки
• Интеграция с функциями MVC, такими как фильтры и соглашения

Подробные сведения об обработке ошибок на основе контроллера, включая ошибки проверки, настройку сведений о проблеме и фильтры исключений, см. в разделах вкладки "Контроллеры ".

Controllers

Ответ на ошибку проверки

Для контроллеров веб-API MVC возвращает ответ типа ValidationProblemDetails, если проверка модели завершается неудачей. MVC использует результаты InvalidModelStateResponseFactory для создания ответа на ошибку для сбоя проверки. В следующем примере фабрика по умолчанию заменяется реализацией, которая также поддерживает форматирование ответов в XML, в элементе 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();

Использование исключений для изменения ответа

Содержимое ответа можно изменить за пределами контроллера с помощью настраиваемого исключения и фильтра действий:

1. Создайте известный тип исключения с именем 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. Создайте фильтр действий с именем 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;
           }
       }
   }
   

   Предыдущий фильтр задает Order значение, равное максимальному целочисленному значению минус 10. Это Order позволяет другим фильтрам запускаться в конце конвейера.

3. В Program.cs добавьте фильтр действий в коллекцию фильтров:

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

Основные различия для контроллеров

• Автоматическая проверка модели: контроллеры автоматически проверяют состояние модели и возвращают 400 Bad Request ответы на ошибки проверки.
• Фильтры исключений: использование фильтров действий и фильтров исключений для централизованной обработки ошибок
• Встроенные сведения о проблеме: настройка ApiBehaviorOptions стандартных ответов на ошибки
• Настраиваемые ответы на ошибки: переопределение InvalidModelStateResponseFactory для форматирования пользовательских ошибок проверки

Дополнительные ресурсы

• Использование проверки ModelState в веб-API ASP.NET Core
• View или скачайте пример кода
• Hellang.Middleware.ProblemDetails