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 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 ignorovat požadavek klienta na jiný formát. Například vrácení vrácených JsonResult dat 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 formátovaná json:

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

Ukázkový kód vrátí seznam položek úkolů. Pomocí vývojářských nástrojů prohlížeče F12 nebo Nástroje Postman 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í. Záhlaví Accept je ignorováno předchozím kódem.

Chcete-li vrátit data formátovaná prostým textem, použijte ContentResult a pomocné rutiny Content :

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

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

Pro akce s více návratovými typy vrátíte hodnotu IActionResult. Například při vrácení 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ů akce specifické 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á pomocné OkNotFound 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 Postman , mohou nastavit hlavičku Accept požadavku tak, aby určila návratový formát. Pokud hlavička Accept obsahuje typ, který server podporuje, tento typ se vrátí. V další části se dozvíte, jak přidat další formátovací moduly.

Akce kontroleru můžou vracet objekty POCO (prosté staré objekty CLR). Když se vrátí poco, modul runtime automaticky vytvoří ObjectResult zalomení objektu. 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 204 No Content položku úkolu vrátí odpověď.

Hlavička Přijmout

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

  • Vytvoří výčet typů médií v záhlaví accept v pořadí předvoleb.
  • Pokusí se najít formátovač, 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, pokud MvcOptions.ReturnHttpNotAcceptable je nastavena na truehodnotu , nebo -
  • Pokusí se najít první formátovač, 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 objekt formátovat. 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 .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ž architektura zjistí, že požadavek pochází z prohlížeče, ve výchozím nastavení:

  • 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átování

Aplikace, které potřebují podporovat další formáty, můžou přidat příslušné balíčky NuGet a nakonfigurovat podporu. Pro vstup a výstup existují samostatné formátovací moduly. 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ů na základě

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

var builder = WebApplication.CreateBuilder(args);

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

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.

Chcete-li nakonfigurovat 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 na základě

Výchozí formátovací moduly JSON používají System.Text.Json. Pokud chcete použít Newtonsoft.Jsonformátovací moduly založené na NuGet, nainstalujte balíček NuGet a nakonfigurujte Microsoft.AspNetCore.Mvc.NewtonsoftJson 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:

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

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

To configure features for the Newtonsoft.Json-based formatters, use SerializerSettings:

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

Chcete-li nakonfigurovat 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()
        });

Určení formátu

Pokud chcete omezit formáty odpovědí, použijte [Produces] filtr. Stejně jako většina filtrů[Produces] se dá použít v rámci akce, kontroleru nebo globálního rozsahu:

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

Předchozí [Produces] filtr:

  • Vynutí všechny akce v kontroleru, aby vrátily odpovědi ve formátu JSON pro objekty POCOs (prosté staré objekty 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á a malá písmena

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

var builder = WebApplication.CreateBuilder(args);

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

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

HttpNoContentOutputFormatterBez objektu null jsou formátovány pomocí nakonfigurované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 si můžou vyžádat konkrétní formát jako součást adresy URL, například:

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

Mapování z cesty požadavku by mělo být zadáno ve trase, kterou 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 souboru RouteData a mapuje formát odpovědi na příslušný formát při vytvoření odpovědi.

Trasa Formátovací modul
/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ý)

Další materiály

ASP.NET Core MVC podporuje formátování dat odpovědi. Data odpovědí lze formátovat pomocí konkrétních formátů nebo v reakci na požadovaný formát klienta.

Zobrazení nebo stažení vzorového kódu (jak stáhnout)

Výsledky akce specifické pro 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 formátované v určitém formátu bez ohledu na předvolby klienta. Například vrácení vrátí JsonResult data ve formátu JSON. ContentResult Vrácení nebo řetězec vrací ř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.

Integrovaná pomocná metoda Ok vrací data ve formátu JSON:

// GET: api/authors
[HttpGet]
public ActionResult Get()
{
    return Ok(_authors.List());
}

Ukázkový soubor ke stažení vrátí seznam autorů. Použití vývojářských nástrojů prohlížeče F12 nebo Nástroje Postman s předchozím kódem:

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

Chcete-li vrátit data formátovaná prostým textem, použijte ContentResult a pomocné rutiny Content :

// GET api/authors/about
[HttpGet("About")]
public ContentResult About()
{
    return Content("An API listing authors of docs.asp.net.");
}

V předchozím kódu Content-Type je text/plainvráceno . Vrácení řetězce:Content-Typetext/plain

// GET api/authors/version
[HttpGet("version")]
public string Version()
{
    return "Version 1.0.0";
}

Pro akce s více návratovými typy vrátíte hodnotu IActionResult. Například vrácení různých stavových kódů HTTP na základě výsledku provedených operací.

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ů akce specifické 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á pomocné OkNotFound metody:

// GET: api/authors/search?namelike=th
[HttpGet("Search")]
public IActionResult Search(string namelike)
{
    var result = _authors.GetByNameSubstring(namelike);
    if (!result.Any())
    {
        return NotFound(namelike);
    }
    return Ok(result);
}

Ve výchozím nastavení ASP.NET Core podporuje application/jsona text/jsontext/plain typy médií. Nástroje, jako je Fiddler nebo Postman , mohou nastavit hlavičku Accept požadavku tak, aby určila návratový formát. Pokud hlavička Accept obsahuje typ, který server podporuje, tento typ se vrátí. V další části se dozvíte, jak přidat další formátovací moduly.

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

Vrácení typu objektu:

// GET api/authors/RickAndMSFT
[HttpGet("{alias}")]
public Author Get(string alias)
{
    return _authors.GetByAlias(alias);
}

V předchozím kódu vrátí 200 OK požadavek na platný alias autora odpověď s daty autora. Požadavek na neplatný alias vrátí 204 No Content odpověď.

Hlavička Přijmout

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

  • Vytvoří výčet typů médií v záhlaví accept v pořadí předvoleb.
  • Pokusí se najít formátovač, 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, pokud MvcOptions.ReturnHttpNotAcceptable je nastavena na truehodnotu , nebo -
  • Pokusí se najít první formátovač, 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 objekt formátovat. 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 .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ž architektura zjistí, že požadavek pochází z prohlížeče, ve výchozím nastavení:

  • 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 dodržovala hlavičky přijetí prohlížeče, nastavte RespectBrowserAcceptHeader na true:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        options.RespectBrowserAcceptHeader = true; // false by default
    });
}

Konfiguraceformátch

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

Přidání podpory formátu XML

Formátovací moduly XML implementované pomocí XmlSerializer volání AddXmlSerializerFormatters:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddXmlSerializerFormatters();
}

Předchozí kód serializuje výsledky pomocí XmlSerializer.

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.Json formátovacích souborů na základě

Funkce pro System.Text.Json založené formátovací moduly lze nakonfigurovat pomocí Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Výchozí formátování je camelCase. Následující zvýrazněný kód nastaví pascalcase formátování:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddJsonOptions(options =>
            options.JsonSerializerOptions.PropertyNamingPolicy = null);
}

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

[HttpGet("error")]
public IActionResult GetError()
{
    return Problem("Something went wrong!");
}

S předchozím kódem:

  • https://localhost:5001/WeatherForecast/temperature vrátí PascalCase.
  • https://localhost:5001/WeatherForecast/error vrátí camelCase. Odpověď na chybu je vždy camelCase, i když aplikace nastaví formát na PascalCase. ProblemDetails se řídí dokumentem RFC 7807, který určuje malá písmena.

Následující kód nastaví PascalCase a přidá vlastní převaděč:

services.AddControllers().AddJsonOptions(options =>
{
    // Use the default property (Pascal) casing.
    options.JsonSerializerOptions.PropertyNamingPolicy = null;

    // Configure a custom converter.
    options.JsonSerializerOptions.Converters.Add(new MyCustomJsonConverter());
});

Možnosti serializace výstupu na základě akce lze nakonfigurovat pomocí JsonResult. Příklad:

public IActionResult Get()
{
    return Json(model, new JsonSerializerOptions
    {
        WriteIndented = true,
    });
}

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

Výchozí formátovací moduly JSON jsou založené na System.Text.Json. Podpora pro Newtonsoft.Json založené formátovače a funkce je k dispozici instalací Microsoft.AspNetCore.Mvc.NewtonsoftJson balíčku NuGet a jeho konfigurací v Startup.ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
    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:

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

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

Funkceproch Newtonsoft.JsonMicrosoft.AspNetCore.Mvc.MvcNewtonsoftJsonOptions.SerializerSettings

services.AddControllers().AddNewtonsoftJson(options =>
{
    // Use the default property (Pascal) casing
    options.SerializerSettings.ContractResolver = new DefaultContractResolver();

    // Configure a custom converter
    options.SerializerSettings.Converters.Add(new MyCustomJsonConverter());
});

Možnosti serializace výstupu na základě akce lze nakonfigurovat pomocí JsonResult. Příklad:

public IActionResult Get()
{
    return Json(model, new JsonSerializerSettings
    {
        Formatting = Formatting.Indented,
    });
}

Určení formátu

Chcete-li omezit formáty odpovědí, použijte [Produces] filtr. Podobně jako většina filtrů[Produces] se dá použít v rámci akce, kontroleru nebo globálního oboru:

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

Předchozí [Produces] filtr:

  • Vynutí všechny akce v kontroleru, aby vrátily odpovědi formátované json pro objekty POCOs (prosté staré objekty CLR) nebo ObjectResult jeho odvozené typy.
  • Pokud jsou nakonfigurované jiné formátovací moduly a klient určuje jiný formát, vrátí se JSON.

Další informace najdete v tématu Filtry.

Speciální formátovací moduly velkých a malých písmen

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

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        // requires using Microsoft.AspNetCore.Mvc.Formatters;
        options.OutputFormatters.RemoveType<StringOutputFormatter>();
        options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
    });
}

Bez integrovaného StringOutputFormatterformátu string JSON vrací typy. Pokud je předdefinovaný formátovací modul JSON odebrán a je k dispozici formátovací modul XML, vrátí formáty string FORMÁTU XML typy. string V opačném případě vrátí návratové typy 406 Not Acceptable.

HttpNoContentOutputFormatterBez objektu null jsou formátovány pomocí nakonfigurované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 si můžou vyžádat konkrétní formát jako součást adresy URL, například:

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

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

[Route("api/[controller]")]
[ApiController]
[FormatFilter]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}.{format?}")]
    public Product Get(int id)
    {

Předchozí trasa umožňuje zadat požadovaný formát jako volitelnou příponu souboru. Atribut [FormatFilter] kontroluje existenci hodnoty formátu v souboru RouteData a mapuje formát odpovědi na odpovídající formátovací modul při vytvoření odpovědi.

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

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 formát

Některé typy výsledků akce jsou specifické pro určitý formát, například JsonResult a ContentResult. Akce můžou vrátit výsledky, které vždy používají zadaný formát, a ignorovat požadavek klienta na jiný formát. Například vrácení vrácených JsonResult dat ve formátu JSON a vrácení vrátí řetězcová ContentResult 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 formátovaná ve formátu JSON:

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

Ukázkový kód vrátí seznam položek úkolů. Pomocí vývojářských nástrojů pro prohlížeč F12 nebo Postmanu 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í. Záhlaví Accept je ignorováno předchozím kódem.

Pokud chcete vrátit data formátovaná 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 vrácení 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:

  • Implementuje .ObjectResult
  • Integrované do výsledků akce specifické 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á pomocné OkNotFound 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 Postman , mohou nastavit hlavičku Accept požadavku tak, aby určila návratový formát. Pokud hlavička Accept obsahuje typ, který server podporuje, tento typ se vrátí. V další části se dozvíte, jak přidat další formátovací moduly.

Akce kontroleru můžou vracet objekty POCO (prosté staré objekty CLR). Když se vrátí poco, modul runtime automaticky vytvoří ObjectResult zalomení objektu. 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 204 No Content položku úkolu vrátí odpověď.

Hlavička Přijmout

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

  • Vytvoří výčet typů médií v záhlaví accept v pořadí předvoleb.
  • Pokusí se najít formátovač, 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, pokud MvcOptions.ReturnHttpNotAcceptable je nastavena na truehodnotu , nebo -
  • Pokusí se najít první formátovač, 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 objekt formátovat. 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 .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ž architektura zjistí, že požadavek pochází z prohlížeče, ve výchozím nastavení:

  • 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átování

Aplikace, které potřebují podporovat další formáty, můžou přidat příslušné balíčky NuGet a nakonfigurovat podporu. Pro vstup a výstup existují samostatné formátovací moduly. 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ů na základě

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

var builder = WebApplication.CreateBuilder(args);

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

Chcete-li nakonfigurovat 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 na základě

Výchozí formátovací moduly JSON používají System.Text.Json. Pokud chcete použít Newtonsoft.Jsonformátovací moduly založené na NuGet, nainstalujte balíček NuGet a nakonfigurujte Microsoft.AspNetCore.Mvc.NewtonsoftJson 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:

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

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

To configure features for the Newtonsoft.Json-based formatters, use SerializerSettings:

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

Chcete-li nakonfigurovat 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] Pokud je atribut použit pro 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á chybový klíč 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 MvcOptions.ModelMetadataDetailsProviders kolekce implementaciIMetadataDetailsProvider. Následující příklad přidá implementaci založenou System.Text.Jsonna jazyce , 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 názvy vlastností formátování.

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

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í formátuje NewtonsoftJsonValidationMetadataProvider názvy vlastností jako camelCase. NewtonsoftJsonValidationMetadataProvider také přijímá implementaci NamingPolicy v jeho konstruktoru, který určuje vlastní zásady pojmenování pro názvy vlastností formátování. Pokud chcete nastavit vlastní název vlastnosti v modelu, použijte atribut [JsonProperty] .

Určení formátu

Pokud chcete omezit formáty odpovědí, použijte [Produces] filtr. Stejně jako většina filtrů[Produces] se dá použít v rámci akce, kontroleru nebo globálního rozsahu:

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

Předchozí [Produces] filtr:

  • Vynutí všechny akce v kontroleru, aby vrátily odpovědi ve formátu JSON pro objekty POCOs (prosté staré objekty 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á a malá písmena

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

var builder = WebApplication.CreateBuilder(args);

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

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

HttpNoContentOutputFormatterBez objektu null jsou formátovány pomocí nakonfigurované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 si můžou vyžádat konkrétní formát jako součást adresy URL, například:

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

Mapování z cesty požadavku by mělo být zadáno ve trase, kterou 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 souboru RouteData a mapuje formát odpovědi na příslušný formát při vytvoření odpovědi.

Trasa Formátovací modul
/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ý)

Další materiály