Válaszadatok formázása a ASP.NET Core Web API-ban

ASP.NET Core MVC támogatja a válaszadatok formázását megadott formátumok használatával vagy az ügyfél kérésére válaszul.

Formátumspecifikus művelet eredményei

Egyes műveleteredmény-típusok egy adott formátumra vonatkoznak, például JsonResult és ContentResult. A műveletek olyan eredményeket adhatnak vissza, amelyek mindig egy megadott formátumot használnak, figyelmen kívül hagyva az ügyfél más formátumra vonatkozó kérését. A visszatérési JsonResult érték például JSON formátumú adatokat ad vissza, a visszaadott ContentResult adatok pedig egyszerű szöveges formátumú sztringadatokat ad vissza.

Egy adott típus visszaadásához nincs szükség műveletre. ASP.NET Core támogat bármilyen objektumszintű visszatérési értéket. A nem IActionResult típusok objektumait visszaadó műveletek eredményei a megfelelő IOutputFormatter implementációval szerializálva lesznek. További információ: Vezérlőművelet visszatérési típusai a ASP.NET Core webes API-ban.

A beépített segédmetódus ControllerBase.Ok alapértelmezés szerint JSON formátumú adatokat ad vissza:

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

A mintakód a teendők listáját adja vissza. Az F12 böngésző fejlesztői eszközeinek vagy a http-repl előző kódjával történő használata megjeleníti:

• A tartalomtípust tartalmazó válaszfejléc:application/json; charset=utf-8
• A kérelem fejlécei. Például a Accept fejlécet. A Accept fejlécet az előző kód figyelmen kívül hagyja.

Egyszerű szöveges formátumú adatok visszaadásához használja a ContentResult és a Content segédet.

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

Az előző kódrészletben a Content-Type visszatérített érték a text/plain.

Több visszatérési típussal rendelkező műveletek esetén adja vissza a következőt IActionResult: . Ha például a művelet eredménye alapján különböző HTTP-állapotkódokat ad vissza.

Tartalom egyeztetése

A tartalom egyeztetése akkor történik, ha az ügyfél egy Accept fejlécet ad meg. A ASP.NET Core által használt alapértelmezett formátum a JSON. A tartalom egyeztetése a következő:

• Implementálva: ObjectResult.
• Beépített az állapotkód-specifikus művelet eredményeibe, amelyeket a segítő metódusok adnak vissza. A műveleti eredmények segédmetódusai a ObjectResult-on alapulnak.

Modelltípus visszaadásakor a visszatérési típus a következő ObjectResult: .

A következő műveletmetódus a segédmetódusokat OkNotFound használja:

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

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

    return Ok(todo);
}

Alapértelmezés szerint a ASP.NET Core a következő médiatípusokat támogatja:

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

Az olyan eszközök, mint a Fiddler vagy a http-repl , beállíthatják a Accept kérés fejlécét a visszatérési formátum megadására. Ha a Accept fejléc olyan típust tartalmaz, amelyet a kiszolgáló támogat, a rendszer ezt a típust adja vissza. A következő szakasz bemutatja, hogyan adhat hozzá további formázókat.

A vezérlőműveletek POCO-kat (egyszerű régi CLR-objektumokat) adhatnak vissza. POCO visszaadásakor a futtatókörnyezet automatikusan létrehoz egy ObjectResult-t, amely becsomagolja az objektumot. Az ügyfél megkapja a formázott szerializált objektumot. Ha a visszaadott objektum az null, a 204 No Content rendszer választ ad vissza.

Az alábbi példa egy objektumtípust ad vissza:

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

Az előző kódban egy érvényes teendőelemre vonatkozó kérés válaszként 200 OK ad vissza. Egy érvénytelen teendőelemre vonatkozó kérés 204 No Content választ ad vissza.

Az Accept fejléc

A tartalom egyeztetésére akkor kerül sor, amikor egy Accept fejléc jelenik meg a kérelemben. Ha egy kérelem elfogadó fejlécet tartalmaz, ASP.NET Core:

• Az elfogadás fejlécében szereplő médiatípusok számbavétele beállítási sorrendben.
• Olyan formázót próbál megkeresni, amely a megadott formátumok egyikében tud választ adni.

Ha nem található olyan formázó, amely megfelel az ügyfél kérésének, ASP.NET Core:

• Visszaadja 406 Not Acceptable, ha MvcOptions.ReturnHttpNotAcceptable be van állítva true-ra vagy -
• Megkeresi az első formázót, amely képes választ generálni.

Ha nincs formázó a kért formátumhoz konfigurálva, a rendszer az objektumot formázó első formázót használja. Ha a kérés nem tartalmaz Accept fejlécet:

• Az objektumot kezelő első formázó szerializálja a választ.
• Nincs tárgyalás. A kiszolgáló határozza meg, hogy milyen formátumot kell visszaadni.

Ha az Elfogadás fejléc tartalmazza */*, a fejléc figyelmen kívül lesz hagyva, kivéve, ha RespectBrowserAcceptHeader igaz értékre MvcOptionsvan állítva.

Böngészők és tartalom egyeztetése

A tipikus API-ügyfelektől eltérően a webböngészők fejléceket biztosítanak Accept . A webböngészők számos formátumot határoznak meg, beleértve a helyettesítő karaktereket is. Alapértelmezés szerint, ha a keretrendszer azt észleli, hogy a kérés böngészőből érkezik:

• A Accept fejléc figyelmen kívül lesz hagyva.
• A tartalom JSON-ban lesz visszaadva, hacsak nincs más konfigurálva.

Ez a megközelítés konzisztensebb élményt nyújt a böngészőkben az API-k használata során.

Ha úgy szeretne konfigurálni egy alkalmazást, hogy megfeleljen a böngészőben az elfogadási fejléceket, állítsa a következőre a RespectBrowserAcceptHeader tulajdonságot: true.

var builder = WebApplication.CreateBuilder(args);

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

Formázók konfigurálása

Az extra formátumok támogatásához szükséges alkalmazások hozzáadhatják a megfelelő NuGet-csomagokat, és konfigurálhatják a támogatást. A bemenethez és a kimenethez külön formátumok tartoznak. A bemeneti formázókat a modellkötés használja. A kimeneti formázók a válaszok formázására szolgálnak. Az egyéni formázók létrehozásáról további információt az Egyéni formázók című témakörben talál.

XML-formátum támogatása

Az XmlSerializer által implementált XML-formázók konfigurálásához hívja meg a AddXmlSerializerFormatters:

var builder = WebApplication.CreateBuilder(args);

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

Az előző kód használatakor a vezérlő metódusai a kérés fejléce Accept alapján visszaadják a megfelelő formátumot.

System.Text.Json alapú formázók konfigurálása

A(z) System.Text.Json alapú formázók funkcióinak konfigurálásához használja a Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Az alábbi kiemelt kód a PascalCase formázást konfigurálja az alapértelmezett camelCase formázás helyett:

var builder = WebApplication.CreateBuilder(args);

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

A kimeneti szerializálási beállítások adott műveletekhez való konfigurálásához használja JsonResulta következőt: . Például:

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

Newtonsoft.Json-alapú JSON formátum támogatásának hozzáadása

Az alapértelmezett JSON-formázók a következőt használják System.Text.Json: . A(z) Newtonsoft.Json alapú formázók használatához telepítse a Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-csomagot, és konfigurálja a Program.cs.

var builder = WebApplication.CreateBuilder(args);

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

Az előző kódban a AddNewtonsoftJson hívás konfigurálja a következő Web API-, MVC- és Razor Pages-funkciók használatát Newtonsoft.Json:

• JSON-t olvasó és író bemeneti és kimeneti formázók
• JsonResult
• JSON-javítás
• IJsonHelper
• TempData

Előfordulhat, hogy egyes funkciók nem működnek megfelelően a System.Text.Json alapú formázókkal, és hivatkozni kell a Newtonsoft.Json alapú formázókra. Folytassa a Newtonsoft.Json alapú formázók használatát, amikor az alkalmazás:

• A Newtonsoft.Json attribútumokat használja. Például, [JsonProperty] vagy [JsonIgnore].
• Testre szabja a szerializálási beállításokat.
• A szolgáltatásokra Newtonsoft.Json támaszkodik.

A Newtonsoft.Json alapú formatter funkcióinak konfigurálásához használja a SerializerSettings elemet.

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

A kimeneti szerializálási beállítások adott műveletekhez való konfigurálásához használja JsonResulta következőt: . Például:

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

Formázd meg a ProblemDetails és ValidationProblemDetails válaszokat

A következő műveletmetódus meghívja a ControllerBase.Problem függvényt egy ProblemDetails válasz létrehozásához.

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

A ProblemDetails válasz mindig camelCase, még akkor is, ha az alkalmazás PascalCase formátumot állít be. ProblemDetails az RFC 7807-et követi, amely kisbetűt ad meg.

Amikor az [ApiController] attribútumot egy vezérlőosztályra alkalmazza, a vezérlő választ hoz létre ValidationProblemDetails , ha a modell érvényesítése sikertelen. Ez a válasz tartalmaz egy szótárt, amely a modell tulajdonságneveit hibakulcsként használja, változatlanul. A következő modell például egyetlen, érvényesítést igénylő tulajdonságot tartalmaz:

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

A válasz, amelyet ValidationProblemDetails érvénytelen Value tulajdonság esetén alapértelmezés szerint visszaadnak, a Value hibakulcsot használja, ahogyan az a következő példában látható:

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

A hibakulcsként használt tulajdonságnevek formázásához adja hozzá a IMetadataDetailsProvider implementációját a MvcOptions.ModelMetadataDetailsProviders gyűjteményhez. Az alábbi példa egy -alapú implementációt System.Text.Jsonad hozzá, SystemTextJsonValidationMetadataProvideramely alapértelmezés szerint camelCaseként formázja a tulajdonságneveket:

builder.Services.AddControllers();

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

SystemTextJsonValidationMetadataProvider Emellett elfogadja a konstruktor implementációját JsonNamingPolicy is, amely egy egyéni elnevezési szabályzatot határoz meg a tulajdonságnevek formázásához.

A modellen belüli tulajdonság egyéni nevének beállításához használja a [JsonPropertyName] attribútumot a tulajdonságon:

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

A ValidationProblemDetails válasz, amelyet az előző modellnél kapunk, ha a Value tulajdonság érvénytelen, a következő hibakulcsot sampleValue használja, amint az a következő példában látható:

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

A ValidationProblemDetails válasz formázásához a következő Newtonsoft.Json használja: NewtonsoftJsonValidationMetadataProvider

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

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

Alapértelmezés szerint NewtonsoftJsonValidationMetadataProvider a tulajdonságneveket camelCase formátumban formázta. NewtonsoftJsonValidationMetadataProvider Emellett elfogadja a konstruktor implementációját NamingPolicy is, amely egy egyéni elnevezési szabályzatot határoz meg a tulajdonságnevek formázásához. A modellen belüli tulajdonság egyéni nevének beállításához használja az [JsonProperty] attribútumot.

Formátum megadása

A válaszformátumok korlátozásához alkalmazza a szűrőt [Produces] . A legtöbb szűrő alkalmazható a művelet, a vezérlő vagy a globális hatókör szintjén:

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

Az előző [Produces] szűrő:

• Kényszeríti a vezérlőn belüli összes műveletet, hogy JSON-formátumú válaszokat ad vissza a POCOS-okra (egyszerű régi CLR-objektumok) vagy ObjectResult annak származtatott típusaira.
• JSON-formátumú válaszokat ad vissza akkor is, ha más formázók vannak konfigurálva, és az ügyfél más formátumot ad meg.

További információ: Szűrők.

Speciális esetformázók

Néhány speciális eset beépített formázókkal van implementálva. Alapértelmezés szerint a string visszatérési típusok szövegként/egyszerűként vannak formázva (szöveg/html, ha a fejlécen keresztül kérik).Accept Ez a viselkedés törölhető az StringOutputFormatter eltávolításával. A formázók törlődnek a fájlból Program.cs. Azokban az esetekben, amikor a műveletek modellobjektum visszatérési típussal rendelkeznek, 204 No Content adódik vissza, amikor a null a visszatérési érték. Ez a viselkedés törölhető az HttpNoContentOutputFormatter eltávolításával. Az alábbi kód eltávolítja a StringOutputFormatter és HttpNoContentOutputFormatter-t.

var builder = WebApplication.CreateBuilder(args);

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

A StringOutputFormatter hiányában a beépített JSON formázó formázza a string visszatérési típusokat. Ha a beépített JSON-formázó el lett távolítva, és elérhető egy XML-formázó, az XML-formázó formátumok string típusokat ad vissza. Ellenkező esetben a string visszatérési típusok 406 Not Acceptable-t adnak vissza.

HttpNoContentOutputFormatter nélkül a null objektumok a konfigurált formázó használatával vannak formázva. Például:

• A JSON-formázó egy olyan választ ad vissza, amelynek törzse a következő null: .
• Az XML-formázó egy üres XML-elemet ad vissza az attribútumkészlettel xsi:nil="true" .

Válaszformátum URL-leképezései

Az ügyfelek az URL-cím részeként kérhetnek egy adott formátumot, például:

• A lekérdezési sztringben vagy az elérési út egy részében.
• Formátumspecifikus fájlkiterjesztés, például .xml vagy .jsonhasználatával.

A kérelem elérési útjának leképezését az API által használt útvonalon kell megadni. Például:

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

Az előző útvonal lehetővé teszi a kért formátum megadását opcionális fájlkiterjesztés használatával. Az [FormatFilter] attribútum ellenőrzi, hogy létezik-e a formátumérték a RouteData fájlban, és a válaszformátumot a válasz létrehozásakor a megfelelő formázóhoz rendeli.

Route	Formatter
/api/todoitems/5	Az alapértelmezett kimeneti formátum
/api/todoitems/5.json	A JSON-formázó (ha konfigurálva van)
/api/todoitems/5.xml	Az XML-formázó (ha konfigurálva van)

Polimorf deszerializálás

A beépített funkciók a polimorf szerializálás korlátozott körét biztosítják, de egyáltalán nem támogatják a deszerializálást. A deszerializáláshoz egyéni konverter szükséges. A polimorf deszerializálás teljes mintájáért lásd a polimorf deszerializálást .

További erőforrások

• Mintakód megtekintése vagy letöltése (hogyan töltsd le)