Создайте обработчик исключений в ASP.NET Core 8.

Ноябрьский выпуск .NET 8 от Microsoft принес множество новых замечательных функций. Одним из приятных улучшений, представленных в ASP.NET Core 8, является IExceptionHandler, интерфейс, который упрощает корректную обработку исключений в веб-приложениях ASP.NET Core.

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

Чтобы использовать примеры кода, представленные в этой статье, в вашей системе должна быть установлена ​​Visual Studio 2022. Если у вас еще нет копии, вы можете скачать Visual Studio 2022 здесь.

Создайте проект веб-API ASP.NET Core в Visual Studio 2022.

Чтобы создать проект веб-API ASP.NET Core 8 в Visual Studio 2022, выполните действия, описанные ниже.

1. Запустите интегрированную среду разработки Visual Studio 2022.
2. Нажмите «Создать новый проект».
3. В окне «Создать новый проект» выберите «ASP.NET Core Web API» из списка отображаемых шаблонов.
4. Нажмите “Далее.
5. В окне «Настроить новый проект» укажите имя и местоположение нового проекта.
6. При желании установите флажок «Поместить решение и проект в один каталог», в зависимости от ваших предпочтений.
7. Нажмите “Далее.
8. В следующем окне «Дополнительная информация» выберите «.NET 8.0 (долгосрочная поддержка)» в качестве версии платформы и убедитесь, что флажок «Использовать контроллеры» снят. В этом проекте мы будем использовать минимальные API.
9. В другом месте окна «Дополнительная информация» оставьте для параметра «Тип аутентификации» значение «Нет» (по умолчанию) и убедитесь, что флажки «Включить поддержку Open API», «Настроить HTTPS» и «Включить Docker» остаются снятыми. . Мы не будем здесь использовать ни одну из этих функций.
10. Нажмите Создать.

Мы будем использовать этот проект веб-API ASP.NET Core для работы с интерфейсом IExceptionHandler в разделах ниже.

Зачем нам нужен обработчик исключений?

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

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

Давайте разберемся в этом на примере. Рассмотрим следующий код.

using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;
using System.ComponentModel.DataAnnotations;
using System.Net;
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.UseExceptionHandler(opt => { });
app.MapGet("/GenerateError", () =>
{
    throw new NotImplementedException();
});
app.Run();

Когда вы запустите приложение и достигнете конечной точки /GenerateError, ответ, отображаемый в вашем веб-браузере, будет выглядеть, как показано ниже.

ИДГ

Обратите внимание, что ответ об ошибке не форматируется, и прочитать и понять метаданные об ошибке из этого ответа довольно сложно.

Знакомство с интерфейсом IExceptionHandler

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

Интерфейс IExceptionHandler выглядит следующим образом:

public interface IExceptionHandler
{
    ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception exception, CancellationToken cancellationToken);
}

Интерфейс IExceptionHandler содержит объявление метода TryHandleAsync. Этот метод принимает три параметра: экземпляр типа HttpContext, Exception и CancellationToken. Он возвращает ValueTask, чтобы указать, было ли исключение обработано успешно или нет.

Когда вы реализуете метод TryHandleAsync в своем классе, который расширяет интерфейс IExceptionHandler, вы должны вернуть логическое значение из этого метода. Вы должны вернуть true, если исключение было обработано, или false в противном случае.

Создайте собственный обработчик исключений в ASP.NET Core.

Чтобы реализовать интерфейс IExceptionHandler, создайте новый класс с именем GlobalExceptionHandler в одноименном файле с расширением .cs. И введите туда следующий код.

public class GlobalExceptionHandler(IHostEnvironment hostEnvironment, ILogger<GlobalExceptionHandler> logger)
    : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception exception, CancellationToken cancellationToken)
    {
        return true;
    }
}

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

private const string ExceptionMessage = "An unhandled exception has occurred while executing the request.";

public async ValueTask TryHandleAsync(HttpContext httpContext, исключение Exception, CancellationToken cancelToken)

{

logger.LogError(исключение, исключение — исключение? исключение.Сообщение: ExceptionMessage);

вар проблемаDetails = CreateProblemDetails (httpContext, исключение);

ждут httpContext.Response.WriteAsJsonAsync(problemDetails, cancelToken);

вернуть истину;

}

Теперь мы воспользуемся промежуточным программным обеспечением с открытым исходным кодом IssueDetails для создания согласованных, структурированных, машиночитаемых сообщений об ошибках. Метод CreateProblemDetails возвращает экземпляр IssueDetails, содержащий метаданные ошибки, как показано в приведенном ниже фрагменте кода.

private ProblemDetails CreateProblemDetails(in HttpContext httpContext, in Exception exception)

{

httpContext.Response.ContentType = “application/json”;

переключатель (исключение)

{

случай NotImplementedException notImplementedException:

httpContext.Response.StatusCode = (int)HttpStatusCode.BadRequest;

перерыв;

по умолчанию:

httpContext.Response.StatusCode = (int)HttpStatusCode.InternalServerError;

перерыв;

}

вернуть новые сведения о проблеме

{

Статус = (int)httpContext.Response.StatusCode,

Тип = исключение.GetType().Имя,

Title = «Произошла непредвиденная ошибка»,

Деталь = исключение.Сообщение,

Экземпляр = $”{httpContext.Request.Method} {httpContext.Request.Path}”

};

}

Полный исходный код нашего специального обработчика исключений

Следующий листинг кода содержит полный исходный код класса GlobalExceptionHandler.

public class GlobalExceptionHandler(IHostEnvironment hostEnvironment, ILogger<GlobalExceptionHandler> logger)

: IExceptionHandler

{

Private const string ExceptionMessage = “При выполнении запроса произошло необработанное исключение.”;

public async ValueTask TryHandleAsync(HttpContext httpContext, исключение исключения, CancellationToken cancelToken)

{

logger.LogError(исключение, исключение — исключение? исключение.Сообщение: ExceptionMessage);

вар проблемаDetails = CreateProblemDetails (httpContext, исключение);

ждут httpContext.Response.WriteAsJsonAsync(problemDetails, cancelToken);

вернуть истину;

}

частная проблемаDetails CreateProblemDetails (в HttpContext httpContext, в исключении исключения)

{

httpContext.Response.ContentType = “application/json”;

переключатель (исключение)

{

случай NotImplementedException notImplementedException:

httpContext.Response.StatusCode = (int)HttpStatusCode.BadRequest;

перерыв;

по умолчанию:

httpContext.Response.StatusCode = (int)HttpStatusCode.InternalServerError;

перерыв;

}

вернуть новые сведения о проблеме

{

Статус = (int)httpContext.Response.StatusCode,

Тип = исключение.GetType().Имя,

Title = «Произошла непредвиденная ошибка»,

Деталь = исключение.Сообщение,

Экземпляр = $”{httpContext.Request.Method} {httpContext.Request.Path}”

};

}

}

Зарегистрируйте обработчик исключений в конвейере обработки запросов.

Теперь, когда наш собственный обработчик исключений готов, нам нужно зарегистрировать его в конвейере обработки запросов, чтобы начать использовать его в нашем приложении. Вы можете зарегистрировать обработчик исключений, включив следующую строку кода в файл Program.cs.

builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

Давайте теперь создадим конечную точку обработки ошибок в Program.cs. При вызове этой конечной точки будет отображаться удобный для пользователя ответ об ошибке, как указано в настроенном обработчике ошибок. Чтобы создать конечную точку обработки ошибок, введите следующий код в файл Program.cs.

app.MapGet("/GenerateError", () =>

{

выбросить новое ValidationException();

});

Вызов метода UseExceptionHandler() настраивает конвейер обработки запросов в ASP.NET Core для обработки исключений с помощью нашего промежуточного программного обеспечения.

app.UseExceptionHandler(opt => { });

Теперь, когда вы запустите приложение и нажмете конечную точку /GenerateError, ответ, отображаемый в веб-браузере, будет выглядеть, как показано ниже. Намного лучше!

ИДГ

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