Форматирование данных отклика в веб-API ASP.NET Core

ASP.NET Core MVC поддерживает форматирование данных ответа, используя указанные форматы или в ответ на запрос клиента.

Результаты действий для конкретного формата

Некоторые типы результатов действий характерны для определенного формата, например JsonResult и ContentResult. Действия могут возвращать результаты, которые всегда используют указанный формат, игнорируя запрос клиента для другого формата. Например, возвращая возвращаемые данные в формате JSON и возвращая JsonResult ContentResult возвращаемые строковые данные обычного текста.

Действие не должно возвращать данные конкретного типа. ASP.NET Core поддерживает любое возвращаемое значение объекта. Результаты действий, возвращающих объекты, которые не IActionResult являются типами, сериализуются с помощью соответствующей IOutputFormatter реализации. Дополнительные сведения см. в разделе "Типы возвращаемых действий контроллера" в веб-API ASP.NET Core.

По умолчанию встроенный вспомогательный метод ControllerBase.Ok возвращает данные в формате JSON:

[HttpGet]
public IActionResult Get()
    => Ok(_todoItemStore.GetList());

Пример кода возвращает список элементов todo. С помощью средств разработчика браузера F12 или http-repl с предыдущим кодом отображается следующее:

• Заголовок ответа, содержащий тип контента: application/json; charset=utf-8
• Заголовки запроса. Например, заголовок Accept. Приведенный выше код игнорирует заголовок Accept.

Чтобы возвратить данные в формате обычного текста, используйте ContentResult и вспомогательный метод Content:

[HttpGet("Version")]
public ContentResult GetVersion()
    => Content("v1.0.0");

В приведенном выше коде возвращаемым Content-Type является text/plain.

Для действий с несколькими возвращаемыми типами возвращается значение IActionResult. Например, при возврате различных кодов состояния HTTP в зависимости от результата операции.

Согласование содержимого

Согласование содержимого происходит, когда клиент задает заголовок Accept. Для ASP.NET Core по умолчанию используется формат JSON. Согласование содержимого:

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

при возврате типа модели возвращаемым типом является ObjectResult.

Следующий метод действия использует вспомогательные методы Ok и NotFound:

[HttpGet("{id:long}")]
public IActionResult GetById(long id)
{
    var todo = _todoItemStore.GetById(id);

    if (todo is null)
    {
        return NotFound();
    }

    return Ok(todo);
}

По умолчанию ASP.NET Core поддерживает следующие типы носителей:

• application/json
• text/json
• text/plain

Такие средства, как Fiddler или http-repl , могут задать Accept заголовок запроса, чтобы указать формат возврата. Если заголовок Accept содержит тип, который поддерживается сервером, возвращается этот тип. Сведения о добавлении дополнительных форматировщиков приведены в следующем разделе.

Действия контроллера могут возвращать POCO (простые объекты CLR). При возвращении POCO среда выполнения автоматически создает ObjectResult, который генерирует оболочку объекта. Клиент получает отформатированный сериализованный объект. Если возвращаемый объект имеет значение null, возвращается ответ 204 No Content.

В следующем примере возвращается тип объекта:

[HttpGet("{id:long}")]
public TodoItem? GetById(long id)
    => _todoItemStore.GetById(id);

В приведенном выше коде запрос допустимого элемента todo возвращает 200 OK ответ. Запрос недопустимого элемента todo возвращает 204 No Content ответ.

Заголовок Accept

Согласование содержимого выполняется только при наличии в запросе заголовка Accept. Если запрос содержит заголовок Accept, ASP.NET Core:

• перечисляет типы мультимедиа в заголовке Accept в порядке предпочтения;
• пытается найти форматировщик, который может создать ответ в одном из указанных форматов.

Если форматировщик, который может удовлетворить запрос клиента, не найден, ASP.NET Core:

• Возвращает значение 406 Not Acceptable , если MvcOptions.ReturnHttpNotAcceptable задано значение true, или -
• пытается найти первый форматировщик, который может создать ответ.

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

• Для сериализации ответа используется первый форматировщик, который может работать с объектом.
• Согласование не выполняется. Сервер определяет возвращаемый формат.

Если заголовок Accept содержит */*, он игнорируется, если только RespectBrowserAcceptHeader не имеет значение true в MvcOptions.

Браузеры и согласование содержимого

В отличие от обычных клиентов API, веб-браузеры предоставляют заголовки Accept. Веб-браузеры указывают множество форматов, включая подстановочные знаки. Если платформа обнаруживает, что запрос поступает из браузера, по умолчанию выполняется следующее:

• Заголовок Accept игнорируется.
• Содержимое возвращается в формате JSON, если не указано иначе.

Этот подход обеспечивает более согласованный интерфейс в браузерах при использовании API.

Чтобы настроить приложение для соблюдения заголовков браузера, задайте RespectBrowserAcceptHeader для свойства trueзначение :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(options =>
{
    options.RespectBrowserAcceptHeader = true;
});

Настройка форматировщиков

Приложения, которые должны поддерживать дополнительные форматы, могут добавлять соответствующие пакеты NuGet и настраивать поддержку. Существуют отдельные модули форматирования для ввода и вывода. Форматировщики ввода используются привязкой модели. Форматировщики вывода используются для форматирования ответов. Сведения о создании пользовательского форматировщика см. в статье Пользовательские модули форматирования для веб-API в ASP.NET Core.

Добавление поддержки формата XML

Чтобы настроить xml-форматировщики, реализованные с помощью , XmlSerializerвызов:AddXmlSerializerFormatters

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .AddXmlSerializerFormatters();

При использовании приведенного выше кода методы контроллера возвращают соответствующий формат на основе заголовка Accept запроса.

Настройка System.Text.Jsonформатировщиков на основе

Чтобы настроить функции для System.Text.Jsonформатировщиков на основе, используйте Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Следующий выделенный код настраивает форматирование PascalCase вместо форматирования верблюдьего Регистра по умолчанию:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.PropertyNamingPolicy = null;
    });

Чтобы настроить параметры сериализации выходных данных для определенных действий, используйте JsonResult. Например:

[HttpGet]
public IActionResult Get() 
    => new JsonResult(
        _todoItemStore.GetList(),
        new JsonSerializerOptions { PropertyNamingPolicy = null });

Добавление Newtonsoft.Jsonподдержки формата JSON на основе

Используются System.Text.Jsonформатировщики JSON по умолчанию. Чтобы использовать Newtonsoft.Jsonсредства форматирования на основе, установите Microsoft.AspNetCore.Mvc.NewtonsoftJson пакет NuGet и настройте его в Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .AddNewtonsoftJson();

В приведенном выше коде вызов AddNewtonsoftJson настраивает следующие функции веб-API, MVC и Razor Pages для использования Newtonsoft.Json:

• Методы форматирования входных и выходных данных, которые считывают и записывают JSON
• JsonResult
• Исправление JSON
• IJsonHelper
• TempData

Возможно, некоторые функции не будут оптимально работать с форматировщиками на основе System.Text.Json и будут требовать ссылки на форматировщики на основе Newtonsoft.Json. Продолжайте использовать Newtonsoft.Jsonсредства форматирования на основе, когда приложение:

• Использует атрибут Newtonsoft.Json. Например, [JsonProperty] или [JsonIgnore].
• Настраивает параметры сериализации.
• Зависит от функций, предоставляемых Newtonsoft.Json.

Чтобы настроить функции для Newtonsoft.Jsonформатировщиков на основе, используйте SerializerSettingsследующую команду:

builder.Services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.ContractResolver = new DefaultContractResolver();
    });

Чтобы настроить параметры сериализации выходных данных для определенных действий, используйте JsonResult. Например:

[HttpGet]
public IActionResult GetNewtonsoftJson()
    => new JsonResult(
        _todoItemStore.GetList(),
        new JsonSerializerSettings { ContractResolver = new DefaultContractResolver() });

Формат ProblemDetails и ValidationProblemDetails ответы

Для создания ProblemDetails ответа вызывается ControllerBase.Problem следующий метод действия:

[HttpGet("Error")]
public IActionResult GetError()
    => Problem("Something went wrong.");

ProblemDetails Ответ всегда верблюдю Регистр, даже если приложение задает формат PascalCase. ProblemDetailsследует RFC 7807, который задает нижний регистр.

[ApiController] Если атрибут применяется к классу контроллера, контроллер создает ValidationProblemDetails ответ при сбое проверки модели. Этот ответ содержит словарь, который использует имена свойств модели в качестве ключей ошибок без изменений. Например, следующая модель включает одно свойство, требующее проверки:

public class SampleModel
{
    [Range(1, 10)]
    public int Value { get; set; }
}

По умолчанию ValidationProblemDetails ответ, возвращаемый, если Value свойство недопустимо, использует ключ Valueошибки, как показано в следующем примере:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-00000000000000000000000000000000-000000000000000-00",
  "errors": {
    "Value": [
      "The field Value must be between 1 and 10."
    ]
  }
}

Чтобы отформатировать имена свойств, используемые в качестве ключей IMetadataDetailsProvider ошибок, добавьте реализацию в коллекцию MvcOptions.ModelMetadataDetailsProviders . В следующем примере добавляется System.Text.Jsonреализация на основе, SystemTextJsonValidationMetadataProviderкоторая форматирует имена свойств как верблюдю по умолчанию:

builder.Services.AddControllers();

builder.Services.Configure<MvcOptions>(options =>
{
    options.ModelMetadataDetailsProviders.Add(
        new SystemTextJsonValidationMetadataProvider());
});

SystemTextJsonValidationMetadataProvider также принимает реализацию JsonNamingPolicy в конструкторе, которая задает настраиваемую политику именования для форматирования имен свойств.

Чтобы задать настраиваемое имя свойства в модели, используйте атрибут [JsonPropertyName] для свойства:

public class SampleModel
{
    [Range(1, 10)]
    [JsonPropertyName("sampleValue")]
    public int Value { get; set; }
}

Ответ, ValidationProblemDetails возвращаемый для предыдущей модели, если Value свойство недопустимо использует ключ sampleValueошибки, как показано в следующем примере:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-00000000000000000000000000000000-000000000000000-00",
  "errors": {
    "sampleValue": [
      "The field Value must be between 1 and 10."
    ]
  }
}

Чтобы отформатировать ValidationProblemDetails ответ, используйтеNewtonsoft.JsonNewtonsoftJsonValidationMetadataProvider:

builder.Services.AddControllers()
    .AddNewtonsoftJson();

builder.Services.Configure<MvcOptions>(options =>
{
    options.ModelMetadataDetailsProviders.Add(
        new NewtonsoftJsonValidationMetadataProvider());
});

По умолчанию форматирует имена свойств как верблюдю NewtonsoftJsonValidationMetadataProvider . NewtonsoftJsonValidationMetadataProvider также принимает реализацию NamingPolicy в конструкторе, которая задает настраиваемую политику именования для форматирования имен свойств. Чтобы задать пользовательское имя свойства в модели, используйте [JsonProperty] атрибут.

Указание формата

Чтобы ограничить форматы ответа, примените фильтр [Produces]. Как и большинство фильтров, [Produces] можно применить к действию, контроллеру или глобальной области.

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoItemsController : ControllerBase

Предыдущий фильтр [Produces]:

• Принудительно принуждает все действия контроллера возвращать ответы в формате JSON для POCOs (обычные старые объекты CLR) или ObjectResult их производных типов.
• Возвращает ответы в формате JSON, даже если настроены другие модули форматирования, а клиент задает другой формат.

Дополнительные сведения см. в статье Фильтры в ASP.NET Core.

Специальные форматировщики

Встроенные модули форматирования реализуют некоторые специальные возможности. По умолчанию типы возвращаемых значений string форматируются как text/plain (text/html, если того требует заголовок Accept). Это поведение можно отключить, удалив StringOutputFormatter. Форматировщики удаляются в Program.cs. Действия, у которых типом возвращаемого объекта является модель, возвращают ответ 204 No Content при возврате значения null. Это поведение можно отключить, удалив HttpNoContentOutputFormatter. Приведенный ниже код удаляет StringOutputFormatter и HttpNoContentOutputFormatter.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(options =>
{
    // using Microsoft.AspNetCore.Mvc.Formatters;
    options.OutputFormatters.RemoveType<StringOutputFormatter>();
    options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
});

Без StringOutputFormatter, встроенный модуль форматирования JSON форматирует типы возвращаемого значения string. Если встроенный модуль форматирования JSON удален и доступен модуль форматирования XML, то типы возвращаемого значения string форматирует модуль форматирования XML. В противном случае, string типы возвращаемого значения возвращают 406 Not Acceptable.

Без HttpNoContentOutputFormatter объекты со значением null форматируются с помощью настроенного модуля форматирования. Например:

• Форматировщик JSON возвращает ответ с текстом null.
• Форматировщик XML возвращает пустой XML-элемент с атрибутом xsi:nil="true".

Сопоставления URL-адреса для формата ответа

Клиенты могут запрашивать определенный формат как часть URL-адреса, например:

• В строке запроса или в части пути.
• С использованием расширения файла конкретного формата, такого как XML или JSON.

Сопоставление из пути запроса должно быть указано в маршруте, используемом API. Например:

[ApiController]
[Route("api/[controller]")]
[FormatFilter]
public class TodoItemsController : ControllerBase
{
    private readonly TodoItemStore _todoItemStore;

    public TodoItemsController(TodoItemStore todoItemStore)
        => _todoItemStore = todoItemStore;

    [HttpGet("{id:long}.{format?}")]
    public TodoItem? GetById(long id)
        => _todoItemStore.GetById(id);

Предыдущий маршрут позволяет указать запрошенный формат с помощью дополнительного расширения файла. Атрибут [FormatFilter] проверяет наличие значения формата в RouteData и сопоставляет этот формат ответа с соответствующим форматировщиком при создании ответа.

Маршрут	Форматировщик
/api/todoitems/5	Модуль форматирования вывода по умолчанию
/api/todoitems/5.json	Модуль форматирования JSON (если настроен)
/api/todoitems/5.xml	Модуль форматирования XML (если настроен)

Полиморфная десериализация

Встроенные функции предоставляют ограниченный диапазон полиморфной сериализации, но совсем не поддерживают десериализацию. Для десериализации требуется настраиваемый преобразователь. Полный пример полиморфной десериализации см. в разделе "Полиморфная десериализация ".

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

• Просмотреть или скачать образец кода (описание загрузки)