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

Замечание

Это не последняя версия этой статьи. В текущей версии см. версию .NET 10 этой статьи.

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

Эта версия ASP.NET Core больше не поддерживается. Для получения дополнительной информации см. Политику поддержки .NET и .NET Core. Для текущей версии см. версию .NET 9 этой статьи.

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

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

Контроллеры

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

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

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

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

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

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

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

Не включите страницу исключений разработчика, если приложение не запущено в среде разработки. Не делитесь подробными сведениями об исключениях публично при запуске приложения в рабочей среде. Дополнительные сведения о настройке сред см. в 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:

• Запустите пример приложения в среде разработки.
• Перейдите к конечной точке /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();

Контроллеры

Чтобы просмотреть страницу исключений разработчика в 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();

Контроллеры

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 код состояния без текста ответа. Дополнительные сведения о создании ответа см. в статье "Создание ответов" в приложениях 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);

Контроллеры

Для 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 по промежуточному слоям по промежуточному слоя возникает проблема, когда вызывается ответы AddProblemDetails HTTP, за исключением случаев, когда Accept заголовок HTTP запроса не включает один из типов контента, поддерживаемых зарегистрированным 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 указывает тип носителя, который DefaulProblemDetailsWriter не поддерживается.
• Использует ПО промежуточного слоя обработчика исключений.

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

Контроллеры

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

ASP.NET Core поддерживает создание сведений о проблеме для API HTTP с помощью .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, такими как фильтры и соглашения

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

Контроллеры

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

Для контроллеров веб-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
• Просмотр или скачивание примера кода
• Hellang.Middleware.ProblemDetails