Formatowanie danych odpowiedzi w internetowym interfejsie API platformy ASP.NET Core

ASP.NET Core MVC obsługuje formatowanie danych odpowiedzi przy użyciu określonych formatów lub w odpowiedzi na żądanie klienta.

Wyniki akcji specyficzne dla formatu

Niektóre typy wyników akcji są specyficzne dla określonego formatu, takiego jak JsonResult i ContentResult. Akcje mogą zwracać wyniki, które zawsze używają określonego formatu, ignorując żądanie klienta dla innego formatu. Na przykład zwrócenie JsonResult zwraca dane sformatowane w formacie JSON, a zwrócenie ContentResult zwraca dane ciągów sformatowane w formacie zwykłego tekstu.

Nie jest wymagane, aby akcja zwracała konkretny typ. ASP.NET Core obsługuje dowolną wartość zwracaną przez obiekt. Wyniki akcji, które zwracają obiekty niebędące typami IActionResult, są serializowane przy użyciu odpowiedniej implementacji IOutputFormatter. Aby uzyskać więcej informacji, zobacz Typy zwracane przez akcje kontrolera w ASP.NET Core Web API.

Domyślnie wbudowana metoda ControllerBase.Ok pomocnika zwraca dane w formacie JSON:

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

Przykładowy kod zwraca listę zadań do wykonania. Za pomocą narzędzi deweloperskich przeglądarki F12 lub http-repl z poprzednim kodem wyświetla się:

• Nagłówek odpowiedzi zawierający typ zawartości:application/json; charset=utf-8.
• Nagłówki żądania. Na przykład nagłówka Accept. Nagłówek Accept jest ignorowany przez poprzedni kod.

Aby zwrócić dane sformatowane w postaci zwykłego tekstu, użyj ContentResult oraz funkcji pomocniczej Content.

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

W poprzednim kodzie zwracana wartość Content-Type to text/plain.

W przypadku akcji z wieloma typami zwracanymi zwróć wartość IActionResult. Na przykład podczas zwracania różnych kodów stanu HTTP na podstawie wyniku operacji.

Negocjowanie zawartości

Negocjowanie zawartości występuje, gdy klient określa nagłówek "Accept". Domyślny format używany przez ASP.NET Core to JSON. Negocjowanie zawartości jest:

• Zaimplementowane przez program ObjectResult.
• Wbudowane wyniki akcji specyficznej dla kodu stanu zwrócone z metod pomocnika. Metody pomocnika wyników akcji są oparte na ObjectResult.

Gdy zwracany jest typ modelu, zwracany typ to ObjectResult.

Poniższa metoda akcji używa metod pomocniczych Ok i NotFound.

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

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

    return Ok(todo);
}

Domyślnie ASP.NET Core obsługuje następujące typy multimediów:

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

Narzędzia, takie jak Fiddler lub http-repl , mogą ustawić Accept nagłówek żądania, aby określić format zwracany. Accept Gdy nagłówek zawiera typ, który obsługuje serwer, zwracany jest ten typ. W następnej sekcji pokazano, jak dodać dodatkowe formatery.

Akcje kontrolera mogą zwracać obiekty POCO (zwykłe, proste obiekty CLR). Gdy zwracany jest POCO, środowisko uruchomieniowe automatycznie tworzy ObjectResult, które opakowuje obiekt. Klient pobiera sformatowany obiekt serializowany. Jeśli zwracany obiekt to null, odpowiedź 204 No Content jest zwracana.

Poniższy przykład zwraca typ obiektu:

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

W poprzednim kodzie żądanie ważnego elementu Todo zwraca odpowiedź 200 OK. Żądanie nieprawidłowego elementu todo zwraca 204 No Content odpowiedź.

Nagłówek Accept

Negocjacja zawartości odbywa się, gdy w żądaniu pojawia się nagłówek Accept. Gdy żądanie zawiera nagłówek 'Accept', ASP.NET Core:

• Wylicza typy mediów w nagłówku 'Accept' w kolejności preferencji.
• Próbuje znaleźć formater, który może wygenerować odpowiedź w jednym z określonych formatów.

Jeśli nie znaleziono programu formatującego, który może spełnić żądanie klienta, ASP.NET Core:

• Zwraca 406 Not Acceptable, jeśli MvcOptions.ReturnHttpNotAcceptable ustawiono na true, lub —
• Próbuje znaleźć pierwszy formater, który może wygenerować odpowiedź.

Jeśli dla żądanego formatu nie skonfigurowano żadnego formatowania, zostanie użyty pierwszy formater, który może sformatować obiekt. Jeśli w żądaniu nie pojawi się żaden nagłówek Accept.

• Pierwszy formater, który może obsłużyć obiekt, jest używany do serializacji odpowiedzi.
• Nie ma żadnych negocjacji. Serwer określa, jaki format ma być zwracany.

pl-PL: Jeśli nagłówek Accept zawiera */*, jest ignorowany, chyba że RespectBrowserAcceptHeader jest ustawione na true dla MvcOptions.

Przeglądarki i negocjacje zawartości

W przeciwieństwie do typowych klientów API, przeglądarki internetowe przekazują Accept nagłówki. Przeglądarki sieci Web określają wiele formatów, w tym symbole wieloznaczne. Domyślnie gdy platforma wykryje, że żądanie pochodzi z przeglądarki:

• Nagłówek Accept jest ignorowany.
• Zawartość jest zwracana przy użyciu pierwszego zarejestrowanego formatera danych wyjściowych, który może obsługiwać typ odpowiedzi, chyba że skonfigurowano inaczej.

Takie podejście zapewnia bardziej spójne doświadczenie w przeglądarkach podczas korzystania z API.

Aby skonfigurować aplikację w celu respektowania nagłówków akceptowanych przez przeglądarkę, ustaw RespectBrowserAcceptHeader właściwość na true:

var builder = WebApplication.CreateBuilder(args);

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

Konfigurowanie formaterów

Aplikacje, które muszą obsługiwać dodatkowe formaty, mogą dodawać odpowiednie pakiety NuGet i konfigurować obsługę. Istnieją oddzielne formatery dla danych wejściowych i wyjściowych. Formatery danych wejściowych są używane przez Model Binding. Formatery danych wyjściowych służą do formatowania odpowiedzi. Aby uzyskać informacje na temat tworzenia niestandardowego modułu formatującego, zobacz Niestandardowe formatery.

Wsparcie dla formatu XML

Aby skonfigurować formatery XML zaimplementowane przy użyciu metody XmlSerializer, wywołaj metodę AddXmlSerializerFormatters:

var builder = WebApplication.CreateBuilder(args);

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

W przypadku używania poprzedniego kodu metody kontrolera zwracają odpowiedni format na podstawie nagłówka Accept żądania.

Konfigurowanie formaterów bazujących na System.Text.Json

Aby skonfigurować funkcje dla formaterów opartych na System.Text.Json, użyj Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Poniższy wyróżniony kod konfiguruje formatowanie PascalCase zamiast domyślnego formatowania camelCase:

var builder = WebApplication.CreateBuilder(args);

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

Aby skonfigurować opcje serializacji danych wyjściowych dla określonych akcji, użyj polecenia JsonResult. Przykład:

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

Dodaj obsługę formatu JSON opartego na Newtonsoft.Json.

Domyślne formatery JSON używają elementu System.Text.Json. Aby użyć formaterów opartych na Newtonsoft.Json, zainstaluj pakiet NuGet Microsoft.AspNetCore.Mvc.NewtonsoftJson i skonfiguruj go w Program.cs.

var builder = WebApplication.CreateBuilder(args);

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

W poprzednim kodzie wywołanie AddNewtonsoftJson konfiguruje następujące funkcje Web API, MVC i Razor Pages do użycia Newtonsoft.Json:

• Formatery wejściowe i wyjściowe odczytujące i zapisujące dane JSON
• JsonResult
• JSON Patch
• IJsonHelper
• TempData

Niektóre funkcje mogą nie działać dobrze z formaterami System.Text.Json i wymagają odwołania do formaterów Newtonsoft.Json. Kontynuuj korzystanie z formaterów opartych na Newtonsoft.Json, gdy aplikacja:

• Używa Newtonsoft.Json atrybutów. Na przykład: [JsonProperty] lub [JsonIgnore].
• Dostosowuje ustawienia serializacji.
• Opiera się na funkcjach, które Newtonsoft.Json udostępnia.

Aby skonfigurować funkcje dla formaterów opartych na Newtonsoft.Json, użyj SerializerSettings:

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

Aby skonfigurować opcje serializacji danych wyjściowych dla określonych akcji, użyj polecenia JsonResult. Przykład:

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

Sformatuj ProblemDetails i ValidationProblemDetails odpowiedzi

Następująca akcja wywołuje ControllerBase.Problem w celu utworzenia odpowiedzi ProblemDetails:

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

ProblemDetails Odpowiedź jest zawsze camelCase, nawet jeśli aplikacja ustawia format na PascalCase. ProblemDetails program jest zgodny z specyfikacją RFC 7807, która określa małe litery.

Po zastosowaniu atrybutu [ApiController] do klasy kontrolera kontroler tworzy odpowiedź ValidationProblemDetails, gdy Walidacja Modelu zakończy się niepowodzeniem. Ta odpowiedź zawiera słownik, który bez zmian używa nazw właściwości modelu jako kluczy błędów. Na przykład poniższy model zawiera jedną właściwość, która wymaga weryfikacji:

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

Domyślnie odpowiedź zwracana, gdy właściwość Value jest nieprawidłowa, używa klucza błędu Value, jak pokazano w poniższym przykładzie:

{
  "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."
    ]
  }
}

Aby sformatować nazwy właściwości używane jako klucze błędów, dodaj implementację IMetadataDetailsProviderMvcOptions.ModelMetadataDetailsProviders do kolekcji. W poniższym przykładzie dodano implementację opartą na metodzie System.Text.Json, SystemTextJsonValidationMetadataProviderktóra domyślnie formatuje nazwy właściwości jako camelCase:

builder.Services.AddControllers();

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

SystemTextJsonValidationMetadataProvider w swoim konstruktorze akceptuje także implementację JsonNamingPolicy, która określa niestandardowe zasady nazewnictwa do formatowania nazw właściwości.

Aby ustawić niestandardową nazwę właściwości w modelu, użyj atrybutu [JsonPropertyName] we właściwości :

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

ValidationProblemDetails Odpowiedź zwrócona dla poprzedniego modelu, gdy Value właściwość jest nieprawidłowa, używa klucza błędu sampleValue, jak pokazano w poniższym przykładzie:

{
  "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."
    ]
  }
}

Aby sformatować ValidationProblemDetails odpowiedź przy użyciu polecenia Newtonsoft.Json, użyj polecenia NewtonsoftJsonValidationMetadataProvider:

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

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

Domyślnie NewtonsoftJsonValidationMetadataProvider formatuje nazwy właściwości jako camelCase. NewtonsoftJsonValidationMetadataProvider akceptuje również implementację NamingPolicy w jego konstruktorze, co pozwala określić własne zasady nazewnictwa dla formatowania nazw właściwości. Aby ustawić niestandardową nazwę właściwości w modelu, użyj atrybutu [JsonProperty] .

Określanie formatu

Aby ograniczyć formaty odpowiedzi, zastosuj [Produces] filtr. Podobnie jak większość filtrów, [Produces] można zastosować na poziomie akcji, kontrolera lub poziomu globalnego.

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

Powyższy [Produces] filtr:

• Wymusza, aby wszystkie akcje w kontrolerze zwracały odpowiedzi sformatowane w formacie JSON dla obiektów typu POCO (zwyczajnych obiektów CLR) lub ObjectResult i jego typów pochodnych.
• Zwracanie odpowiedzi sformatowanych w formacie JSON, nawet jeśli inne formatatory są skonfigurowane, a klient określa inny format.

Aby uzyskać więcej informacji, zobacz Filtry.

Specjalne formatery do wyjątkowych przypadków

Niektóre specjalne przypadki są implementowane przy użyciu wbudowanych formaterów. Domyślnie string typy zwracane są formatowane jako tekst/zwykły (tekst/html , jeśli jest to wymagane za pośrednictwem nagłówka Accept ). To zachowanie można usunąć, usuwając element StringOutputFormatter. Formatery są usuwane w pliku Program.cs. Akcje, które mają typ zwracanego obiektu modelu, zwracają 204 No Content, kiedy zwracana jest null. To zachowanie można usunąć, usuwając element HttpNoContentOutputFormatter. Poniższy kod usuwa elementy StringOutputFormatter i HttpNoContentOutputFormatter.

var builder = WebApplication.CreateBuilder(args);

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

StringOutputFormatterBez wbudowanego formatu string formatującego JSON zwraca typy. Jeśli wbudowany formater JSON zostanie usunięty, a formater XML jest dostępny, formater XML formatuje typy zwracane jako string. string W przeciwnym razie zwracane typy zwracają wartość 406 Not Acceptable.

Bez HttpNoContentOutputFormatter obiekty null są formatowane przy użyciu skonfigurowanego formatera. Przykład:

• Formater JSON zwraca odpowiedź z treścią null.
• Funkcja formatowania XML zwraca pusty element XML z zestawem atrybutów xsi:nil="true" .

Mapowanie adresów URL dla formatu odpowiedzi

Klienci mogą zażądać określonego formatu jako części adresu URL, na przykład:

• W ciągu zapytania lub w części ścieżki.
• Za pomocą rozszerzenia pliku specyficznego dla formatu, takiego jak .xml lub .json.

Mapowanie ścieżki żądania należy określić w trasie, z której korzysta interfejs API. Przykład:

[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);

Poprzednia trasa umożliwia określenie żądanego formatu przy użyciu opcjonalnego rozszerzenia pliku. Atrybut [FormatFilter] sprawdza, czy wartość formatu istnieje w RouteData i mapuje format odpowiedzi na odpowiedni formatator, gdy odpowiedź jest tworzona.

Route	Formatter
/api/todoitems/5	Domyślny formater danych wyjściowych
/api/todoitems/5.json	Formater JSON (jeśli został skonfigurowany)
/api/todoitems/5.xml	Formater XML (jeśli został skonfigurowany)

Deserializacja polimorficzna

Wbudowane funkcje zapewniają ograniczony zakres serializacji polimorficznej, ale w ogóle nie obsługują deserializacji. Deserializacja wymaga niestandardowego konwertera. Zobacz deserializacja polimorficzna, aby uzyskać pełną próbkę deserializacji polimorficznej.

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)