Formátování dat odpovědí ve webovém rozhraní API ASP.NET Core

ASP.NET Core MVC podporuje formátování dat odpovědi pomocí zadaných formátů nebo v reakci na požadavek klienta.

Výsledky akce specifické pro konkrétní formát

Některé typy výsledků akce jsou specifické pro určitý formát, například JsonResult a ContentResult. Akce můžou vracet výsledky, které vždy používají zadaný formát a ignorují požadavek klienta na jiný formát. Například vrácení JsonResult vrátí data ve formátu JSON a vrácení vrátí ContentResult řetězcová data ve formátu prostého textu.

Akce není nutná k vrácení žádného konkrétního typu. ASP.NET Core podporuje libovolnou vrácenou hodnotu objektu. Výsledky z akcí, které vracejí objekty, které nejsou IActionResult typy, jsou serializovány pomocí příslušné IOutputFormatter implementace. Další informace najdete v tématu Návratové typy akcí kontroleru ve webovém rozhraní API ASP.NET Core.

Ve výchozím nastavení integrovaná pomocná metoda ControllerBase.Ok vrací data ve formátu JSON:

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

Vzorový kód vrátí seznam položek úkolů. Pomocí vývojářských nástrojů prohlížeče F12 nebo http-repl s předchozím kódem se zobrazí:

• Hlavička odpovědi obsahující typ obsahu: application/json; charset=utf-8.
• Hlavičky požadavku. Například Accept záhlaví. Hlavička Accept je ignorována předchozím kódem.

Pokud chcete vrátit data ve formátu prostého textu, použijte ContentResult a pomocné rutiny Content :

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

V předchozím kódu je text/plainvrácena Content-Type .

Pro akce s více návratovými typy, vraťte IActionResult. Například při vracení různých stavových kódů HTTP na základě výsledku operace.

Vyjednávání obsahu

Vyjednávání obsahu nastane, když klient určuje hlavičku Accept. Výchozí formát používaný ASP.NET Core je JSON. Vyjednávání obsahu je:

• Implementoval .ObjectResult
• Integrované do výsledků akcí specifických pro stavový kód vrácených z pomocných metod. Pomocné metody výsledků akce jsou založeny na ObjectResult.

Při vrácení typu modelu je ObjectResultnávratový typ .

Následující metoda akce používá Ok NotFound pomocné metody:

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

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

    return Ok(todo);
}

Ve výchozím nastavení ASP.NET Core podporuje následující typy médií:

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

Nástroje, jako je Fiddler nebo http-repl , můžou nastavit hlavičku Accept požadavku tak, aby určila návratový formát. Pokud hlavička Accept obsahuje typ, který server podporuje, vrátí se tento typ. V další části se dozvíte, jak přidat další formátování.

Akce kontroleru můžou vracet objekty POCOs (prosté staré objekty CLR). Při vrácení poco modul runtime automaticky vytvoří ObjectResult objekt, který objekt zabalí. Klient získá formátovaný serializovaný objekt. Pokud je nullvrácen objekt , 204 No Content vrátí se odpověď.

Následující příklad vrátí typ objektu:

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

V předchozím kódu vrátí požadavek na platnou 200 OK položku úkolu odpověď. Požadavek na neplatnou položku úkolu vrátí 204 No Content odpověď.

Hlavička Accept

Vyjednávání obsahu probíhá, když Accept se v požadavku zobrazí záhlaví. Pokud požadavek obsahuje hlavičku accept, ASP.NET Core:

• Vytvoří výčet typů médií v hlavičce accept v pořadí předvoleb.
• Pokusí se najít formátovací modul, který může vytvořit odpověď v jednom ze zadaných formátů.

Pokud se nenajde žádný formátovací modul, který by mohl vyhovět požadavku klienta, ASP.NET Core:

• Vrátí 406 Not Acceptable hodnotu, je-li MvcOptions.ReturnHttpNotAcceptable nastavena na truehodnotu , nebo -
• Pokusí se najít první formátovací modul, který může vytvořit odpověď.

Pokud není pro požadovaný formát nakonfigurovaný žádný formát, použije se první formátovací modul, který může formátovat objekt. Pokud se v požadavku nezobrazí žádná Accept hlavička:

• První formátovací modul, který dokáže zpracovat objekt, se používá k serializaci odpovědi.
• Neprobíhá žádné vyjednávání. Server určuje, jaký formát se má vrátit.

Pokud hlavička Accept obsahuje */*, je hlavička ignorována, pokud RespectBrowserAcceptHeader není nastavena na hodnotu true on MvcOptions.

Prohlížeče a vyjednávání obsahu

Na rozdíl od typických klientů rozhraní API poskytují Accept webové prohlížeče hlavičky. Webové prohlížeče určují mnoho formátů, včetně zástupných znaků. Když rozhraní ve výchozím nastavení zjistí, že požadavek pochází z prohlížeče:

• Záhlaví Accept se ignoruje.
• Obsah se vrátí ve formátu JSON, pokud není nakonfigurovaný jinak.

Tento přístup poskytuje konzistentnější prostředí napříč prohlížeči při využívání rozhraní API.

Pokud chcete nakonfigurovat aplikaci tak, aby respektovala hlavičky přijetí prohlížeče, nastavte RespectBrowserAcceptHeader vlastnost na true:

var builder = WebApplication.CreateBuilder(args);

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

Konfigurace formátovacích souborů

Aplikace, které potřebují podporovat další formáty, můžou přidat příslušné balíčky NuGet a nakonfigurovat podporu. Existují samostatné formátovací moduly pro vstup a výstup. Vstupní formátovací moduly používají vazby modelu. Výstupní formátovací moduly se používají k formátování odpovědí. Informace o vytvoření vlastního formátovače naleznete v tématu Vlastní formátovací moduly.

Přidání podpory formátu XML

Konfigurace formátovacích souborů XML implementovaných pomocí XmlSerializervolání AddXmlSerializerFormatters:

var builder = WebApplication.CreateBuilder(args);

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

Při použití předchozího kódu vrátí metody kontroleru odpovídající formát na základě hlavičky Accept požadavku.

Konfigurace System.Text.Jsonformátovacích souborů založených na

Ke konfiguraci funkcí pro System.Text.Jsonformátovací moduly Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptionszaložené na jazyce . Následující zvýrazněný kód místo výchozího formátování camelCase konfiguruje formátování PascalCase:

var builder = WebApplication.CreateBuilder(args);

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

Chcete-li konfigurovat možnosti serializace výstupu pro konkrétní akce, použijte JsonResult. Příklad:

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

Přidání Newtonsoft.Jsonpodpory formátu JSON založeného na

Výchozí formátovací moduly JSON používají System.Text.Json. Pokud chcete použít Newtonsoft.Jsonformátovací moduly založené na základech, nainstalujte Microsoft.AspNetCore.Mvc.NewtonsoftJson balíček NuGet a nakonfigurujte ho v Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

V předchozím kódu volání AddNewtonsoftJson konfiguruje následující funkce webového rozhraní API, MVC a Razor Pages, které se mají použít Newtonsoft.Json:

• Vstupní a výstupní formátovací moduly, které čtou a zapisují JSON
• JsonResult
• Oprava JSON
• IJsonHelper
• TempData

Některé funkce nemusí dobře fungovat s formátovacími System.Text.Jsonmoduly založenými na nich a vyžadují odkaz na Newtonsoft.Jsonformátovací nástroje. Pokračujte v používání Newtonsoft.Jsonformátovacích metod založených na aplikaci:

• Používá Newtonsoft.Json atributy. Například [JsonProperty] nebo [JsonIgnore].
• Přizpůsobí nastavení serializace.
• Spoléhá na funkce, které Newtonsoft.Json poskytuje.

Ke konfiguraci funkcí pro Newtonsoft.Jsonformátovací moduly SerializerSettingszaložené na :

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

Chcete-li konfigurovat možnosti serializace výstupu pro konkrétní akce, použijte JsonResult. Příklad:

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

Formátování ProblemDetails a ValidationProblemDetails odpovědi

Následující volání metody ControllerBase.Problem akce k vytvoření ProblemDetails odpovědi:

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

ProblemDetails Odpověď je vždy camelCase, i když aplikace nastaví formát na PascalCase. ProblemDetails se řídí dokumentem RFC 7807, který určuje malá písmena.

[ApiController] Když se atribut použije na třídu kontroleru, řadič vytvoří ValidationProblemDetails odpověď, když ověření modelu selže. Tato odpověď obsahuje slovník, který používá názvy vlastností modelu jako chybové klíče beze změny. Následující model například obsahuje jednu vlastnost, která vyžaduje ověření:

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

Ve výchozím nastavení odpověď vrácená, když Value je vlastnost neplatná, ValidationProblemDetails používá kód chyby Value, jak je znázorněno v následujícím příkladu:

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

Chcete-li formátovat názvy vlastností používané jako chybové klíče, přidejte do kolekce implementaci IMetadataDetailsProvider MvcOptions.ModelMetadataDetailsProviders . Následující příklad přidá implementaci založenou System.Text.Jsonna -, SystemTextJsonValidationMetadataProviderkterá ve výchozím nastavení formátuje názvy vlastností jako camelCase:

builder.Services.AddControllers();

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

SystemTextJsonValidationMetadataProvider také přijímá implementaci JsonNamingPolicy v jeho konstruktoru, který určuje vlastní zásady pojmenování pro formátování názvů vlastností.

Pokud chcete nastavit vlastní název vlastnosti v rámci modelu, použijte atribut [JsonPropertyName] pro vlastnost:

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

Odpověď ValidationProblemDetails vrácená pro předchozí model, pokud Value je vlastnost neplatná, používá chybový klíč sampleValue, jak je znázorněno v následujícím příkladu:

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

Chcete-li naformátovat ValidationProblemDetails odpověď pomocí Newtonsoft.Jsonpříkazu , použijte NewtonsoftJsonValidationMetadataProvider:

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

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

Ve výchozím nastavení NewtonsoftJsonValidationMetadataProvider formátuje názvy vlastností jako camelCase. NewtonsoftJsonValidationMetadataProvider také přijímá implementaci NamingPolicy v jeho konstruktoru, který určuje vlastní zásady pojmenování pro formátování názvů vlastností. Pokud chcete nastavit vlastní název vlastnosti v modelu, použijte [JsonProperty] atribut.

Zadání formátu

Chcete-li omezit formáty odpovědí, použijte [Produces] filtr. Podobně jako u většiny filtrů[Produces] je možné použít akce, kontroleru nebo globálního oboru:

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

Předchozí [Produces] filtr:

• Vynutí všechny akce v kontroleru tak, aby vracely odpovědi formátované json pro objekty POCOs (Plain Old CLR) nebo ObjectResult jeho odvozené typy.
• Vrátí odpovědi ve formátu JSON, i když jsou nakonfigurované jiné formátovací moduly a klient určí jiný formát.

Další informace najdete v tématu Filtry.

Speciální formátovací moduly pro velká písmena

Některé speciální případy se implementují pomocí integrovaných formátovacích metod. Ve výchozím nastavení string jsou návratové typy formátované jako text/prostý text (text/html , pokud se požaduje prostřednictvím hlavičky Accept ). Toto chování lze odstranit odebráním souboru StringOutputFormatter. Formátovací moduly jsou odebrány v Program.cs. Akce, které mají návratový typ 204 No Content objektu modelu při vrácení null. Toto chování lze odstranit odebráním souboru HttpNoContentOutputFormatter. Následující kód odebere znak a StringOutputFormatter HttpNoContentOutputFormatter.

var builder = WebApplication.CreateBuilder(args);

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

Bez integrovaného StringOutputFormatterformátovače string JSON vrátí typy. Pokud je předdefinovaný formátovací modul JSON odebrán a je k dispozici formátovací modul XML, vrátí formátovací modul string XML typy. string V opačném případě vrátí návratové 406 Not Acceptabletypy .

Bez objektu HttpNoContentOutputFormatternull jsou formátovány pomocí konfigurovaného formátovače. Příklad:

• Formátovací modul JSON vrátí odpověď s textem null.
• Formátovací modul XML vrátí prázdný element XML se sadou atributů xsi:nil="true" .

Mapování adres URL formátu odpovědi

Klienti můžou v rámci adresy URL požadovat určitý formát, například:

• V řetězci dotazu nebo části cesty.
• Pomocí přípony souboru specifického pro konkrétní formát, například .xml nebo .json.

Mapování z cesty požadavku by mělo být zadané ve směrování, které rozhraní API používá. Příklad:

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

Předchozí trasa umožňuje zadat požadovaný formát pomocí volitelné přípony souboru. Atribut [FormatFilter] kontroluje existenci hodnoty formátu v RouteData řetězci a mapuje formát odpovědi na příslušný formátovací modul při vytvoření odpovědi.

Postup	Formátovač
/api/todoitems/5	Výchozí výstupní formátovací modul
/api/todoitems/5.json	Formátovací modul JSON (pokud je nakonfigurovaný)
/api/todoitems/5.xml	Formátovací modul XML (pokud je nakonfigurovaný)

Polymorfní deserializace

Integrované funkce poskytují omezený rozsah polymorfní serializace, ale vůbec žádná podpora deserializace. Deserializace vyžaduje vlastní převaděč. Úplný vzorek polymorfní deserializace najdete v tématu Polymorfní deserializace.

Další materiály

• Zobrazení nebo stažení ukázkového kódu (postup stažení)