Статические классы Results и TypedResults в ASP.NET Core. Обзор методов

Содержание

Методы классов Results и TypedResults
Пример использования классов Results и TypedResults
Итого

Начиная с .NET 6 в ASP.NET Core появился статический класс Results, а с версии .NET 7 — TypedResults (типизированный эквивалент Results), которые упрощают нам управление кодами состояния HTTP и формирование ответа клиенту. Эти классы удобно использовать в том числе и при разработке собственных API. Рассмотрим методы, которые предоставляют эти статические классы.

Методы классов Results и TypedResults

`Accepted()`, `AcceptedAtRoute()`	Отправляет клиенту код статуса 202 Accepted Запрос был принят на обработку, но она не завершена. Клиенту не обязательно дожидаться окончательной передачи сообщения, так как может быть начат очень долгий процесс Примеры `Accepted()` и `AcceptedAtRoute()` см. здесь
`BadRequest()`	Отправляет клиенту код статуса 400 Bad Request сервер обнаружил в запросе клиента синтаксическую ошибку Пример `BadRequest()` см. здесь
`Bytes()`	Отправляет в ответ клиенту массив байтов и применяется обычно для отправки файлов
`Challenge()`	Создает объект `IResult` (или `ChallengeHttpResult`, если используется `TypedResults`) для которого выполняется метод `ChallengeAsync(HttpContext, String, AuthenticationProperties)`. Поведение этого метода зависит от сервиса `IAuthenticationService`. Возможные коды статуса, отправляемые методом: 401 Unauthorized для доступа к запрашиваемому ресурсу требуется аутентификация. В заголовке ответ должен содержать поле WWW-Authenticate с перечнем условий аутентификации 403 Forbidden сервер понял запрос, но он отказывается его выполнять из-за ограничений в доступе для клиента к указанному ресурсу. Иными словами, клиент не уполномочен совершать операции с запрошенным ресурсом
`Conflict()`	Отправляет ответ с кодом статуса 409 Conflict запрос не может быть выполнен из-за конфликтного обращения к ресурсу. Такое возможно, например, когда два клиента пытаются изменить ресурс с помощью метода PUT Пример `Conflict()` см. здесь
`Content()`	Отправляет клиенту текст. Примеры см. здесь
`Created()`, `CreatedAtRoute()`	Отправляет ответ с кодом статуса 201 Created В результате успешного выполнения запроса был создан новый ресурс. Сервер может указать адрес(-а) созданного ресурса в теле ответа, при этом предпочтительный адрес указывается в заголовке Location. Формат тела ответа определяется заголовком Content-Type. При обработке запроса новый ресурс должен быть создан до отправки ответа клиенту, иначе следует использовать ответ с кодом 202 (см. метод Accepted()) Примеры `Created()`и `CreatedAtRoute()`см. здесь
`Forbid()`	Создает объект `IResult` (или `ForbidHttpResult`, если используется `TypedResults)` который выполняет метод `ForbidAsync(HttpContext, String, AuthenticationProperties)` . По умолчанию при выполнении этого метода клиенту возвращается код статуса 403 Forbidden сервер понял запрос, но он отказывается его выполнять из-за ограничений в доступе для клиента к указанному ресурсу. Иными словами, клиент не уполномочен совершать операции с запрошенным ресурсом
`Json()`	Отправляет клиенту ответ в формате JSON. Примеры см. здесь
`LocalRedirect()`, `RedirectToRoute()`	Перенаправляет пользователя на локальный URL. В зависимости от заданных параметров метода может возвращать один из четырех статусных кодов: 308 Permanent Redirect запрашиваемый ресурс был окончательно перенесен на новый URI, указанный в поле Location заголовка 307 Temporary Redirect запрашиваемый ресурс на короткое время доступен по другому URI, указанный в поле Location заголовка 301 Moved Permanently запрошенный документ был окончательно перенесен на новый URI, указанный в поле Location заголовка 302 Found запрошенный документ временно доступен по другому URI, указанному в заголовке в поле Location Пример `LocalRedirect` см. здесь Пример `RedirectToRoute` см. здесь
`NoContent()`	Отправляет ответ с кодом статуса 204 No Content сервер успешно обработал запрос, но в ответе были переданы только заголовки без тела сообщения Пример `NoContent()` см. здесь
`NotFound()`	Отправляет ответ с кодом статуса 404 Not Found сервер понял запрос, но не нашёл соответствующего ресурса по указанному URL Пример `NotFound()` см. здесь
`Ok()`	Отправляет ответ с кодом статуса 200 OK успешный запрос Пример `Ok()` см. здесь
`Problem()`	Применяет формат `ProblemDetails` для отправки ответа.
`Redirect()`	Перенаправляет на указанный адрес. В зависимости от заданных параметров метода может возвращать один из трех статусных кодов: 308 Permanent Redirect запрашиваемый ресурс был окончательно перенесен на новый URI, указанный в поле Location заголовка 307 Temporary Redirect запрашиваемый ресурс на короткое время доступен по другому URI, указанный в поле Location заголовка 301 Moved Permanently запрошенный документ был окончательно перенесен на новый URI, указанный в поле Location заголовка Пример использования см. здесь
`SignIn()`	Создает объект `IResult` (или `SignInHttpResult`, если используется `TypedResults`), для которого выполняется метод `SignInAsync(HttpContext, String, AuthenticationProperties)`
`SignOut()`	Создает объект `IResult` (или `SignOutHttpResult`, если используется `TypedResults`), для которого выполняется метод `SignOutAsync(HttpContext, String, AuthenticationProperties)`
`StatusCode()`	Отправляет клиенту определенный статусный код. Пример `StatusCode()` см. здесь
`Stream()`	Записывает в ответ поток данных. По своему действию аналогичен методу `File(Stream, String, String, Nullable<DateTimeOffset>, EntityTagHeaderValue, Boolean)`
`Text()`	Отправляет в ответе клиенту текстовое содержимое. Аналогичен методу `Content(String, String, Encoding)`Описание метода см. здесь
`Unauthorized()`	Отправляет ответ с кодом статуса 401 Unauthorized для доступа к запрашиваемому ресурсу требуется аутентификация. В заголовке ответ должен содержать поле WWW-Authenticate с перечнем условий аутентификации Пример `Unauthorized()`см. здесь
`UnprocessableEntity()`	Отправляет ответ с кодом статуса 422 Unprocessable Entity сервер успешно принял запрос и может работать с указанным видом данных, однако имеется какая-то логическая ошибка, из-за которой невозможно произвести операцию над ресурсом Пример `UnprocessableEntity()` см. здесь
`ValidationProblem()`	Отправляет ответ с кодом статуса 400 Bad Request сервер обнаружил в запросе клиента синтаксическую ошибку Пример `ValidationProblem()` см. здесь
`File()`, `PhysicalFile()`, `VirtualFile()`	Отправляет клиенту файл Пример `File()` см. здесь Пример `VirtualFile()` см. здесь

Пример использования классов Results и TypedResults

Рассмотрим небольшой пример, демонстрирующий работу классов Results и TypedResults. Допустим, нам необходимо на какой-то запрос пользователя ответить кодом 201 Created. Без классов Results и TypedResults мы бы это сделали, например, так:

app.MapGet("/create", (context) =>
{
    context.Response.ContentType = "text/html";
    context.Response.Headers["Location"] = "/crated";
    context.Response.StatusCode = 201;
    return Task.CompletedTask;
});

В соответствии с описанием кода 201, мы должны отправить в заголовке Location путь к созданному ресурсу тип которого определяется заголовком Content-Type, что мы и сделали в коде выше. С использованием классов Results и TypedResults это же действие можно сократить до одной строки:

app.MapGet("/create", () => Results.Created("/created",null));

Итого

Классы Results и TypedResults позволяют упростить работу с различными кодами статуса HTTP и содержат ряд методов, с помощью которых мы можем отправлять пользователю файлы, сообщать о проблемах и т.д. В следующих частях мы более подробно рассмотрим работы методов этих классов.