Dela via

Formatera svarsdata i ASP.NET Core Web API

ASP.NET Core MVC stöder formatering av svarsdata, med angivna format eller som svar på en klients begäran.

Formatspecifika åtgärdsresultat

Vissa typer av åtgärdsresultat är specifika för ett visst format, till exempel JsonResult och ContentResult. Åtgärder kan returnera resultat som alltid använder ett angivet format och ignorerar en klients begäran om ett annat format. Om du till exempel returnerar JsonResult returneras JSON-formaterade data och returnerar ContentResult returneras strängar med oformaterad text.

En åtgärd krävs inte för att returnera någon specifik typ. ASP.NET Core stöder alla objektreturvärden. Resultat från åtgärder som returnerar objekt som inte är av IActionResult-typer serialiseras med lämpliga IOutputFormatter-implementeringar. Mer information finns i Returnera typer av kontrollantåtgärder i ASP.NET Core-webb-API.

Som standard returnerar den inbyggda hjälpmetoden ControllerBase.Ok JSON-formaterade data:

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

Exempelkoden returnerar en lista över att göra-objekt. Använd utvecklarverktygen för F12-webbläsaren eller http-repl med föregående kod:

  • Svarshuvudet som innehåller innehållstyp:application/json; charset=utf-8.
  • Begärandehuvuden. Till exempel Accept rubriken. Rubriken Accept ignoreras av föregående kod.

Om du vill returnera oformaterade data använder du ContentResult och hjälpverktyget Content :

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

I föregående kod returneras Content-Type som text/plain.

För åtgärder med flera returtyper returnerar du IActionResult. När du till exempel returnerar olika HTTP-statuskoder baserat på resultatet av åtgärden.

Innehållsförhandling

Innehållsförhandling sker när klienten anger ett Accept-huvud. Standardformatet som används av ASP.NET Core är JSON. Innehållsförhandling är:

  • Implementerad av ObjectResult.
  • Inbyggt i statuskodsspecifika åtgärdsresultat som returneras från hjälpmetoderna. Hjälpmetoderna för åtgärdsresultat baseras på ObjectResult.

När en modelltyp returneras är returtypen ObjectResult.

Följande åtgärdsmetod använder hjälpmetoderna Ok och NotFound :

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

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

    return Ok(todo);
}

Som standard stöder ASP.NET Core följande medietyper:

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

Verktyg som Fiddler eller curl kan ange Accept begärandehuvudet för att ange returformatet. Accept Om headern innehåller en typ som servern stöder returneras den typen. I nästa avsnitt visas hur du lägger till ytterligare formaterare.

Kontrolleråtgärder kan returnera POCOs (vanliga gamla CLR-objekt). När en POCO returneras skapar körningsmiljön automatiskt en ObjectResult som omsluter objektet. Klienten hämtar det formaterade serialiserade objektet. Om objektet som returneras är nullreturneras ett 204 No Content svar.

I följande exempel returneras en objekttyp:

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

I föregående kod returnerar en förfrågan om ett giltigt objekt ett 200 OK svar. En begäran om ett ogiltigt uppgiftsobjekt returnerar en 204 No Content svarskod.

Sidhuvudet Acceptera

Innehållsförhandling sker när en Accept rubrik visas i begäran. När en begäran innehåller ett accepthuvud ASP.NET Core:

  • Räknar upp medietyperna i accepthuvudet i inställningsordning.
  • Försöker hitta en formaterare som kan skapa ett svar i något av de angivna formaten.

Om det inte finns någon formatering som kan uppfylla klientens begäran ASP.NET Core:

Om ingen formatering har konfigurerats för det begärda formatet används den första formaterare som kan formatera objektet. Om inget Accept huvud visas i begäran:

  • Den första formaterare som kan hantera objektet används för att serialisera svaret.
  • Det pågår inga förhandlingar. Servern avgör vilket format som ska returneras.

Om Accept-rubriken innehåller */* ignoreras rubriken, såvida inte RespectBrowserAcceptHeader är inställt på sant på MvcOptions.

Webbläsare och innehållsförhandling

Till skillnad från vanliga API-klienter levererar webbläsare Accept rubriker. Webbläsare anger många format, inklusive jokertecken. När ramverket som standard identifierar att begäran kommer från en webbläsare:

  • Rubriken Accept ignoreras.
  • Innehållet returneras i JSON, om inget annat har konfigurerats.

Den här metoden ger en mer konsekvent upplevelse i webbläsare när du använder API:er.

Om du vill konfigurera en app så att den respekterar webbläsarens accepthuvuden RespectBrowserAcceptHeader anger du egenskapen till true:

var builder = WebApplication.CreateBuilder(args);

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

Konfigurera formaterare

Appar som behöver stöd för extra format kan lägga till lämpliga NuGet-paket och konfigurera support. Det finns separata formaterare för in- och utdata. Indataformaterare används av modellbindning. Utdataformaterare används för att formatera svar. Information om hur du skapar en anpassad formatering finns i Anpassade formatters.

Lägg till stöd för XML-format

Om du vill konfigurera XML-formaterare som implementerats med hjälp av XmlSerializeranropar du AddXmlSerializerFormatters:

var builder = WebApplication.CreateBuilder(args);

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

När du använder föregående kod returnerar kontrollantmetoder lämpligt format baserat på begärandehuvudet Accept .

Konfigurera System.Text.Json-baserade formatters

För att konfigurera funktioner för System.Text.Json-baserade formatrar, använd Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Följande markerade kod konfigurerar PascalCase-formatering i stället för standardformatering av camelCase:

var builder = WebApplication.CreateBuilder(args);

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

Följande åtgärdsmetod anropar ControllerBase.Problem för att skapa ett ProblemDetails svar:

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

Ett ProblemDetails svar är alltid camelCase, även när appen anger formatet till PascalCase. ProblemDetails följer RFC 7807, som specificerar användning av gemener.

Om du vill konfigurera alternativ för utdatas serialisering för specifika åtgärder använder du JsonResult. Till exempel:

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

Stöd för Newtonsoft.Json-baserat JSON-format

JSON-standardformaterarna använder System.Text.Json. Om du vill använda de Newtonsoft.Json-baserade formatrarna installerar Microsoft.AspNetCore.Mvc.NewtonsoftJson du NuGet-paketet och konfigurerar det i Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

I föregående kod konfigurerar anropet till AddNewtonsoftJson följande webb-API,MVC- och Razor Pages-funktioner för att använda Newtonsoft.Json:

Vissa funktioner kanske inte fungerar bra med System.Text.Json-baserade formatare och kräver en referens till de Newtonsoft.Json-baserade formatrarna. Fortsätt att använda Newtonsoft.Json-baserade formaterare när appen:

  • Använder Newtonsoft.Json attribut. Till exempel [JsonProperty] eller [JsonIgnore].
  • Anpassar serialiseringsinställningarna.
  • Förlitar sig på funktioner som Newtonsoft.Json tillhandahåller.

Om du vill konfigurera funktioner för de Newtonsoft.Json-baserade formatrarna använder du SerializerSettings:

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

Om du vill konfigurera alternativ för utdatas serialisering för specifika åtgärder använder du JsonResult. Till exempel:

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

Ange ett format

Använd filtret för att begränsa svarsformaten [Produces] . Precis som de flesta filter kan [Produces] tillämpas på åtgärden, kontrollern eller det globala omfånget:

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

Föregående [Produces] filter:

  • Tvingar alla åtgärder i kontrollanten att returnera JSON-formaterade svar för POCOs (vanliga gamla CLR-objekt) eller ObjectResult dess härledda typer.
  • Returnera JSON-formaterade svar även om andra formaterare har konfigurerats och klienten anger ett annat format.

Mer information finns i Filter.

Särskilda formatinställningar

Vissa specialfall implementeras med hjälp av inbyggda formatters. Som standardinställning formateras returtyperna som string (text/html om det begärs via -huvudet). Det här beteendet kan tas bort genom att ta bort StringOutputFormatter. Formaterare tas bort i Program.cs. Åtgärder som har en modellobjektreturtyp returneras 204 No Content när du returnerar null. Det här beteendet kan tas bort genom att ta bort HttpNoContentOutputFormatter. Följande kod tar StringOutputFormatter bort och HttpNoContentOutputFormatter.

var builder = WebApplication.CreateBuilder(args);

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

Utan StringOutputFormatter formaterar den inbyggda JSON-formatören string returtyper. Om den inbyggda JSON-formateren tas bort och en XML-formaterare är tillgänglig returnerar XML-formateringsformaten string typer. Annars returnerar returtyper string406 Not Acceptable.

HttpNoContentOutputFormatterUtan formateras null-objekten med den konfigurerade formateren. Till exempel:

  • JSON-formaterare returnerar ett svar med en brödtext av null.
  • XML-formaterare returnerar ett tomt XML-element med attributuppsättningen xsi:nil="true" .

Svarsformatets URL-mappningar

Klienter kan begära ett visst format som en del av URL:en, till exempel:

  • I frågesträngen eller en del av sökvägen.
  • Genom att använda ett formatspecifikt filnamnstillägg som .xml eller .json.

Mappningen från begärans sökväg bör specificeras i den rutt som API:et använder. Till exempel:

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

Föregående väg gör att det begärda formatet kan anges med hjälp av ett valfritt filnamnstillägg. Attributet [FormatFilter] kontrollerar om formatvärdet finns i RouteData och mappar svarsformatet till lämplig formatering när svaret skapas.

Route Formatter
/api/todoitems/5 Standardutdataformaterare
/api/todoitems/5.json JSON-formaterare (om den är konfigurerad)
/api/todoitems/5.xml XML-formaterare (om den är konfigurerad)

Polymorf deserialisering

Inbyggda funktioner ger ett begränsat utbud av polymorf serialisering men inget stöd för deserialisering alls. Deserialisering kräver en anpassad konverterare. Se Polymorf deserialisering för ett komplett urval av polymorfisk deserialisering.

Ytterligare resurser

ASP.NET Core MVC har stöd för formatering av svarsdata. Svarsdata kan formateras med specifika format eller som svar på det begärda formatet för klienten.

Visa eller ladda ned exempelkod (hur du laddar ned)

Formatspecifika åtgärdsresultat

Vissa typer av åtgärdsresultat är specifika för ett visst format, till exempel JsonResult och ContentResult. Åtgärder kan returnera resultat som är formaterade i ett visst format, oavsett klientinställningar. Om du till exempel returnerar JsonResult returneras data i JSON-format. Returnerar ContentResult eller en sträng returnerar strängdata formaterade som vanlig text.

En åtgärd krävs inte för att returnera någon specifik typ. ASP.NET Core stöder alla objektreturvärden. Resultat från åtgärder som returnerar objekt som inte är av IActionResult-typer serialiseras med lämpliga IOutputFormatter-implementeringar. Mer information finns i Returnera typer av kontrollantåtgärder i ASP.NET Core-webb-API.

Den inbyggda hjälpmetoden Ok returnerar JSON-formaterade data:

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

Exempelnedladdningen returnerar listan över författare. Använd utvecklarverktygen i F12-webbläsaren eller http-repl med föregående kod:

  • Svarshuvudet som innehåller innehållstyp:application/json; charset=utf-8 visas.
  • Begäranderubrikerna visas. Till exempel Accept rubriken. Rubriken Accept ignoreras av föregående kod.

Om du vill returnera oformaterade data använder du ContentResult och hjälpverktyget Content :

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

I föregående kod returneras Content-Type som text/plain. Returnerar en sträng som levererar Content-Type :text/plain

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

För åtgärder med flera returtyper returnerar du IActionResult. Du kan till exempel returnera olika HTTP-statuskoder baserat på resultatet av utförda åtgärder.

Innehållsförhandling

Innehållsförhandling sker när klienten anger ett Accept-huvud. Standardformatet som används av ASP.NET Core är JSON. Innehållsförhandling är:

  • Implementerad av ObjectResult.
  • Inbyggt i statuskodsspecifika åtgärdsresultat som returneras från hjälpmetoderna. Hjälpmetoderna för åtgärdsresultat baseras på ObjectResult.

När en modelltyp returneras är returtypen ObjectResult.

Följande åtgärdsmetod använder hjälpmetoderna Ok och NotFound :

// 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);
}

Som standard stöder ASP.NET Core medietyperna application/json, text/json och text/plain. Verktyg som Fiddler eller http-repl kan ange Accept begärandehuvudet för att ange returformatet. Accept Om headern innehåller en typ som servern stöder returneras den typen. I nästa avsnitt visas hur du lägger till ytterligare formaterare.

Kontrolleråtgärder kan returnera POCOs (vanliga gamla CLR-objekt). När en POCO returneras skapar körningsmiljön automatiskt en ObjectResult som omsluter objektet. Klienten hämtar det formaterade serialiserade objektet. Om objektet som returneras är nullreturneras ett 204 No Content svar.

Returnerar en objekttyp

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

I föregående kod returnerar en begäran om ett giltigt författarealias ett 200 OK svar med författarens data. En begäran om ett ogiltigt alias returnerar ett 204 No Content svar.

Sidhuvudet Acceptera

Innehållsförhandling sker när en Accept rubrik visas i begäran. När en begäran innehåller ett accepthuvud ASP.NET Core:

  • Räknar upp medietyperna i accepthuvudet i inställningsordning.
  • Försöker hitta en formaterare som kan skapa ett svar i något av de angivna formaten.

Om det inte finns någon formatering som kan uppfylla klientens begäran ASP.NET Core:

Om ingen formatering har konfigurerats för det begärda formatet används den första formaterare som kan formatera objektet. Om inget Accept huvud visas i begäran:

  • Den första formaterare som kan hantera objektet används för att serialisera svaret.
  • Det pågår inga förhandlingar. Servern avgör vilket format som ska returneras.

Om Accept-rubriken innehåller */* ignoreras rubriken, såvida inte RespectBrowserAcceptHeader är inställt på sant på MvcOptions.

Webbläsare och innehållsförhandling

Till skillnad från vanliga API-klienter levererar webbläsare Accept rubriker. Webbläsare anger många format, inklusive jokertecken. När ramverket som standard identifierar att begäran kommer från en webbläsare:

  • Rubriken Accept ignoreras.
  • Innehållet returneras i JSON, om inget annat har konfigurerats.

Den här metoden ger en mer konsekvent upplevelse i webbläsare när du använder API:er.

Om du vill konfigurera en app för att uppfylla webbläsarens accepthuvuden anger du RespectBrowserAcceptHeader till true:

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

Konfigurera formaterare

Appar som behöver stöd för ytterligare format kan lägga till lämpliga NuGet-paket och konfigurera support. Det finns separata formaterare för in- och utdata. Indataformaterare används av modellbindning. Utdataformaterare används för att formatera svar. Information om hur du skapar en anpassad formatering finns i Anpassade formatters.

Lägg till stöd för XML-format

XML-formaterare som implementeras med XmlSerializer konfigureras genom att anropa AddXmlSerializerFormatters:

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

Föregående kod serialiserar resultat med hjälp av XmlSerializer.

När du använder föregående kod returnerar kontrollantmetoder lämpligt format baserat på begärandehuvudet Accept .

Konfigurera formaterare baserade på System.Text.Json

Funktioner för de System.Text.Json baserade formatrarna kan konfigureras med hjälp av Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Standardformateringen är camelCase. Följande markerade kod använder PascalCase-formattering:

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

Följande åtgärdsmetod anropar ControllerBase.Problem för att skapa ett ProblemDetails svar:

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

Med föregående kod:

  • https://localhost:5001/WeatherForecast/temperature returnerar PascalCase.
  • https://localhost:5001/WeatherForecast/error returnerar camelCase. Felsvaret är alltid camelCase, även när appen anger formatet till PascalCase. ProblemDetails följer RFC 7807, som anger gemener för text/bokstäver

Följande kod anger PascalCase och lägger till en anpassad konverterare:

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

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

Serialiseringsalternativ för utdata kan konfigureras per åtgärd med hjälp av JsonResult. Till exempel:

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

Lägg till Newtonsoft.Json-baserat JSON-formatstöd

JSON-standardformatrarna baseras på System.Text.Json. Stöd för Newtonsoft.Json-baserade formaterare och funktioner är tillgängligt genom installation av Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-paketet och konfigurering i Startup.ConfigureServices.

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

I föregående kod konfigurerar anropet till AddNewtonsoftJson följande webb-API,MVC- och Razor Pages-funktioner för att använda Newtonsoft.Json:

Vissa funktioner kanske inte fungerar bra med System.Text.Json-baserade formatare och kräver en referens till de Newtonsoft.Json-baserade formatrarna. Fortsätt att använda Newtonsoft.Json-baserade formaterare när appen:

  • Använder Newtonsoft.Json attribut. Till exempel [JsonProperty] eller [JsonIgnore].
  • Anpassar serialiseringsinställningarna.
  • Förlitar sig på funktioner som Newtonsoft.Json tillhandahåller.

Funktioner för de Newtonsoft.Json-baserade formatrarna kan konfigureras med hjälp av Microsoft.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());
});

Serialiseringsalternativ för utdata kan konfigureras per åtgärd med hjälp av JsonResult. Till exempel:

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

Ange ett format

Använd filtret för att begränsa svarsformaten [Produces] . Precis som de flesta filter kan [Produces] tillämpas på åtgärden, kontrollern eller det globala omfånget:

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

Föregående [Produces] filter:

  • Tvingar alla åtgärder i kontrollanten att returnera JSON-formaterade svar för POCOs (vanliga gamla CLR-objekt) eller ObjectResult dess härledda typer.
  • Om andra formaterare har konfigurerats och klienten anger ett annat format returneras JSON.

Mer information finns i Filter.

Särskilda formatinställningar

Vissa specialfall implementeras med hjälp av inbyggda formatters. Som standardinställning formateras returtyperna som string (text/html om det begärs via -huvudet). Det här beteendet kan tas bort genom att ta bort StringOutputFormatter. Formaterare tas bort i ConfigureServices -metoden. Åtgärder som har en modellobjektreturtyp returneras 204 No Content när du returnerar null. Det här beteendet kan tas bort genom att ta bort HttpNoContentOutputFormatter. Följande kod tar StringOutputFormatter bort och HttpNoContentOutputFormatter.

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

Utan StringOutputFormatter formaterar den inbyggda JSON-formatören string returtyper. Om den inbyggda JSON-formateren tas bort och en XML-formaterare är tillgänglig returnerar XML-formateringsformaten string typer. Annars returnerar returtyper string406 Not Acceptable.

HttpNoContentOutputFormatterUtan formateras null-objekten med den konfigurerade formateren. Till exempel:

  • JSON-formaterare returnerar ett svar med en brödtext av null.
  • XML-formaterare returnerar ett tomt XML-element med attributuppsättningen xsi:nil="true" .

Svarsformatets URL-mappningar

Klienter kan begära ett visst format som en del av URL:en, till exempel:

  • I frågesträngen eller en del av sökvägen.
  • Genom att använda ett formatspecifikt filnamnstillägg som .xml eller .json.

Mappningen från begärans sökväg bör specificeras i den rutt som API:et använder. Till exempel:

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

Föregående väg gör att det begärda formatet kan anges som ett valfritt filnamnstillägg. Attributet [FormatFilter] kontrollerar om formatvärdet finns i RouteData och mappar svarsformatet till lämplig formatering när svaret skapas.

Route Formatter
/api/products/5 Standardutdataformaterare
/api/products/5.json JSON-formaterare (om den är konfigurerad)
/api/products/5.xml XML-formaterare (om den är konfigurerad)

ASP.NET Core MVC stöder formatering av svarsdata, med angivna format eller som svar på en klients begäran.

Formatspecifika åtgärdsresultat

Vissa typer av åtgärdsresultat är specifika för ett visst format, till exempel JsonResult och ContentResult. Åtgärder kan returnera resultat som alltid använder ett angivet format och ignorerar en klients begäran om ett annat format. Om du till exempel returnerar JsonResult returneras JSON-formaterade data och returnerar ContentResult returneras strängar med oformaterad text.

En åtgärd krävs inte för att returnera någon specifik typ. ASP.NET Core stöder alla objektreturvärden. Resultat från åtgärder som returnerar objekt som inte är av IActionResult-typer serialiseras med lämpliga IOutputFormatter-implementeringar. Mer information finns i Returnera typer av kontrollantåtgärder i ASP.NET Core-webb-API.

Som standard returnerar den inbyggda hjälpmetoden ControllerBase.Ok JSON-formaterade data:

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

Exempelkoden returnerar en lista över att göra-objekt. Använd utvecklarverktygen för F12-webbläsaren eller http-repl med föregående kod:

  • Svarshuvudet som innehåller innehållstyp:application/json; charset=utf-8.
  • Begärandehuvuden. Till exempel Accept rubriken. Rubriken Accept ignoreras av föregående kod.

Om du vill returnera oformaterade data använder du ContentResult och hjälpverktyget Content :

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

I föregående kod returneras Content-Type som text/plain.

För åtgärder med flera returtyper returnerar du IActionResult. När du till exempel returnerar olika HTTP-statuskoder baserat på resultatet av åtgärden.

Innehållsförhandling

Innehållsförhandling sker när klienten anger ett Accept-huvud. Standardformatet som används av ASP.NET Core är JSON. Innehållsförhandling är:

  • Implementerad av ObjectResult.
  • Inbyggt i statuskodsspecifika åtgärdsresultat som returneras från hjälpmetoderna. Hjälpmetoderna för åtgärdsresultat baseras på ObjectResult.

När en modelltyp returneras är returtypen ObjectResult.

Följande åtgärdsmetod använder hjälpmetoderna Ok och NotFound :

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

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

    return Ok(todo);
}

Som standard stöder ASP.NET Core följande medietyper:

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

Verktyg som Fiddler eller http-repl kan ange Accept begärandehuvudet för att ange returformatet. Accept Om headern innehåller en typ som servern stöder returneras den typen. I nästa avsnitt visas hur du lägger till ytterligare formaterare.

Kontrolleråtgärder kan returnera POCOs (vanliga gamla CLR-objekt). När en POCO returneras skapar körningsmiljön automatiskt en ObjectResult som omsluter objektet. Klienten hämtar det formaterade serialiserade objektet. Om objektet som returneras är nullreturneras ett 204 No Content svar.

I följande exempel returneras en objekttyp:

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

I föregående kod returnerar en förfrågan om ett giltigt objekt ett 200 OK svar. En begäran om ett ogiltigt uppgiftsobjekt returnerar en 204 No Content svarskod.

Sidhuvudet Acceptera

Innehållsförhandling sker när en Accept rubrik visas i begäran. När en begäran innehåller ett accepthuvud ASP.NET Core:

  • Räknar upp medietyperna i accepthuvudet i inställningsordning.
  • Försöker hitta en formaterare som kan skapa ett svar i något av de angivna formaten.

Om det inte finns någon formatering som kan uppfylla klientens begäran ASP.NET Core:

Om ingen formatering har konfigurerats för det begärda formatet används den första formaterare som kan formatera objektet. Om inget Accept huvud visas i begäran:

  • Den första formaterare som kan hantera objektet används för att serialisera svaret.
  • Det pågår inga förhandlingar. Servern avgör vilket format som ska returneras.

Om Accept-rubriken innehåller */* ignoreras rubriken, såvida inte RespectBrowserAcceptHeader är inställt på sant på MvcOptions.

Webbläsare och innehållsförhandling

Till skillnad från vanliga API-klienter levererar webbläsare Accept rubriker. Webbläsare anger många format, inklusive jokertecken. När ramverket som standard identifierar att begäran kommer från en webbläsare:

  • Rubriken Accept ignoreras.
  • Innehållet returneras i JSON, om inget annat har konfigurerats.

Den här metoden ger en mer konsekvent upplevelse i webbläsare när du använder API:er.

Om du vill konfigurera en app så att den respekterar webbläsarens accepthuvuden RespectBrowserAcceptHeader anger du egenskapen till true:

var builder = WebApplication.CreateBuilder(args);

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

Konfigurera formaterare

Appar som behöver stöd för extra format kan lägga till lämpliga NuGet-paket och konfigurera support. Det finns separata formaterare för in- och utdata. Indataformaterare används av modellbindning. Utdataformaterare används för att formatera svar. Information om hur du skapar en anpassad formatering finns i Anpassade formatters.

Lägg till stöd för XML-format

Om du vill konfigurera XML-formaterare som implementerats med hjälp av XmlSerializeranropar du AddXmlSerializerFormatters:

var builder = WebApplication.CreateBuilder(args);

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

När du använder föregående kod returnerar kontrollantmetoder lämpligt format baserat på begärandehuvudet Accept .

Konfigurera System.Text.Json-baserade formatters

För att konfigurera funktioner för System.Text.Json-baserade formatrar, använd Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Följande markerade kod konfigurerar PascalCase-formatering i stället för standardformatering av camelCase:

var builder = WebApplication.CreateBuilder(args);

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

Om du vill konfigurera alternativ för utdatas serialisering för specifika åtgärder använder du JsonResult. Till exempel:

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

Stöd för Newtonsoft.Json-baserat JSON-format

JSON-standardformaterarna använder System.Text.Json. Om du vill använda de Newtonsoft.Json-baserade formatrarna installerar Microsoft.AspNetCore.Mvc.NewtonsoftJson du NuGet-paketet och konfigurerar det i Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

I föregående kod konfigurerar anropet till AddNewtonsoftJson följande webb-API,MVC- och Razor Pages-funktioner för att använda Newtonsoft.Json:

Vissa funktioner kanske inte fungerar bra med System.Text.Json-baserade formatare och kräver en referens till de Newtonsoft.Json-baserade formatrarna. Fortsätt att använda Newtonsoft.Json-baserade formaterare när appen:

  • Använder Newtonsoft.Json attribut. Till exempel [JsonProperty] eller [JsonIgnore].
  • Anpassar serialiseringsinställningarna.
  • Förlitar sig på funktioner som Newtonsoft.Json tillhandahåller.

Om du vill konfigurera funktioner för de Newtonsoft.Json-baserade formatrarna använder du SerializerSettings:

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

Om du vill konfigurera alternativ för utdatas serialisering för specifika åtgärder använder du JsonResult. Till exempel:

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

svar Format ProblemDetails och ValidationProblemDetails

Följande åtgärdsmetod anropar ControllerBase.Problem för att skapa ett ProblemDetails svar:

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

Ett ProblemDetails svar är alltid camelCase, även när appen anger formatet till PascalCase. ProblemDetails följer RFC 7807, som specificerar användning av gemener.

[ApiController] När attributet tillämpas på en kontrollantklass skapar kontrollanten ett ValidationProblemDetails svar när modellverifieringen misslyckas. Det här svaret innehåller en ordlista som använder modellens egenskapsnamn som felnycklar, oförändrade. Följande modell innehåller till exempel en enda egenskap som kräver validering:

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

Som standard använder svaret ValidationProblemDetails som returneras när egenskapen Value är ogiltig felnyckeln Value, som visas i följande exempel:

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

Om du vill formatera de egenskapsnamn som används som felnycklar lägger du till en implementering av IMetadataDetailsProvider i MvcOptions.ModelMetadataDetailsProviders samlingen. I följande exempel läggs en System.Text.Json-baserad implementering, SystemTextJsonValidationMetadataProvider, som formaterar egenskapsnamn som camelCase som standard:

builder.Services.AddControllers();

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

SystemTextJsonValidationMetadataProvider accepterar också en implementering av JsonNamingPolicy i sin konstruktor, som anger en anpassad namngivningsprincip för formatering av egenskapsnamn.

Om du vill ange ett anpassat namn för en egenskap i en modell använder du attributet [JsonPropertyName] på egenskapen:

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

Svaret ValidationProblemDetails som returnerades för föregående modell när Value egenskapen är ogiltig använder en felnyckel på sampleValue, som du ser i följande exempel:

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

Om du vill formatera svaret ValidationProblemDetails med Newtonsoft.Json, använd NewtonsoftJsonValidationMetadataProvider:

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

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

Som standardinställning, formaterar NewtonsoftJsonValidationMetadataProvider egenskapsnamnen som camelCase. NewtonsoftJsonValidationMetadataProvider accepterar också en implementering av NamingPolicy i sin konstruktor, som anger en anpassad namngivningsprincip för formatering av egenskapsnamn. Om du vill ange ett anpassat namn för en egenskap i en modell använder du attributet [JsonProperty] .

Ange ett format

Använd filtret för att begränsa svarsformaten [Produces] . Precis som de flesta filter kan [Produces] tillämpas på åtgärden, kontrollern eller det globala omfånget:

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

Föregående [Produces] filter:

  • Tvingar alla åtgärder i kontrollanten att returnera JSON-formaterade svar för POCOs (vanliga gamla CLR-objekt) eller ObjectResult dess härledda typer.
  • Returnera JSON-formaterade svar även om andra formaterare har konfigurerats och klienten anger ett annat format.

Mer information finns i Filter.

Särskilda formatinställningar

Vissa specialfall implementeras med hjälp av inbyggda formatters. Som standardinställning formateras returtyperna som string (text/html om det begärs via -huvudet). Det här beteendet kan tas bort genom att ta bort StringOutputFormatter. Formaterare tas bort i Program.cs. Åtgärder som har en modellobjektreturtyp returneras 204 No Content när du returnerar null. Det här beteendet kan tas bort genom att ta bort HttpNoContentOutputFormatter. Följande kod tar StringOutputFormatter bort och HttpNoContentOutputFormatter.

var builder = WebApplication.CreateBuilder(args);

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

Utan StringOutputFormatter formaterar den inbyggda JSON-formatören string returtyper. Om den inbyggda JSON-formateren tas bort och en XML-formaterare är tillgänglig returnerar XML-formateringsformaten string typer. Annars returnerar returtyper string406 Not Acceptable.

HttpNoContentOutputFormatterUtan formateras null-objekten med den konfigurerade formateren. Till exempel:

  • JSON-formaterare returnerar ett svar med en brödtext av null.
  • XML-formaterare returnerar ett tomt XML-element med attributuppsättningen xsi:nil="true" .

Svarsformatets URL-mappningar

Klienter kan begära ett visst format som en del av URL:en, till exempel:

  • I frågesträngen eller en del av sökvägen.
  • Genom att använda ett formatspecifikt filnamnstillägg som .xml eller .json.

Mappningen från begärans sökväg bör specificeras i den rutt som API:et använder. Till exempel:

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

Föregående väg gör att det begärda formatet kan anges med hjälp av ett valfritt filnamnstillägg. Attributet [FormatFilter] kontrollerar om formatvärdet finns i RouteData och mappar svarsformatet till lämplig formatering när svaret skapas.

Route Formatter
/api/todoitems/5 Standardutdataformaterare
/api/todoitems/5.json JSON-formaterare (om den är konfigurerad)
/api/todoitems/5.xml XML-formaterare (om den är konfigurerad)

Polymorf deserialisering

Inbyggda funktioner ger ett begränsat utbud av polymorf serialisering men inget stöd för deserialisering alls. Deserialisering kräver en anpassad konverterare. Se Polymorf deserialisering för ett komplett urval av polymorfisk deserialisering.

Ytterligare resurser