Статические классы Results и TypedResults в ASP.NET Core. Отправка текста и JSON

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

Метод Content класса Results

Метод Content() отправляет пользователю строку, позволяя, при этом задавать кодировку текста. Метод имеет три перегруженные версии:

public static IResult Content (string? content, string? contentType = default, Encoding? contentEncoding = default, int? statusCode = default);

public static IResult Content (string? content, string? contentType, Encoding? contentEncoding);

public static IResult Content (string? content, MediaTypeHeaderValue contentType);

Например, рассмотрим использование метода Content:

app.MapGet("/", () => Results.Content("Привет, мир!"));

здесь мы воспользовались первой версией метода и, при этом, параметры contentType, encoding и statusCode оставили со значениями по умолчанию. Напомню, что раннее, без использования классов Results или TypedResults мы бы столкнулись с проблемой кодировки символов. В данном же случае, сервер вернет нам следующий ответ:

то есть, по умолчанию, значение заголовка Content-Type принимается как "text/plain; charset=utf-8", что избавляет нас лишний раз работать вручную с заголовками ответа.

Метод Text класса Results

Метод Text() работает аналогичным образом с Content() и различается, по сути, только одной версией метода, которая принимает в качестве текста структуру ReadOnlySpan<byte>. В классе Results этот метод выглядит следующим образом:

public static IResult Text (ReadOnlySpan<byte> utf8Content, string? contentType = default, int? statusCode = default);

Метод Json класса Results

Этот метод позволяет сериализовать объект в JSON и отправить её пользователю. Метод имеет две версии:

public static IResult Json (object? data, JsonSerializerOptions? options = default, string? contentType = default, int? statusCode = default);

public static IResult Json<TValue> (TValue? data, JsonSerializerOptions? options = default, string? contentType = default, int? statusCode = default);

Пример использования метода:

app.MapGet("/", () => Results.Json(new {Name = "Джон", Surname = "Доу", Age = 35 }));

Здесь мы использовали только первый параметр метода Json(), а остальные оставили со значениями по умолчанию. В результате получим такой ответ сервера:

Если необходимо использовать какие-то дополнительные настройки сериализации в JSON, то можно вызвать метод следующим образом:

app.MapGet("/", () => Results.Json(new { Name = "Джон", Surname = "Доу", Age = 35 },
     new System.Text.Json.JsonSerializerOptions()
     {
         AllowTrailingCommas = true,
         PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
         WriteIndented = true,
     }));

Часто, формат JSON в ответе клиенту используется для отправки сообщений об ошибке. В этом случае, мы можем передать статусный код HTTP:

app.MapGet("/", () => Results.Json(new { Name = "Джон", Surname = "Доу", Age = 35 }, 
    null, 
    null, 
    400));

Методы Content, Text и Json в классе TypedResults

Действие методов Content, Text и Json в классе TypedResults аналогично действию этих же методов в классе Results, но, при этом, TypedResults возвращает типизированные объекты. Так, в результате выполнения метода Content возвращается объект ContentHttpResult со следующими свойствами:

При использовании метода Text может возвращаться два типа ответов: первый — тот же ContentHttpResult, второй —  Utf8ContentHttpResult если используется версия метода в котором текст задается в виде ReadOnlySpan<byte>.

При использовании метода Json TypedResult возвращает объект типа JsonHttpResult<TValue>, который имеет следующие свойства:

Итого

Методы Content, Text и Json классов Results и TypedResults позволяют отправлять пользователю текстовое содержимое. При этом, метод Json сериализует переданный в параметрах метода объект в формат Json и отправляет его в ответе пользователю. Все три метода по умолчанию используют кодировку UTF-8 для заголовка Cotent-Type, что несколько упрощает нам работу, например, при отправке текстовых ответов, содержащих кириллицу.