Results API

Введение в Results API

Для упрощения отправки ответа ASP.NET Core предоставляет специальный API - Results API. Он реализуется посредством методов статического класса Results:

• Accepted(): отправляет клиенту статусный код 202, который указывает, что запрос принят к обработке. Может принимать два необязательных параметра: первый параметр представляет адрес для отслеживания состояния запроса, а второй - произвольный объект, оправляемый в ответ клиенту

• AcceptedAtRoute(): также отправляет клиенту статусный код 202. Может принимать три необязательных параметра: первый параметр представляет имя маршрута, а второй - параметры для этого маршрута, третий - произвольный объект, оправляемый в ответ клиенту

• BadRequest(): отправляет клиенту статусный код 400, который указывает, что запрос не может быть обработан в силу содержащихся в нем ошибок. Может принимать необязательный параметр - произвольный объект, отправляемый в ответ клиенту

• Bytes(): отправляет в ответ клиенту массив байтов, обычно применяется для отправки файлов

  Этот метод по своему действию аналогичен методу

  File(Byte[], String, String, Boolean, Nullable<DateTimeOffset>, EntityTagHeaderValue)

• Challenge(): создает объект IResult, для которого выполняется метод ChallengeAsync(HttpContext, String, AuthenticationProperties)

  Поведение этого метода зависит от сервиса IAuthenticationService. В качестве возможных ответов могут статусные коды 401 (не авторизирован) и 403 (доступ запрещен)

• Conflict(): отправляет ответ со статусным кодом 409

• Content(): отправляет в ответе некоторую строку

• Created(): отправляет ответ со статусным кодом 201

• CreatedAtRoute(): отправляет ответ со статусным кодом 201

• File(): отправляет в ответ файл

• Forbid(): создает объект IResult, для которого выполняется метод ForbidAsync(HttpContext, String, AuthenticationProperties). По умолчанию отправляет статусный код 403 (доступ запрещен)

• Json(): отправляет ответ в формате JSON

• LocalRedirect(): перенаравляет на один из локальных адресов

• NoContent(): отправляет статусный код 204

• NotFound(): отправляет ответ со статусным кодом 404

• Ok(): отправляет ответ со статусным кодом 200

• Problem(): применяет формат ProblemDetails для отправки ответа.

• Redirect(): перенаравляет на определенный адрес

• RedirectToRoute(): перенаравляет на определенный маршрут

• SignIn(): создает объект IResult, для которого выполняется метод SignInAsync(HttpContext, String, ClaimsPrincipal, AuthenticationProperties)

• SignOut(): создает объект IResult, для которого выполняется метод SignOutAsync(HttpContext, String, AuthenticationProperties)

• StatusCode(): отправляет определенный статусный код

• Stream(): пишет в ответ поток данных. По своему действию аналогичен методу File(Stream, String, String, Nullable<DateTimeOffset>, EntityTagHeaderValue, Boolean)

• Text(): отправляет в ответ некоторое текстовое содержимое. Аналогичен методу Content(String, String, Encoding)

• Unauthorized(): отправляет статусный код 401

• UnprocessableEntity(): отправляет ответ со статусным кодом 422

• ValidationProblem(): отправляет ответ со статусным кодом 400

Применим один из методов:

var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.Map("/hello", () => Results.Text("Hello ASP.NET Core"));
app.Map("/", () => "Hello ASP.NET Core");

app.Run();

В данном случае в приложении определены две конечные точки: одна обрабатывает запросы по маршруту "/hello", а другая - запросы к корню веб-приложения. Первая конечная точка для отправки ответа использует метод Results.Text(). Другая конечная точка напрямую возвращает некоторую строку. Однако в реальности обе конечные точки продуцируют почти аналогичный ответ: также будет отправляться одна и та же строка со статусным кодом 200. Разница будет заключаться только в отдельных ззаголовках (в частности, метод Reqults.Text добавляет заголовок "Content-Length").

Подобным обазом можно обрабатывать запрос в отдельном методе, который возвращает объект IResult:

var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.Map("/hello", SendHello);
app.Map("/", () => "Hello ASP.NET Core 6");

app.Run();

IResult SendHello()
{
    return Results.Text("Hello ASP.NET Core");
}

Хотя мы можем отправлять некоторый ответ напрямую из конечных точек, не используя методы Results, тем не менее методы Results API могут быть полезны, когда необходимо установить какие-то дополнительные параметры ответа, например, кодировку, форматирование в json. И конечно мы можем использовать методы Results API для отправки в конечных точках статусных кодов, файлов или выполнения редиректов.

Хотя Results API в большей степени предназначено для использования в конечных точках ASP.NET Core, те же методы могут применяться для отправки ответа и в обычных компонентах middleware. Например:

var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.Run(async context =>
{
    await Results.Text("Hello ASP.NET Core").ExecuteAsync(context);
});

app.Run();