Application error web service

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

В этой статье описывается обработка ошибок и настройка обработки ошибок с помощью ASP.NET Core веб-API.

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

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

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

Если клиент запрашивает ответ в формате HTML, страница исключений разработчика создает ответ, аналогичный следующему примеру:

Чтобы запросить ответ в формате HTML, задайте для заголовка Accept HTTP-запроса значение text/html .

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

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

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

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

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

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

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

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

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

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

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

Маршрут /error-development в среде разработки.
Маршрут в средах /error , не относящихся к разработке.

Добавьте действия контроллера как для маршрутов Разработки, так и для маршрутов, не относящихся к разработке:

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

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

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

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

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

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

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

В контроллерах веб-API MVC отвечает с помощью типа ответа ValidationProblemDetails при сбое проверки модели. MVC использует результаты InvalidModelStateResponseFactory для создания ответа в случае ошибки при сбое проверки. В следующем примере фабрика по умолчанию заменяется реализацией, которая также поддерживает форматирование ответов в формате XML в Program.cs :

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

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

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

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

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

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

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

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

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

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

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

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

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

Отключить автоматическое создание ProblemDetails для кодов состояния ошибок можно, задав свойству SuppressMapClientErrors значение true :

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

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

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

Обновленный контроллер API:

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

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

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

Реализуйте ProblemDetailsFactory

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

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

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

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

В этой статье описывается обработка ошибок и настройка обработки ошибок с помощью ASP.NET Core веб-API.

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

Чтобы запросить ответ в формате HTML, задайте для заголовка Accept HTTP-запроса значение text/html .

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

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

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

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

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

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

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

Маршрут /error-development в среде разработки.
Маршрут в средах /error , не относящихся к разработке.

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

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

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

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

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

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

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

Реализуйте ProblemDetailsFactory

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

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

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

Создание полезных данных ProblemDetails для исключений

ASP.NET Core не создает стандартизированные полезные данные ошибок при возникновении необработанного исключения. В сценариях, в которых желательно возвращать клиенту стандартизованный ответ ProblemDetails , ПО промежуточного слоя ProblemDetails можно использовать для сопоставления исключений и 404 ответов с полезными данными ProblemDetails . ПО промежуточного слоя для обработки исключений ProblemDetails также можно использовать для возврата полезных данных для необработанных исключений.

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

В этой статье описывается обработка и настройка обработки ошибок с помощью веб-API ASP.NET Core.

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

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

Выполните следующую команду curl , чтобы проверить предыдущее действие:

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

Чтобы вместо этого отображался отформатированный HTML-запрос, задайте для заголовка HTTP-запроса Accept тип носителя text/html . Пример:

Рассмотрим следующий фрагмент HTTP-ответа:

Отформатированный HTML-ответ полезен при тестировании с помощью таких инструментов, как Postman. На следующем снимке экрана показаны ответы в виде обычного текста и в формате HTML в Postman:

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

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

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

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

В Startup.Configure вызовите UseExceptionHandler, чтобы использовать ПО промежуточного слоя:

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

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

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

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

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

Маршрут /error-local-development в среде разработки.
Маршрут /error в средах, не имеющих отношения к разработке.

Примените маршрутизацию атрибутов к действиям контроллера:

Приведенный выше код вызывает ControllerBase.Problem для создания ProblemDetails ответа.

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

Содержимое ответа можно изменить за пределами контроллера. В веб-API ASP.NET 4.x один из способов это сделать — использовать тип HttpResponseException. ASP.NET Core не содержит эквивалентный тип. Поддержку HttpResponseException можно добавить, сделав следующее:

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

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

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

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

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

В контроллерах веб-API MVC отвечает с помощью типа ответа ValidationProblemDetails при сбое проверки модели. MVC использует результаты InvalidModelStateResponseFactory для создания ответа в случае ошибки при сбое проверки. В следующем примере в Startup.ConfigureServices для изменения типа ответа по умолчанию на SerializableError используется фабрика:

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

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

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

Реализуйте ProblemDetailsFactory

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

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

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

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

Источник