Delen via

Antwoordgegevens opmaken in ASP.NET Core Web-API

ASP.NET Core MVC ondersteunt het opmaken van antwoordgegevens, met behulp van opgegeven indelingen of in reactie op de aanvraag van een client.

Opmaakspecifieke actieresultaten

Sommige typen actieresultaten zijn specifiek voor een bepaalde indeling, zoals JsonResult en ContentResult. Acties kunnen resultaten retourneren die altijd een opgegeven indeling gebruiken, waarbij de aanvraag van een client voor een andere indeling wordt genegeerd. Als u bijvoorbeeld JsonResult JSON-geformatteerde gegevens retourneert en ContentResult tekenreeksgegevens zonder opmaak retourneert.

Een actie is niet vereist om een specifiek type te retourneren. ASP.NET Core ondersteunt elke retourwaarde van objecten. Resultaten van acties die objecten retourneren die geen IActionResult typen zijn, worden geserialiseerd met behulp van de juiste IOutputFormatter implementatie. Zie Retourtypen controlleractie in ASP.NET Core-web-API voor meer informatie.

Standaard retourneert de ingebouwde helpermethode ControllerBase.Ok JSON-geformatteerde gegevens:

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

De voorbeeldcode retourneert een lijst met takenitems. Met behulp van de ontwikkelhulpprogramma's van de F12-browser of http-repl met de vorige code wordt het volgende weergegeven:

  • De antwoordheader met inhoudstype:application/json; charset=utf-8.
  • De aanvraagheaders. Bijvoorbeeld de Accept koptekst. De Accept header wordt genegeerd door de voorgaande code.

Als u opgemaakte gegevens zonder opmaak wilt retourneren, gebruikt ContentResult u en de Content helper:

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

In de voorgaande code is text/plainde Content-Type geretourneerde waarde.

Voor acties met meerdere retourtypen, retour IActionResult. Als u bijvoorbeeld verschillende HTTP-statuscodes retourneert op basis van het resultaat van de bewerking.

Content negotiation

Inhoudsonderhandeling vindt plaats wanneer de client een Accept-header opgeeft. De standaardindeling die wordt gebruikt door ASP.NET Core is JSON. Inhoudsonderhandeling is:

  • Geïmplementeerd door ObjectResult.
  • Ingebouwd in de statuscodespecifieke actieresultaten die worden geretourneerd door de helpermethoden. De helpermethoden voor actieresultaten zijn gebaseerd op ObjectResult.

Wanneer een modeltype wordt geretourneerd, is ObjectResulthet retourtype.

De volgende actiemethode maakt gebruik van de Ok en NotFound helpermethoden:

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

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

    return Ok(todo);
}

Standaard ondersteunt ASP.NET Core de volgende mediatypen:

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

Hulpprogramma's zoals Fiddler of curl kunnen de Accept aanvraagheader instellen om de retourindeling op te geven. Wanneer de Accept header een type bevat dat door de server wordt ondersteund, wordt dat type geretourneerd. In de volgende sectie ziet u hoe u extra formatters toevoegt.

Controlleracties kunnen POCO's (gewone oude CLR-objecten) retourneren. Wanneer een POCO wordt geretourneerd, maakt de runtime automatisch een ObjectResult object dat het object verpakt. De client haalt het opgemaakte geserialiseerde object op. Als het geretourneerde object is null, wordt er een 204 No Content antwoord geretourneerd.

In het volgende voorbeeld wordt een objecttype geretourneerd:

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

In de voorgaande code retourneert een aanvraag voor een geldig todo-item een 200 OK antwoord. Een aanvraag voor een ongeldig taakitem retourneert een 204 No Content antwoord.

De kopTekst Accepteren

Inhoudsonderhandeling vindt plaats wanneer er een Accept header wordt weergegeven in de aanvraag. Wanneer een aanvraag een acceptheader bevat, ASP.NET Core:

  • Opsomming van de mediatypen in de accept-header in voorkeursvolgorde.
  • Hiermee wordt geprobeerd een formatter te vinden die een antwoord kan produceren in een van de opgegeven indelingen.

Als er geen formatter wordt gevonden die aan de aanvraag van de client kan voldoen, ASP.NET Core:

  • Retourneert 406 Not Acceptable als MvcOptions.ReturnHttpNotAcceptable deze is ingesteld op true, of -
  • Hiermee wordt geprobeerd de eerste formatter te vinden die een antwoord kan produceren.

Als er geen formatter is geconfigureerd voor de aangevraagde indeling, wordt de eerste formatter gebruikt waarmee het object kan worden opgemaakt. Als er geen Accept header wordt weergegeven in de aanvraag:

  • De eerste formatter die het object kan verwerken, wordt gebruikt om het antwoord te serialiseren.
  • Er vindt geen onderhandeling plaats. De server bepaalt welke indeling moet worden geretourneerd.

Als de kopTekst Accepteren bevat */*, wordt de koptekst genegeerd, tenzij RespectBrowserAcceptHeader deze is ingesteld op waar op MvcOptions.

Browsers en inhoudsonderhandeling

In tegenstelling tot typische API-clients leveren Accept webbrowsers headers. Webbrowsers geven veel indelingen op, waaronder jokertekens. Wanneer het framework standaard detecteert dat de aanvraag afkomstig is van een browser:

  • De Accept koptekst wordt genegeerd.
  • De inhoud wordt geretourneerd in JSON, tenzij anders geconfigureerd.

Deze benadering biedt een consistentere ervaring in browsers bij het gebruik van API's.

Als u een app wilt configureren voor het respecteren van browserheaders, stelt u de RespectBrowserAcceptHeader eigenschap truein op:

var builder = WebApplication.CreateBuilder(args);

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

Configure formatters

Apps die extra indelingen moeten ondersteunen, kunnen de juiste NuGet-pakketten toevoegen en ondersteuning configureren. Er zijn afzonderlijke formatters voor invoer en uitvoer. Invoerindelingen worden gebruikt door Modelbinding. Uitvoerindelingen worden gebruikt om antwoorden op te maken. Zie Custom Formatters voor meer informatie over het maken van een aangepaste formatter.

Ondersteuning voor XML-indeling toevoegen

Als u XML-formatters wilt configureren die zijn geïmplementeerd met behulp van XmlSerializer, roept u het volgende AddXmlSerializerFormattersaan:

var builder = WebApplication.CreateBuilder(args);

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

Wanneer u de voorgaande code gebruikt, retourneren controllermethoden de juiste indeling op basis van de header van Accept de aanvraag.

Op -gebaseerde formatters configureren System.Text.Json

Als u functies voor de System.Text.Jsonop -gebaseerde formatters wilt configureren, gebruikt u Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Met de volgende gemarkeerde code wordt PascalCase-opmaak geconfigureerd in plaats van de standaardopmaak van camelCase:

var builder = WebApplication.CreateBuilder(args);

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

Met de volgende actiemethode wordt ControllerBase.Problem een ProblemDetails antwoord gemaakt:

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

Een ProblemDetails antwoord is altijd camelCase, zelfs wanneer de app de indeling instelt op PascalCase. ProblemDetails volgt RFC 7807, dat kleine letters aangeeft.

Als u uitvoerserialisatieopties voor specifieke acties wilt configureren, gebruikt u JsonResult. For example:

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

Ondersteuning voor JSON-indeling toevoegen Newtonsoft.Json

De standaard JSON-formatters gebruiken System.Text.Json. Als u de Newtonsoft.Jsonop -gebaseerde formatters wilt gebruiken, installeert u het Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-pakket en configureert u het in Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

In de voorgaande code configureert de aanroep om de volgende web-API-, MVC- en Pages-functies te AddNewtonsoftJson configureren voor gebruikNewtonsoft.Json:Razor

Sommige functies werken mogelijk niet goed met System.Text.Jsonformatters op basis van -en vereisen een verwijzing naar de Newtonsoft.Jsonop -gebaseerde formatters. Blijf de Newtonsoft.Jsonop -gebaseerde formatters gebruiken wanneer de app:

  • Maakt gebruik van Newtonsoft.Json kenmerken. Een voorbeeld hiervan is [JsonProperty] of [JsonIgnore].
  • Hiermee past u de serialisatie-instellingen aan.
  • Is afhankelijk van functies die Newtonsoft.Json bieden.

Als u functies voor de Newtonsoft.Jsonop -gebaseerde formatters wilt configureren, gebruikt u SerializerSettings:

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

Als u uitvoerserialisatieopties voor specifieke acties wilt configureren, gebruikt u JsonResult. For example:

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

Een indeling opgeven

Als u de antwoordindelingen wilt beperken, past u het [Produces] filter toe. Net als bij de meeste filters[Produces] kunt u deze toepassen op de actie, controller of globaal bereik:

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

Het voorgaande [Produces] filter:

  • Dwingt alle acties binnen de controller af om JSON-geformatteerde antwoorden te retourneren voor POCOs (gewone oude CLR-objecten) of ObjectResult de afgeleide typen.
  • Retourneer JSON-opgemaakte antwoorden, zelfs als andere formatters zijn geconfigureerd en de client een andere indeling opgeeft.

Zie Filters voor meer informatie.

Speciale case formatters

Sommige speciale gevallen worden geïmplementeerd met behulp van ingebouwde formatters. string Standaard worden retourtypen opgemaakt als tekst/tekst zonder opmaak (tekst/html indien aangevraagd via de Accept koptekst). Dit gedrag kan worden verwijderd door de StringOutputFormatter. Formatters worden verwijderd in Program.cs. Acties met een retourtype modelobject retourneren wanneer ze worden geretourneerd 204 No Contentnull. Dit gedrag kan worden verwijderd door de HttpNoContentOutputFormatter. Met de volgende code worden de StringOutputFormatter en HttpNoContentOutputFormatter.

var builder = WebApplication.CreateBuilder(args);

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

Zonder de StringOutputFormatter, de ingebouwde JSON formatter formatter formats retourneert string typen. Als de ingebouwde JSON-indeling wordt verwijderd en er een XML-formatter beschikbaar is, retourneert de XML-formatter-indelingen string typen. string Anders retourneren 406 Not Acceptableretourtypen.

Zonder de HttpNoContentOutputFormatternotatie worden null-objecten opgemaakt met behulp van de geconfigureerde formatter. For example:

  • De JSON-formatter retourneert een antwoord met een hoofdtekst van null.
  • De XML-formatter retourneert een leeg XML-element met de kenmerkset xsi:nil="true" .

URL-toewijzingen voor antwoordindeling

Clients kunnen een bepaalde indeling aanvragen als onderdeel van de URL, bijvoorbeeld:

  • In de querytekenreeks of een deel van het pad.
  • Door een indelingsspecifieke bestandsextensie te gebruiken, zoals .xml of .json.

De toewijzing van het aanvraagpad moet worden opgegeven in de route die de API gebruikt. For example:

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

Met de voorgaande route kan de aangevraagde indeling worden opgegeven met behulp van een optionele bestandsextensie. Het [FormatFilter] kenmerk controleert op het bestaan van de notatiewaarde in de RouteData en wijst de antwoordindeling toe aan de juiste notatie wanneer het antwoord wordt gemaakt.

Route Formatter
/api/todoitems/5 De standaarduitvoerindeling
/api/todoitems/5.json De JSON-formatter (indien geconfigureerd)
/api/todoitems/5.xml De XML-indeling (indien geconfigureerd)

Polymorphic deserialization

Ingebouwde functies bieden een beperkt scala aan polymorfische serialisatie, maar helemaal geen ondersteuning voor deserialisatie. Voor deserialisatie is een aangepast conversieprogramma vereist. Zie Polymorfische deserialisatie voor een volledig voorbeeld van polymorfische deserialisatie.

Additional resources

ASP.NET Core MVC biedt ondersteuning voor het opmaken van antwoordgegevens. Antwoordgegevens kunnen worden opgemaakt met behulp van specifieke indelingen of als reactie op de aangevraagde indeling van de client.

Voorbeeldcode bekijken of downloaden (hoe download je)

Opmaakspecifieke actieresultaten

Sommige typen actieresultaten zijn specifiek voor een bepaalde indeling, zoals JsonResult en ContentResult. Acties kunnen resultaten retourneren die zijn opgemaakt in een bepaalde indeling, ongeacht de clientvoorkeuren. Retourneert bijvoorbeeld JsonResult JSON-geformatteerde gegevens. Retourneert ContentResult of een tekenreeks retourneert tekenreeksgegevens met tekst zonder opmaak.

Een actie is niet vereist om een specifiek type te retourneren. ASP.NET Core ondersteunt elke retourwaarde van objecten. Resultaten van acties die objecten retourneren die geen IActionResult typen zijn, worden geserialiseerd met behulp van de juiste IOutputFormatter implementatie. Zie Retourtypen controlleractie in ASP.NET Core-web-API voor meer informatie.

De ingebouwde helpermethode Ok retourneert JSON-geformatteerde gegevens:

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

De voorbeelddownload retourneert de lijst met auteurs. Gebruik de ontwikkelhulpprogramma's van de F12-browser of http-repl met de vorige code:

  • De antwoordheader met het inhoudstype:application/json; charset=utf-8 wordt weergegeven.
  • De aanvraagheaders worden weergegeven. Bijvoorbeeld de Accept koptekst. De Accept header wordt genegeerd door de voorgaande code.

Als u opgemaakte gegevens zonder opmaak wilt retourneren, gebruikt ContentResult u en de Content helper:

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

In de voorgaande code is text/plainde Content-Type geretourneerde waarde. Retourneert een tekenreeks van Content-Typetext/plain:

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

Voor acties met meerdere retourtypen, retour IActionResult. Bijvoorbeeld het retourneren van verschillende HTTP-statuscodes op basis van het resultaat van uitgevoerde bewerkingen.

Content negotiation

Inhoudsonderhandeling vindt plaats wanneer de client een Accept-header opgeeft. De standaardindeling die wordt gebruikt door ASP.NET Core is JSON. Inhoudsonderhandeling is:

  • Geïmplementeerd door ObjectResult.
  • Ingebouwd in de statuscodespecifieke actieresultaten die worden geretourneerd door de helpermethoden. De helpermethoden voor actieresultaten zijn gebaseerd op ObjectResult.

Wanneer een modeltype wordt geretourneerd, is ObjectResulthet retourtype.

De volgende actiemethode maakt gebruik van de Ok en NotFound helpermethoden:

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

Standaard ondersteunt application/jsontext/jsonASP.NET Core mediatypen en text/plain mediatypen. Hulpprogramma's zoals Fiddler of http-repl kunnen de Accept aanvraagheader instellen om de retourindeling op te geven. Wanneer de Accept header een type bevat dat door de server wordt ondersteund, wordt dat type geretourneerd. In de volgende sectie ziet u hoe u extra formatters toevoegt.

Controlleracties kunnen POCO's (gewone oude CLR-objecten) retourneren. Wanneer een POCO wordt geretourneerd, maakt de runtime automatisch een ObjectResult object dat het object verpakt. De client haalt het opgemaakte geserialiseerde object op. Als het geretourneerde object is null, wordt er een 204 No Content antwoord geretourneerd.

Een objecttype retourneren:

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

In de voorgaande code retourneert een aanvraag voor een geldige auteursalias een 200 OK antwoord met de gegevens van de auteur. Een aanvraag voor een ongeldige alias retourneert een 204 No Content antwoord.

De kopTekst Accepteren

Inhoudsonderhandeling vindt plaats wanneer er een Accept header wordt weergegeven in de aanvraag. Wanneer een aanvraag een acceptheader bevat, ASP.NET Core:

  • Opsomming van de mediatypen in de accept-header in voorkeursvolgorde.
  • Hiermee wordt geprobeerd een formatter te vinden die een antwoord kan produceren in een van de opgegeven indelingen.

Als er geen formatter wordt gevonden die aan de aanvraag van de client kan voldoen, ASP.NET Core:

  • Retourneert 406 Not Acceptable als MvcOptions.ReturnHttpNotAcceptable deze is ingesteld op true, of -
  • Hiermee wordt geprobeerd de eerste formatter te vinden die een antwoord kan produceren.

Als er geen formatter is geconfigureerd voor de aangevraagde indeling, wordt de eerste formatter gebruikt waarmee het object kan worden opgemaakt. Als er geen Accept header wordt weergegeven in de aanvraag:

  • De eerste formatter die het object kan verwerken, wordt gebruikt om het antwoord te serialiseren.
  • Er vindt geen onderhandeling plaats. De server bepaalt welke indeling moet worden geretourneerd.

Als de kopTekst Accepteren bevat */*, wordt de koptekst genegeerd, tenzij RespectBrowserAcceptHeader deze is ingesteld op waar op MvcOptions.

Browsers en inhoudsonderhandeling

In tegenstelling tot typische API-clients leveren Accept webbrowsers headers. Webbrowsers geven veel indelingen op, waaronder jokertekens. Wanneer het framework standaard detecteert dat de aanvraag afkomstig is van een browser:

  • De Accept koptekst wordt genegeerd.
  • De inhoud wordt geretourneerd in JSON, tenzij anders geconfigureerd.

Deze benadering biedt een consistentere ervaring in browsers bij het gebruik van API's.

Als u een app wilt configureren voor het accepteren van headers in de browser, stelt u het volgende in RespectBrowserAcceptHeadertrue:

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

Configure formatters

Apps die aanvullende indelingen moeten ondersteunen, kunnen de juiste NuGet-pakketten toevoegen en ondersteuning configureren. Er zijn afzonderlijke formatters voor invoer en uitvoer. Invoerindelingen worden gebruikt door Modelbinding. Uitvoerindelingen worden gebruikt om antwoorden op te maken. Zie Custom Formatters voor meer informatie over het maken van een aangepaste formatter.

Ondersteuning voor XML-indeling toevoegen

XML-formatters die zijn geïmplementeerd met behulp XmlSerializer van, worden geconfigureerd door het aanroepen AddXmlSerializerFormattersvan:

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

De voorgaande code serialiseert resultaten met behulp van XmlSerializer.

Wanneer u de voorgaande code gebruikt, retourneren controllermethoden de juiste indeling op basis van de header van Accept de aanvraag.

Op basis van formatters configureren System.Text.Json

Functies voor de System.Text.Json gebaseerde formatters kunnen worden geconfigureerd met behulp van Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. De standaardopmaak is camelCase. Met de volgende gemarkeerde code wordt de PascalCase-opmaak ingesteld:

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

Met de volgende actiemethode wordt ControllerBase.Problem een ProblemDetails antwoord gemaakt:

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

Met de voorgaande code:

  • https://localhost:5001/WeatherForecast/temperature retourneert PascalCase.
  • https://localhost:5001/WeatherForecast/error retourneert camelCase. De foutreactie is altijd camelCase, zelfs wanneer de app de indeling instelt op PascalCase. ProblemDetails volgt RFC 7807, dat kleine letters aangeeft

Met de volgende code wordt PascalCase ingesteld en wordt een aangepast conversieprogramma toegevoegd:

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

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

Uitvoerserialisatieopties kunnen per actie worden geconfigureerd met behulp van JsonResult. For example:

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

Ondersteuning voor JSON-indeling op basis van Newtonsoft.Json toevoegen

De standaard JSON-formatters zijn gebaseerd op System.Text.Json. Ondersteuning voor Newtonsoft.Json op gebaseerde formatters en functies is beschikbaar door het Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-pakket te installeren en in Startup.ConfigureServiceste configureren.

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

In de voorgaande code configureert de aanroep om de volgende web-API-, MVC- en Pages-functies te AddNewtonsoftJson configureren voor gebruikNewtonsoft.Json:Razor

Sommige functies werken mogelijk niet goed met System.Text.Jsonformatters op basis van -en vereisen een verwijzing naar de Newtonsoft.Jsonop -gebaseerde formatters. Blijf de Newtonsoft.Jsonop -gebaseerde formatters gebruiken wanneer de app:

  • Maakt gebruik van Newtonsoft.Json kenmerken. Een voorbeeld hiervan is [JsonProperty] of [JsonIgnore].
  • Hiermee past u de serialisatie-instellingen aan.
  • Is afhankelijk van functies die Newtonsoft.Json bieden.

Functies voor de Newtonsoft.Jsonop -gebaseerde formatters kunnen worden geconfigureerd met behulp van 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());
});

Uitvoerserialisatieopties kunnen per actie worden geconfigureerd met behulp van JsonResult. For example:

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

Een indeling opgeven

Als u de antwoordindelingen wilt beperken, past u het [Produces] filter toe. Net als bij de meeste filters[Produces] kunt u deze toepassen op de actie, controller of globaal bereik:

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

Het voorgaande [Produces] filter:

  • Dwingt alle acties binnen de controller af om JSON-geformatteerde antwoorden te retourneren voor POCOs (gewone oude CLR-objecten) of ObjectResult de afgeleide typen.
  • Als andere formatters zijn geconfigureerd en de client een andere indeling opgeeft, wordt JSON geretourneerd.

Zie Filters voor meer informatie.

Speciale case formatters

Sommige speciale gevallen worden geïmplementeerd met behulp van ingebouwde formatters. string Standaard worden retourtypen opgemaakt als tekst/tekst zonder opmaak (tekst/html indien aangevraagd via de Accept koptekst). Dit gedrag kan worden verwijderd door de StringOutputFormatter. Formatters worden verwijderd in de ConfigureServices methode. Acties met een retourtype modelobject retourneren wanneer ze worden geretourneerd 204 No Contentnull. Dit gedrag kan worden verwijderd door de HttpNoContentOutputFormatter. Met de volgende code worden de StringOutputFormatter en HttpNoContentOutputFormatter.

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

Zonder de StringOutputFormatter, de ingebouwde JSON formatter formatter formats retourneert string typen. Als de ingebouwde JSON-indeling wordt verwijderd en er een XML-formatter beschikbaar is, retourneert de XML-formatter-indelingen string typen. string Anders retourneren 406 Not Acceptableretourtypen.

Zonder de HttpNoContentOutputFormatternotatie worden null-objecten opgemaakt met behulp van de geconfigureerde formatter. For example:

  • De JSON-formatter retourneert een antwoord met een hoofdtekst van null.
  • De XML-formatter retourneert een leeg XML-element met de kenmerkset xsi:nil="true" .

URL-toewijzingen voor antwoordindeling

Clients kunnen een bepaalde indeling aanvragen als onderdeel van de URL, bijvoorbeeld:

  • In de querytekenreeks of een deel van het pad.
  • Door een indelingsspecifieke bestandsextensie te gebruiken, zoals .xml of .json.

De toewijzing van het aanvraagpad moet worden opgegeven in de route die de API gebruikt. For example:

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

Met de voorgaande route kan de aangevraagde indeling worden opgegeven als een optionele bestandsextensie. Het [FormatFilter] kenmerk controleert op het bestaan van de notatiewaarde in de RouteData en wijst de antwoordindeling toe aan de juiste notatie wanneer het antwoord wordt gemaakt.

Route Formatter
/api/products/5 De standaarduitvoerindeling
/api/products/5.json De JSON-formatter (indien geconfigureerd)
/api/products/5.xml De XML-indeling (indien geconfigureerd)

ASP.NET Core MVC ondersteunt het opmaken van antwoordgegevens, met behulp van opgegeven indelingen of in reactie op de aanvraag van een client.

Opmaakspecifieke actieresultaten

Sommige typen actieresultaten zijn specifiek voor een bepaalde indeling, zoals JsonResult en ContentResult. Acties kunnen resultaten retourneren die altijd een opgegeven indeling gebruiken, waarbij de aanvraag van een client voor een andere indeling wordt genegeerd. Als u bijvoorbeeld JsonResult JSON-geformatteerde gegevens retourneert en ContentResult tekenreeksgegevens zonder opmaak retourneert.

Een actie is niet vereist om een specifiek type te retourneren. ASP.NET Core ondersteunt elke retourwaarde van objecten. Resultaten van acties die objecten retourneren die geen IActionResult typen zijn, worden geserialiseerd met behulp van de juiste IOutputFormatter implementatie. Zie Retourtypen controlleractie in ASP.NET Core-web-API voor meer informatie.

Standaard retourneert de ingebouwde helpermethode ControllerBase.Ok JSON-geformatteerde gegevens:

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

De voorbeeldcode retourneert een lijst met takenitems. Met behulp van de ontwikkelhulpprogramma's van de F12-browser of http-repl met de vorige code wordt het volgende weergegeven:

  • De antwoordheader met inhoudstype:application/json; charset=utf-8.
  • De aanvraagheaders. Bijvoorbeeld de Accept koptekst. De Accept header wordt genegeerd door de voorgaande code.

Als u opgemaakte gegevens zonder opmaak wilt retourneren, gebruikt ContentResult u en de Content helper:

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

In de voorgaande code is text/plainde Content-Type geretourneerde waarde.

Voor acties met meerdere retourtypen, retour IActionResult. Als u bijvoorbeeld verschillende HTTP-statuscodes retourneert op basis van het resultaat van de bewerking.

Content negotiation

Inhoudsonderhandeling vindt plaats wanneer de client een Accept-header opgeeft. De standaardindeling die wordt gebruikt door ASP.NET Core is JSON. Inhoudsonderhandeling is:

  • Geïmplementeerd door ObjectResult.
  • Ingebouwd in de statuscodespecifieke actieresultaten die worden geretourneerd door de helpermethoden. De helpermethoden voor actieresultaten zijn gebaseerd op ObjectResult.

Wanneer een modeltype wordt geretourneerd, is ObjectResulthet retourtype.

De volgende actiemethode maakt gebruik van de Ok en NotFound helpermethoden:

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

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

    return Ok(todo);
}

Standaard ondersteunt ASP.NET Core de volgende mediatypen:

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

Hulpprogramma's zoals Fiddler of http-repl kunnen de Accept aanvraagheader instellen om de retourindeling op te geven. Wanneer de Accept header een type bevat dat door de server wordt ondersteund, wordt dat type geretourneerd. In de volgende sectie ziet u hoe u extra formatters toevoegt.

Controlleracties kunnen POCO's (gewone oude CLR-objecten) retourneren. Wanneer een POCO wordt geretourneerd, maakt de runtime automatisch een ObjectResult object dat het object verpakt. De client haalt het opgemaakte geserialiseerde object op. Als het geretourneerde object is null, wordt er een 204 No Content antwoord geretourneerd.

In het volgende voorbeeld wordt een objecttype geretourneerd:

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

In de voorgaande code retourneert een aanvraag voor een geldig todo-item een 200 OK antwoord. Een aanvraag voor een ongeldig taakitem retourneert een 204 No Content antwoord.

De kopTekst Accepteren

Inhoudsonderhandeling vindt plaats wanneer er een Accept header wordt weergegeven in de aanvraag. Wanneer een aanvraag een acceptheader bevat, ASP.NET Core:

  • Opsomming van de mediatypen in de accept-header in voorkeursvolgorde.
  • Hiermee wordt geprobeerd een formatter te vinden die een antwoord kan produceren in een van de opgegeven indelingen.

Als er geen formatter wordt gevonden die aan de aanvraag van de client kan voldoen, ASP.NET Core:

  • Retourneert 406 Not Acceptable als MvcOptions.ReturnHttpNotAcceptable deze is ingesteld op true, of -
  • Hiermee wordt geprobeerd de eerste formatter te vinden die een antwoord kan produceren.

Als er geen formatter is geconfigureerd voor de aangevraagde indeling, wordt de eerste formatter gebruikt waarmee het object kan worden opgemaakt. Als er geen Accept header wordt weergegeven in de aanvraag:

  • De eerste formatter die het object kan verwerken, wordt gebruikt om het antwoord te serialiseren.
  • Er vindt geen onderhandeling plaats. De server bepaalt welke indeling moet worden geretourneerd.

Als de kopTekst Accepteren bevat */*, wordt de koptekst genegeerd, tenzij RespectBrowserAcceptHeader deze is ingesteld op waar op MvcOptions.

Browsers en inhoudsonderhandeling

In tegenstelling tot typische API-clients leveren Accept webbrowsers headers. Webbrowsers geven veel indelingen op, waaronder jokertekens. Wanneer het framework standaard detecteert dat de aanvraag afkomstig is van een browser:

  • De Accept koptekst wordt genegeerd.
  • De inhoud wordt geretourneerd in JSON, tenzij anders geconfigureerd.

Deze benadering biedt een consistentere ervaring in browsers bij het gebruik van API's.

Als u een app wilt configureren voor het respecteren van browserheaders, stelt u de RespectBrowserAcceptHeader eigenschap truein op:

var builder = WebApplication.CreateBuilder(args);

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

Configure formatters

Apps die extra indelingen moeten ondersteunen, kunnen de juiste NuGet-pakketten toevoegen en ondersteuning configureren. Er zijn afzonderlijke formatters voor invoer en uitvoer. Invoerindelingen worden gebruikt door Modelbinding. Uitvoerindelingen worden gebruikt om antwoorden op te maken. Zie Custom Formatters voor meer informatie over het maken van een aangepaste formatter.

Ondersteuning voor XML-indeling toevoegen

Als u XML-formatters wilt configureren die zijn geïmplementeerd met behulp van XmlSerializer, roept u het volgende AddXmlSerializerFormattersaan:

var builder = WebApplication.CreateBuilder(args);

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

Wanneer u de voorgaande code gebruikt, retourneren controllermethoden de juiste indeling op basis van de header van Accept de aanvraag.

Op -gebaseerde formatters configureren System.Text.Json

Als u functies voor de System.Text.Jsonop -gebaseerde formatters wilt configureren, gebruikt u Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Met de volgende gemarkeerde code wordt PascalCase-opmaak geconfigureerd in plaats van de standaardopmaak van camelCase:

var builder = WebApplication.CreateBuilder(args);

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

Als u uitvoerserialisatieopties voor specifieke acties wilt configureren, gebruikt u JsonResult. For example:

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

Ondersteuning voor JSON-indeling toevoegen Newtonsoft.Json

De standaard JSON-formatters gebruiken System.Text.Json. Als u de Newtonsoft.Jsonop -gebaseerde formatters wilt gebruiken, installeert u het Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-pakket en configureert u het in Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

In de voorgaande code configureert de aanroep om de volgende web-API-, MVC- en Pages-functies te AddNewtonsoftJson configureren voor gebruikNewtonsoft.Json:Razor

Sommige functies werken mogelijk niet goed met System.Text.Jsonformatters op basis van -en vereisen een verwijzing naar de Newtonsoft.Jsonop -gebaseerde formatters. Blijf de Newtonsoft.Jsonop -gebaseerde formatters gebruiken wanneer de app:

  • Maakt gebruik van Newtonsoft.Json kenmerken. Een voorbeeld hiervan is [JsonProperty] of [JsonIgnore].
  • Hiermee past u de serialisatie-instellingen aan.
  • Is afhankelijk van functies die Newtonsoft.Json bieden.

Als u functies voor de Newtonsoft.Jsonop -gebaseerde formatters wilt configureren, gebruikt u SerializerSettings:

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

Als u uitvoerserialisatieopties voor specifieke acties wilt configureren, gebruikt u JsonResult. For example:

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

Opmaak ProblemDetails en ValidationProblemDetails antwoorden

Met de volgende actiemethode wordt ControllerBase.Problem een ProblemDetails antwoord gemaakt:

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

Een ProblemDetails antwoord is altijd camelCase, zelfs wanneer de app de indeling instelt op PascalCase. ProblemDetails volgt RFC 7807, dat kleine letters aangeeft.

Wanneer het [ApiController] kenmerk wordt toegepast op een controllerklasse, maakt de controller een ValidationProblemDetails antwoord wanneer modelvalidatie mislukt. Dit antwoord bevat een woordenlijst die de eigenschapsnamen van het model gebruikt als foutsleutels, ongewijzigd. Het volgende model bevat bijvoorbeeld één eigenschap waarvoor validatie is vereist:

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

Het antwoord dat wordt geretourneerd wanneer de Value eigenschap ongeldig is, ValidationProblemDetails gebruikt standaard een foutsleutel van Value, zoals wordt weergegeven in het volgende voorbeeld:

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

Als u de eigenschapsnamen wilt opmaken die worden gebruikt als foutsleutels, voegt u een implementatie van IMetadataDetailsProvider de MvcOptions.ModelMetadataDetailsProviders verzameling toe. In het volgende voorbeeld wordt een System.Text.Jsonimplementatie op basis van een indeling toegevoegd, SystemTextJsonValidationMetadataProviderwaarmee eigenschapsnamen standaard worden opgemaakt als camelCase:

builder.Services.AddControllers();

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

SystemTextJsonValidationMetadataProvider accepteert ook een implementatie van in de constructor, waarmee een aangepast naamgevingsbeleid wordt opgegeven voor het opmaken van JsonNamingPolicy eigenschapsnamen.

Als u een aangepaste naam voor een eigenschap in een model wilt instellen, gebruikt u het kenmerk [JsonPropertyName] op de eigenschap:

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

Het ValidationProblemDetails antwoord dat is geretourneerd voor het voorgaande model wanneer de Value eigenschap ongeldig is, gebruikt een foutsleutel van sampleValue, zoals wordt weergegeven in het volgende voorbeeld:

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

Als u het ValidationProblemDetails antwoord wilt opmaken met behulp van Newtonsoft.Json, gebruikt u NewtonsoftJsonValidationMetadataProvider:

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

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

NewtonsoftJsonValidationMetadataProvider Standaard worden eigenschapsnamen opgemaakt als camelCase. NewtonsoftJsonValidationMetadataProvider accepteert ook een implementatie van in de constructor, waarmee een aangepast naamgevingsbeleid wordt opgegeven voor het opmaken van NamingPolicy eigenschapsnamen. Als u een aangepaste naam voor een eigenschap in een model wilt instellen, gebruikt u het [JsonProperty] kenmerk.

Een indeling opgeven

Als u de antwoordindelingen wilt beperken, past u het [Produces] filter toe. Net als bij de meeste filters[Produces] kunt u deze toepassen op de actie, controller of globaal bereik:

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

Het voorgaande [Produces] filter:

  • Dwingt alle acties binnen de controller af om JSON-geformatteerde antwoorden te retourneren voor POCOs (gewone oude CLR-objecten) of ObjectResult de afgeleide typen.
  • Retourneer JSON-opgemaakte antwoorden, zelfs als andere formatters zijn geconfigureerd en de client een andere indeling opgeeft.

Zie Filters voor meer informatie.

Speciale case formatters

Sommige speciale gevallen worden geïmplementeerd met behulp van ingebouwde formatters. string Standaard worden retourtypen opgemaakt als tekst/tekst zonder opmaak (tekst/html indien aangevraagd via de Accept koptekst). Dit gedrag kan worden verwijderd door de StringOutputFormatter. Formatters worden verwijderd in Program.cs. Acties met een retourtype modelobject retourneren wanneer ze worden geretourneerd 204 No Contentnull. Dit gedrag kan worden verwijderd door de HttpNoContentOutputFormatter. Met de volgende code worden de StringOutputFormatter en HttpNoContentOutputFormatter.

var builder = WebApplication.CreateBuilder(args);

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

Zonder de StringOutputFormatter, de ingebouwde JSON formatter formatter formats retourneert string typen. Als de ingebouwde JSON-indeling wordt verwijderd en er een XML-formatter beschikbaar is, retourneert de XML-formatter-indelingen string typen. string Anders retourneren 406 Not Acceptableretourtypen.

Zonder de HttpNoContentOutputFormatternotatie worden null-objecten opgemaakt met behulp van de geconfigureerde formatter. For example:

  • De JSON-formatter retourneert een antwoord met een hoofdtekst van null.
  • De XML-formatter retourneert een leeg XML-element met de kenmerkset xsi:nil="true" .

URL-toewijzingen voor antwoordindeling

Clients kunnen een bepaalde indeling aanvragen als onderdeel van de URL, bijvoorbeeld:

  • In de querytekenreeks of een deel van het pad.
  • Door een indelingsspecifieke bestandsextensie te gebruiken, zoals .xml of .json.

De toewijzing van het aanvraagpad moet worden opgegeven in de route die de API gebruikt. For example:

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

Met de voorgaande route kan de aangevraagde indeling worden opgegeven met behulp van een optionele bestandsextensie. Het [FormatFilter] kenmerk controleert op het bestaan van de notatiewaarde in de RouteData en wijst de antwoordindeling toe aan de juiste notatie wanneer het antwoord wordt gemaakt.

Route Formatter
/api/todoitems/5 De standaarduitvoerindeling
/api/todoitems/5.json De JSON-formatter (indien geconfigureerd)
/api/todoitems/5.xml De XML-indeling (indien geconfigureerd)

Polymorphic deserialization

Ingebouwde functies bieden een beperkt scala aan polymorfische serialisatie, maar helemaal geen ondersteuning voor deserialisatie. Voor deserialisatie is een aangepast conversieprogramma vereist. Zie Polymorfische deserialisatie voor een volledig voorbeeld van polymorfische deserialisatie.

Additional resources