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.

Formaatspecifieke 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 platte-tekst-geformatteerde tekenreeksgegevens 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 to-do items. Met behulp van de F12-browserontwikkelaarstools of http-repl met de vorige code wordt het volgende weergegeven:

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

Om gegevens in platte-tekstformaat te retourneren, gebruikt u ContentResult en de Content helper:

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

In de voorgaande code wordt Content-Type geretourneerd als text/plain.

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

Inhoudsonderhandeling

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 actieresultaten die bij specifieke statuscodes horen en 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

Programma's zoals Fiddler of curl kunnen de Accept verzoekheader 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 verzoek voor een ongeldig to-do item 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 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 in welk formaat het moet worden geretourneerd.

Als de Accept-koptekst */* bevat, wordt de koptekst genegeerd, tenzij RespectBrowserAcceptHeader is ingesteld op 'true' op MvcOptions.

Browsers en inhoudsonderhandeling

In tegenstelling tot typische API-cliënten leveren 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 om te voldoen aan browser accept-headers, stelt u de eigenschap RespectBrowserAcceptHeader in op true.

var builder = WebApplication.CreateBuilder(args);

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

Formatters configureren

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. Uitvoerformatters worden gebruikt om reacties 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.

Configureren van System.Text.Json-gebaseerde formatters

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. Voorbeeld:

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

Ondersteuning voor op Newtonsoft.Json gebaseerde JSON-indeling toevoegen

De standaard JSON-formatters gebruiken System.Text.Json. Als u de op Newtonsoft.Json-gebaseerde formatters wilt gebruiken, moet u het Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-pakket installeren en deze configureren in Program.cs.

var builder = WebApplication.CreateBuilder(args);

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

In de voorgaande code configureert de aanroep de volgende Web API, MVC en Pages-functies om te gebruiken met AddNewtonsoftJson:RazorNewtonsoft.Json

Sommige functies werken mogelijk niet goed met System.Text.Json-gebaseerde formatters en vereisen een verwijzing naar de Newtonsoft.Json-gebaseerde formatters. Blijf de op-gebaseerde Newtonsoft.Json-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. Voorbeeld:

[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 af dat alle acties binnen de controller JSON-geformatteerde antwoorden retourneren voor POCO's (gewone oude CLR-objecten) of ObjectResult en zijn 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-opmaakprogramma's

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 verwijderd worden door de StringOutputFormatter te verwijderen. Formatters worden verwijderd in Program.cs. Acties met een modelobject als retourtype retourneren 204 No Content wanneer null wordt geretourneerd. Dit gedrag kan verwijderd worden door de HttpNoContentOutputFormatter te verwijderen. 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 formatteert de ingebouwde JSON-formatter de string-retourtypen. nl-NL: Als de ingebouwde JSON-formatter wordt verwijderd en er een XML-formatter beschikbaar is, formatteert de XML-formatter string returntypes. Anders retourneren retourtypen string406 Not Acceptable.

Zonder de HttpNoContentOutputFormatter worden null-objecten opgemaakt met behulp van de geconfigureerde formatter. Voorbeeld:

  • 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 antwoordformaat

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

  • In de querystring of als onderdeel van het pad.
  • Door een indelingsspecifieke bestandsextensie te gebruiken, zoals .xml of .json.

De mapping van het verzoekpad moet worden gespecificeerd in de route die de API gebruikt. Voorbeeld:

[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 formaatwaarde in de RouteData en koppelt het responsformaat aan de juiste formatter bij het creëren van de respons.

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

Polymorfische deserialisatie

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.

Aanvullende bronnen

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)

Formaatspecifieke 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.

Om gegevens in platte-tekstformaat te retourneren, gebruikt u ContentResult 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 wordt Content-Type geretourneerd als text/plain. Het retourneren van een tekenreeks levert Content-Type van text/plain op:

// 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.

Inhoudsonderhandeling

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 actieresultaten die bij specifieke statuscodes horen en 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 ASP.NET Core de mediatypen application/json, text/json en text/plain. Hulpprogramma's zoals Fiddler of http-repl kunnen de Accept requestheader 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 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 in welk formaat het moet worden geretourneerd.

Als de Accept-koptekst */* bevat, wordt de koptekst genegeerd, tenzij RespectBrowserAcceptHeader is ingesteld op 'true' op MvcOptions.

Browsers en inhoudsonderhandeling

In tegenstelling tot typische API-cliënten leveren 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 om browser accept-headers te respecteren, stelt u RespectBrowserAcceptHeader in op true.

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

Formatters configureren

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. Uitvoerformatters worden gebruikt om reacties 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 van XmlSerializer worden geconfigureerd door AddXmlSerializerFormatters aan te roepen.

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.

Configureer op System.Text.Json gebaseerde formatters

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 specificeert kleine letters.

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. Voorbeeld:

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 de volgende Web API, MVC en Pages-functies om te gebruiken met AddNewtonsoftJson:RazorNewtonsoft.Json

Sommige functies werken mogelijk niet goed met System.Text.Json-gebaseerde formatters en vereisen een verwijzing naar de Newtonsoft.Json-gebaseerde formatters. Blijf de op-gebaseerde Newtonsoft.Json-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.Json-op-gebaseerde formatters kunnen worden geconfigureerd door middel 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. Voorbeeld:

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 af dat alle acties binnen de controller JSON-geformatteerde antwoorden retourneren voor POCO's (gewone oude CLR-objecten) of ObjectResult en zijn afgeleide typen.
  • Als andere formatters zijn geconfigureerd en de client een andere indeling opgeeft, wordt JSON geretourneerd.

Zie Filters voor meer informatie.

Speciale case-opmaakprogramma's

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 verwijderd worden door de StringOutputFormatter te verwijderen. Formatters worden verwijderd in de ConfigureServices methode. Acties met een modelobject als retourtype retourneren 204 No Content wanneer null wordt geretourneerd. Dit gedrag kan verwijderd worden door de HttpNoContentOutputFormatter te verwijderen. 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 formatteert de ingebouwde JSON-formatter de string-retourtypen. nl-NL: Als de ingebouwde JSON-formatter wordt verwijderd en er een XML-formatter beschikbaar is, formatteert de XML-formatter string returntypes. Anders retourneren retourtypen string406 Not Acceptable.

Zonder de HttpNoContentOutputFormatter worden null-objecten opgemaakt met behulp van de geconfigureerde formatter. Voorbeeld:

  • 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 antwoordformaat

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

  • In de querystring of als onderdeel van het pad.
  • Door een indelingsspecifieke bestandsextensie te gebruiken, zoals .xml of .json.

De mapping van het verzoekpad moet worden gespecificeerd in de route die de API gebruikt. Voorbeeld:

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

Met de bestaande route kan het aangevraagde formaat worden opgegeven als een optionele bestandsextensie. Het [FormatFilter] kenmerk controleert op het bestaan van de formaatwaarde in de RouteData en koppelt het responsformaat aan de juiste formatter bij het creëren van de respons.

Route Formatter
/api/products/5 De standaarduitvoerindeling
/api/products/5.json De JSON-formatter (indien geconfigureerd)
/api/products/5.xml De XML-formatter (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.

Formaatspecifieke 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 platte-tekst-geformatteerde tekenreeksgegevens 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 to-do items. Met behulp van de F12-browserontwikkelaarstools of http-repl met de vorige code wordt het volgende weergegeven:

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

Om gegevens in platte-tekstformaat te retourneren, gebruikt u ContentResult en de Content helper:

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

In de voorgaande code wordt Content-Type geretourneerd als text/plain.

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

Inhoudsonderhandeling

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 actieresultaten die bij specifieke statuscodes horen en 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 requestheader 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 verzoek voor een ongeldig to-do item 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 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 in welk formaat het moet worden geretourneerd.

Als de Accept-koptekst */* bevat, wordt de koptekst genegeerd, tenzij RespectBrowserAcceptHeader is ingesteld op 'true' op MvcOptions.

Browsers en inhoudsonderhandeling

In tegenstelling tot typische API-cliënten leveren 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 om te voldoen aan browser accept-headers, stelt u de eigenschap RespectBrowserAcceptHeader in op true.

var builder = WebApplication.CreateBuilder(args);

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

Formatters configureren

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. Uitvoerformatters worden gebruikt om reacties 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.

Configureren van System.Text.Json-gebaseerde formatters

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. Voorbeeld:

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

Ondersteuning voor op Newtonsoft.Json gebaseerde JSON-indeling toevoegen

De standaard JSON-formatters gebruiken System.Text.Json. Als u de op Newtonsoft.Json-gebaseerde formatters wilt gebruiken, moet u het Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-pakket installeren en deze configureren in Program.cs.

var builder = WebApplication.CreateBuilder(args);

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

In de voorgaande code configureert de aanroep de volgende Web API, MVC en Pages-functies om te gebruiken met AddNewtonsoftJson:RazorNewtonsoft.Json

Sommige functies werken mogelijk niet goed met System.Text.Json-gebaseerde formatters en vereisen een verwijzing naar de Newtonsoft.Json-gebaseerde formatters. Blijf de op-gebaseerde Newtonsoft.Json-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. Voorbeeld:

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

Formatteer 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 ValidationProblemDetails eigenschap ongeldig is, gebruikt standaard de foutsleutel 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 toe aan de MvcOptions.ModelMetadataDetailsProviders-verzameling. In het volgende voorbeeld wordt een implementatie op basis van System.Text.Json toegevoegd, SystemTextJsonValidationMetadataProvider, waarmee eigenschapsnamen standaard in camelCase worden opgemaakt:

builder.Services.AddControllers();

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

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

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 NamingPolicy in de constructor, waarmee een aangepast naamgevingsbeleid voor het opmaken van eigenschapsnamen wordt opgegeven. 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 af dat alle acties binnen de controller JSON-geformatteerde antwoorden retourneren voor POCO's (gewone oude CLR-objecten) of ObjectResult en zijn 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-opmaakprogramma's

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 verwijderd worden door de StringOutputFormatter te verwijderen. Formatters worden verwijderd in Program.cs. Acties met een modelobject als retourtype retourneren 204 No Content wanneer null wordt geretourneerd. Dit gedrag kan verwijderd worden door de HttpNoContentOutputFormatter te verwijderen. 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 formatteert de ingebouwde JSON-formatter de string-retourtypen. nl-NL: Als de ingebouwde JSON-formatter wordt verwijderd en er een XML-formatter beschikbaar is, formatteert de XML-formatter string returntypes. Anders retourneren retourtypen string406 Not Acceptable.

Zonder de HttpNoContentOutputFormatter worden null-objecten opgemaakt met behulp van de geconfigureerde formatter. Voorbeeld:

  • 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 antwoordformaat

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

  • In de querystring of als onderdeel van het pad.
  • Door een indelingsspecifieke bestandsextensie te gebruiken, zoals .xml of .json.

De mapping van het verzoekpad moet worden gespecificeerd in de route die de API gebruikt. Voorbeeld:

[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 formaatwaarde in de RouteData en koppelt het responsformaat aan de juiste formatter bij het creëren van de respons.

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

Polymorfische deserialisatie

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.

Aanvullende bronnen