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

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

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

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

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

В этом разделе приведен пример приложения, демонстрирующий способы обработки исключений в минимальном API. Он создает исключение при запросе конечной точки :

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

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

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

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

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

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

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

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

[ApiExplorerSettings(IgnoreApi = true)]

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

Конечная точка создает представление о том, когда больше , в противном случае код состояния без текста ответа. Дополнительные сведения о создании ответа см. в разделе "Создание ответов" в приложениях на основе минимального API.

Его можно настроить для создания общего содержимого текста, если пусто для всех ответов HTTP-клиента () или сервера. ПО промежуточного слоя настраивается путем вызова метода расширения UseStatusCodePages .

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

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 преобразует результат ошибки для создания .

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

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

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

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

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

Резервный IProblemDetailsService

В следующем коде возвращает ошибку, если реализация не может создать :

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

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

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

Следующий пример аналогичен предыдущему, за исключением того, что он вызывает .

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 поддерживает создание Problem Details for HTTP API с помощью IProblemDetailsService.

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

[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) не имеет соответствующей конечной точки.
• Возникает необработанное исключение.

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

Следующий код используется для задания :

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

Реализовать

MVC используется для создания всех экземпляров объектов типа Model и View. Эта фабрика используется для:

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

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

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

Используйте

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Создайте известный тип исключения с именем :

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

2. Создайте фильтр действий с именем :

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

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

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

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

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

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