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 zwracanie JsonResult zwracanych danych w formacie JSON i zwraca zwracanie ContentResult danych ciągów w formacie zwykłego tekstu.

Akcja nie jest wymagana do zwrócenia żadnego określonego typu. ASP.NET Core obsługuje dowolną wartość zwracaną przez obiekt. Wyniki akcji, które zwracają obiekty, które nie IActionResult są typami, są serializowane przy użyciu odpowiedniej IOutputFormatter implementacji. Aby uzyskać więcej informacji, zobacz Zwracanie typów akcji kontrolera w interfejsie API sieci Web platformy ASP.NET Core.

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 jest wyświetlany:

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

Aby zwrócić dane sformatowane w postaci zwykłego tekstu, użyj polecenia ContentResult i Content pomocnika:

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

W poprzednim kodzie Content-Type zwracany jest 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 Ok metod i NotFound pomocnika:

[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 POC (zwykłe stare obiekty CLR). Po powrocie poco środowisko uruchomieniowe automatycznie tworzy ObjectResult obiekt, który opakowuje obiekt. Klient pobiera sformatowany obiekt serializowany. Jeśli zwracany obiekt to null, 204 No Content zwracana jest odpowiedź.

Poniższy przykład zwraca typ obiektu:

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

W poprzednim kodzie żądanie prawidłowego elementu zadania do wykonania zwraca 200 OK odpowiedź. Żądanie nieprawidłowego elementu todo zwraca 204 No Content odpowiedź.

Nagłówek Accept

Negocjowanie zawartości odbywa się po Accept wyświetleniu nagłówka w żądaniu. Gdy żądanie zawiera nagłówek akceptowania, ASP.NET Core:

• Wylicza typy multimedió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 wartość , jeśli MvcOptions.ReturnHttpNotAcceptable ustawiono wartość 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 Accept pojawi się żaden nagłówek:

• 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.

Jeśli nagłówek Accept zawiera */*wartość , nagłówek jest ignorowany, chyba że RespectBrowserAcceptHeader ustawiono wartość true dla elementu MvcOptions.

Przeglądarki i negocjacje zawartości

W przeciwieństwie do typowych klientów interfejsu API przeglądarki internetowe dostarczają 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 w formacie JSON, chyba że skonfigurowano inaczej.

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

Aby skonfigurować aplikację w celu przestrzegania 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 powiązanie modelu. Formatery danych wyjściowych służą do formatowania odpowiedzi. Aby uzyskać informacje na temat tworzenia niestandardowego modułu formatującego, zobacz Niestandardowe formatery.

Obsługa dodawania 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 System.Text.Jsonformaterów opartych na protokole

Aby skonfigurować funkcje dla formaterów opartych na System.Text.Jsonprotokole , użyj polecenia 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. Na przykład:

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

Obsługa Newtonsoft.Jsonformatu JSON opartego na dodawaniu

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

var builder = WebApplication.CreateBuilder(args);

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

W poprzednim kodzie wywołanie AddNewtonsoftJson umożliwia skonfigurowanie następujących funkcji internetowego interfejsu API, WZORCA MVC i Razor stron do użycia Newtonsoft.Json:

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

Niektóre funkcje mogą nie działać dobrze z formaterami System.Text.Jsonopartymi na protokole i wymagają odwołania do Newtonsoft.Jsonformaterów opartych na protokole. Kontynuuj korzystanie z formaterów opartych na Newtonsoft.Jsonaplikacjach:

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

Aby skonfigurować funkcje dla formaterów opartych na Newtonsoft.Jsonprotokole , użyj polecenia 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. Na przykład:

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

Formatowanie ProblemDetails i ValidationProblemDetails odpowiedzi

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

[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ź, gdy walidacja modelu zakończy się niepowodzeniemValidationProblemDetails. Ta odpowiedź zawiera słownik, który używa nazw właściwości modelu jako kluczy błędów, bez zmian. 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 Value właściwość jest nieprawidłowa, ValidationProblemDetails 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ę IMetadataDetailsProvider MvcOptions.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 Akceptuje również implementację JsonNamingPolicy w konstruktorze, który 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 konstruktorze, który 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 [JsonProperty] .

Określanie formatu

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

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

Powyższy [Produces] filtr:

• Wymusza wszystkie akcje w kontrolerze w celu zwrócenia odpowiedzi sformatowanych w formacie JSON dla obiektów POC (zwykłych starych obiektów CLR) lub ObjectResult 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 wielkości liter

Niektóre specjalne przypadki są implementowane przy użyciu wbudowanych formató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ą zwracany typ obiektu modelu zwracany 204 No Content podczas zwracania nullwartości . 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 string XML zwraca typy. string W przeciwnym razie zwracane typy zwracają wartość 406 Not Acceptable.

HttpNoContentOutputFormatterBez obiektów null są formatowane przy użyciu skonfigurowanego formatowania. Na przykład:

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

Mapowania adresów URL 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 ze ścieżki żądania należy określić w trasie używanej przez interfejs API. Na 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 istnienie wartości formatu w RouteData obiekcie i mapuje format odpowiedzi na odpowiedni formater po utworzeniu odpowiedzi.

Marszruta	Program formatujący
/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 Deserializacji polimorficznej, aby uzyskać pełną próbkę deserializacji polimorficznej.

Dodatkowe zasoby

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