Обработка ошибок в веб-API на основе контроллера ASP.NET

В этой статье описывается, как обрабатывать ошибки и настраивать обработку ошибок в веб-API на основе контроллера ASP.NET Core. Сведения об обработке ошибок в минимальных API см. в разделе Об обработке ошибок в ASP.NET Core и обработке ошибок в минимальных API.

Страница со сведениями об исключении для разработчика

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

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

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

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

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

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

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

• Трассировка стека
• параметры строки запроса (при наличии);
• Файлы cookie, если таковые есть
• Заголовки
• Метаданные конечной точки, если таковые есть

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

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

В ответ на запрос с заголовком страница исключений разработчика возвращает обычный 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 на основе контроллера. Действие создает исключение при запросе конечной точки.

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

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

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

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

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

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] и задайте для его свойства trueзначениеIgnoreApi. Эта конфигурация атрибута исключает действие обработчика ошибок из спецификации OpenAPI приложения:

[ApiExplorerSettings(IgnoreApi = true)]

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

По промежуточному слоям обработки исключений также можно использовать в среде разработки для создания согласованного формата полезных данных во всех средах:

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

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

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

   • Маршрут /error-development в среде разработки.
   • Маршрут в средах, отличных от разработки /error .

2. Добавьте действия контроллера для маршрутов разработки и не разработки:

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

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

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

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

Ответ в случае ошибки при сбое проверки

В контроллерах веб-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();

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

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

Автоматическое создание ProblemDetails кодов состояния ошибки включено по умолчанию, но ответы на ошибки можно настроить одним из следующих способов:

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

Ответ сведений о проблеме по умолчанию

Program.cs Следующий файл был создан шаблонами веб-приложений для контроллеров API:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

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

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

• /api/values2/divide Конечная точка вызывается с нулевым знаменателем.
• Конечная /api/values2/squareroot точка вызывается с радикой меньше нуля.

Текст ответа о проблеме по умолчанию содержит следующие typetitleзначения:status

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

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

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

Отключить автоматическое создание ProblemDetails для кодов состояния ошибок можно, задав свойству SuppressMapClientErrors значение 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();

При возврате BadRequestконтроллера API состояние ответа HTTP 400 возвращается без текста ответа. SuppressMapClientErrors Запрещает ProblemDetails создание ответа даже при вызове WriteAsync конечной точки контроллера API. WriteAsync объясняется далее в этой статье.

В следующем разделе показано, как настроить текст ответа сведений о проблеме, используя его CustomizeProblemDetails, чтобы вернуть более полезный ответ. Дополнительные параметры настройки см. в разделе "Настройка проблем".

Настройка сведений о проблеме с помощью 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();

Обновленный контроллер 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));
    }

}

Следующий код содержит MathErrorFeature и MathErrorType, которые используются в предыдущем примере:

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

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

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

• /divide Конечная точка вызывается с нулевым знаменателем.
• Конечная /squareroot точка вызывается с радикой меньше нуля.
• Универсальный код ресурса (URI) не имеет соответствующей конечной точки.

Текст ответа сведений о проблеме содержит следующее, если любая squareroot конечная точка вызывается с радикандом меньше нуля:

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

Просмотреть или скачать образец кода

Реализуйте ProblemDetailsFactory

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

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

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

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

Использование ApiBehaviorOptions.ClientErrorMapping

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

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

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

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