Mettre en forme les données des réponses dans l’API web ASP.NET CoreFormat response data in ASP.NET Core Web API

De Rick Anderson et Steve SmithBy Rick Anderson and Steve Smith

ASP.NET Core MVC prend en charge la mise en forme des données de réponse.ASP.NET Core MVC has support for formatting response data. Les données de réponse peuvent être formatées à l’aide de formats spécifiques ou en réponse au format demandé par le client.Response data can be formatted using specific formats or in response to client requested format.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Résultats des actions spécifiques au formatFormat-specific Action Results

Certains types de résultats d’action sont spécifiques à un format particulier, comme JsonResult et ContentResult.Some action result types are specific to a particular format, such as JsonResult and ContentResult. Les actions peuvent retourner des résultats mis en forme dans un format particulier, indépendamment des préférences du client.Actions can return results that are formatted in a particular format, regardless of client preferences. Par exemple, le retour de JsonResult retourne des données au format JSON.For example, returning JsonResult returns JSON-formatted data. Le renvoi d' ContentResult ou d’une chaîne retourne des données de chaîne au format texte brut.Returning ContentResult or a string returns plain-text-formatted string data.

Une action n’est pas requise pour retourner un type spécifique.An action isn't required to return any specific type. ASP.NET Core prend en charge toute valeur de retour d’objet.ASP.NET Core supports any object return value. Les résultats des actions qui retournent des objets qui ne sont pas des types IActionResult sont sérialisés à l’aide de l’implémentation de IOutputFormatter appropriée.Results from actions that return objects that are not IActionResult types are serialized using the appropriate IOutputFormatter implementation. Pour plus d'informations, consultez Types de retour de l’action du contrôleur dans ASP.NET Core API Web.For more information, see Types de retour de l’action du contrôleur dans ASP.NET Core API Web.

La méthode d’assistance intégrée Ok retourne des données au format JSON : [!code-csharp]The built-in helper method Ok returns JSON-formatted data: [!code-csharp]

L’exemple de téléchargement retourne la liste des auteurs.The sample download returns the list of authors. À l’aide des outils de développement du navigateur F12 ou du poster avec le code précédent :Using the F12 browser developer tools or Postman with the previous code:

  • L’en-tête de réponse contenant Content-type : application/json; charset=utf-8 est affiché.The response header containing content-type: application/json; charset=utf-8 is displayed.
  • Les en-têtes de demande s’affichent.The request headers are displayed. Par exemple, l’en-tête Accept.For example, the Accept header. L’en-tête Accept est ignoré par le code précédent.The Accept header is ignored by the preceding code.

Pour retourner des données mises en forme en texte brut, utilisez Content et le helper Content :To return plain text formatted data, use Content and the Content helper:

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

Dans le code précédent, le Content-Type retourné est text/plain.In the preceding code, the Content-Type returned is text/plain. Le retour d’une chaîne Content-Type de text/plain:Returning a string delivers Content-Type of text/plain:

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

Pour les actions avec plusieurs types de retour, retournez IActionResult.For actions with multiple return types, return IActionResult. Par exemple, le retour de codes d’état HTTP différents en fonction du résultat des opérations effectuées.For example, returning different HTTP status codes based on the result of operations performed.

Négociation de contenuContent negotiation

La négociation de contenu se produit lorsque le client spécifie un en-tête Accept.Content negotiation occurs when the client specifies an Accept header. Le format par défaut utilisé par ASP.NET Core est JSON.The default format used by ASP.NET Core is JSON. La négociation de contenu est :Content negotiation is:

  • Implémenté par ObjectResult.Implemented by ObjectResult.
  • Intégré aux résultats d’action spécifiques au code d’État retournés par les méthodes d’assistance.Built into the status code-specific action results returned from the helper methods. Les méthodes d’assistance des résultats d’action sont basées sur ObjectResult.The action results helper methods are based on ObjectResult.

Quand un type de modèle est retourné, le type de retour est ObjectResult.When a model type is returned, the return type is ObjectResult.

La méthode d’action suivante utilise les méthodes helper Ok et NotFound :The following action method uses the Ok and NotFound helper methods:

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

Par défaut, ASP.NET Core prend en charge les types de média application/json, text/jsonet text/plain.By default, ASP.NET Core supports application/json, text/json, and text/plain media types. Les outils tels que Fiddler ou postal peuvent définir l’en-tête de demande Accept pour spécifier le format de retour.Tools such as Fiddler or Postman can set the Accept request header to specify the return format. Lorsque l’en-tête Accept contient un type pris en charge par le serveur, ce type est retourné.When the Accept header contains a type the server supports, that type is returned. La section suivante montre comment ajouter des formateurs supplémentaires.The next section shows how to add additional formatters.

Les actions de contrôleur peuvent retourner des POCO (Plain Old CLR Objects).Controller actions can return POCOs (Plain Old CLR Objects). Lorsqu’un POCO est retourné, le runtime crée automatiquement un ObjectResult qui encapsule l’objet.When a POCO is returned, the runtime automatically creates an ObjectResult that wraps the object. Le client obtient l’objet sérialisé mis en forme.The client gets the formatted serialized object. Si l’objet retourné est null, une réponse 204 No Content est retournée.If the object being returned is null, a 204 No Content response is returned.

Retour d’un type d’objet :Returning an object type:

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

Dans le code précédent, une demande d’alias d’auteur valide retourne une réponse 200 OK avec les données de l’auteur.In the preceding code, a request for a valid author alias returns a 200 OK response with the author's data. Une demande d’alias non valide retourne une réponse 204 No Content.A request for an invalid alias returns a 204 No Content response.

En-tête AcceptThe Accept header

La négociation de contenu a lieu lorsqu’un en-tête de Accept apparaît dans la demande.Content negotiation takes place when an Accept header appears in the request. Quand une demande contient un en-tête Accept, ASP.NET Core :When a request contains an accept header, ASP.NET Core:

  • Énumère les types de médias dans l’en-tête Accept dans l’ordre de préférence.Enumerates the media types in the accept header in preference order.
  • Tente de trouver un formateur capable de produire une réponse dans l’un des formats spécifiés.Tries to find a formatter that can produce a response in one of the formats specified.

Si aucun formateur trouvé pouvant satisfaire la demande du client, ASP.NET Core :If no formatter is found that can satisfy the client's request, ASP.NET Core:

  • Retourne 406 Not Acceptable si MvcOptions a été défini, ou-Returns 406 Not Acceptable if MvcOptions has been set, or -
  • Tente de trouver le premier formateur qui peut produire une réponse.Tries to find the first formatter that can produce a response.

Si aucun formateur n’est configuré pour le format demandé, le premier formateur qui peut mettre en forme l’objet est utilisé.If no formatter is configured for the requested format, the first formatter that can format the object is used. Si aucun en-tête de Accept n’apparaît dans la requête :If no Accept header appears in the request:

  • Le premier formateur qui peut gérer l’objet est utilisé pour sérialiser la réponse.The first formatter that can handle the object is used to serialize the response.
  • Aucune négociation n’a lieu.There isn't any negotiation taking place. Le serveur détermine le format à retourner.The server is determining what format to return.

Si l’en-tête Accept contient */*, l’en-tête est ignoré, sauf si RespectBrowserAcceptHeader a la valeur true sur MvcOptions.If the Accept header contains */*, the Header is ignored unless RespectBrowserAcceptHeader is set to true on MvcOptions.

Navigateurs et négociation de contenuBrowsers and content negotiation

Contrairement aux clients d’API typiques, les navigateurs Web fournissent des en-têtes de Accept.Unlike typical API clients, web browsers supply Accept headers. Le navigateur Web spécifie de nombreux formats, y compris des caractères génériques.Web browser specify many formats, including wildcards. Par défaut, lorsque le Framework détecte que la demande provient d’un navigateur :By default, when the framework detects that the request is coming from a browser:

  • L’en-tête Accept est ignoré.The Accept header is ignored.
  • Le contenu est renvoyé au format JSON, sauf s’il a été configuré autrement.The content is returned in JSON, unless otherwise configured.

Cela offre une expérience plus cohérente entre les navigateurs lors de l’utilisation des API.This provides a more consistent experience across browsers when consuming APIs.

Pour configurer une application pour honorer les en-têtes Accept du navigateur, définissez RespectBrowserAcceptHeader sur true:To configure an app to honor browser accept headers, set RespectBrowserAcceptHeader to true:

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

    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

Configurer les formateursConfigure formatters

Les applications qui doivent prendre en charge des formats supplémentaires peuvent ajouter les packages NuGet appropriés et configurer la prise en charge.Apps that need to support additional formats can add the appropriate NuGet packages and configure support. Il existe des formateurs distincts pour les entrées et pour les sorties.There are separate formatters for input and output. Les formateurs d’entrée sont utilisés par la liaison de modèle.Input formatters are used by Model Binding. Les formateurs de sortie sont utilisés pour mettre en forme les réponses.Output formatters are used to format responses. Pour plus d’informations sur la création d’un formateur personnalisé, consultez formateurs personnalisés.For information on creating a custom formatter, see Custom Formatters.

Ajouter la prise en charge du format XMLAdd XML format support

Les formateurs XML implémentés à l’aide de XmlSerializer sont configurés en appelant AddXmlSerializerFormatters:XML formatters implemented using XmlSerializer are configured by calling AddXmlSerializerFormatters:

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

Le code précédent sérialise les résultats à l’aide de XmlSerializer.The preceding code serializes results using XmlSerializer.

Lorsque vous utilisez le code précédent, les méthodes de contrôleur retournent le format approprié en fonction de l’en-tête Accept de la requête.When using the preceding code, controller methods return the appropriate format based on the request's Accept header.

Configurer des formateurs basés sur System.Text.JsonConfigure System.Text.Json-based formatters

Les fonctionnalités pour les formateurs basés sur System.Text.Json peuvent être configurées avec Microsoft.AspNetCore.Mvc.JsonOptions.SerializerOptions.Features for the System.Text.Json-based formatters can be configured using Microsoft.AspNetCore.Mvc.JsonOptions.SerializerOptions.

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

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

Les options de sérialisation de sortie, en fonction de l’action, peuvent être configurées à l’aide de JsonResult.Output serialization options, on a per-action basis, can be configured using JsonResult. Par exemple :For example:

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

Ajouter la prise en charge du format JSON basé sur Newtonsoft.JsonAdd Newtonsoft.Json-based JSON format support

Avant ASP.NET Core 3,0, les formateurs JSON utilisés par défaut ont été implémentés à l’aide du package Newtonsoft.Json.Prior to ASP.NET Core 3.0, the default used JSON formatters implemented using the Newtonsoft.Json package. Dans ASP.NET Core 3.0 ou version ultérieure, les formateurs JSON par défaut sont basés sur System.Text.Json.In ASP.NET Core 3.0 or later, the default JSON formatters are based on System.Text.Json. La prise en charge des formateurs et fonctionnalités basés sur Newtonsoft.Json est disponible en installant le package NuGet Microsoft. AspNetCore. Mvc. NewtonsoftJson et en le configurant dans Startup.ConfigureServices.Support for Newtonsoft.Json based formatters and features is available by installing the Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet package and configuring it in Startup.ConfigureServices.

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

Certaines fonctionnalités peuvent ne pas fonctionner correctement avec les formateurs de System.Text.Jsonet nécessitent une référence aux formateurs basés sur Newtonsoft.Json.Some features may not work well with System.Text.Json-based formatters and require a reference to the Newtonsoft.Json-based formatters. Continuez à utiliser les formateurs basés sur Newtonsoft.Jsonsi l’application :Continue using the Newtonsoft.Json-based formatters if the app:

  • Utilise Newtonsoft.Json attributs.Uses Newtonsoft.Json attributes. Par exemple, [JsonProperty] ou [JsonIgnore].For example, [JsonProperty] or [JsonIgnore].
  • Personnalise les paramètres de sérialisation.Customizes the serialization settings.
  • S’appuie sur les fonctionnalités fournies par Newtonsoft.Json.Relies on features that Newtonsoft.Json provides.
  • Configure Microsoft.AspNetCore.Mvc.JsonResult.SerializerSettings.Configures Microsoft.AspNetCore.Mvc.JsonResult.SerializerSettings. Avant ASP.NET Core 3.0, JsonResult.SerializerSettings accepte une instance de JsonSerializerSettings spécifique à Newtonsoft.Json.Prior to ASP.NET Core 3.0, JsonResult.SerializerSettings accepts an instance of JsonSerializerSettings that is specific to Newtonsoft.Json.
  • Génère une documentation OpenAPI.Generates OpenAPI documentation.

Les fonctionnalités des formateurs basés sur Newtonsoft.Jsonpeuvent être configurées à l’aide de Microsoft.AspNetCore.Mvc.MvcNewtonsoftJsonOptions.SerializerSettings:Features for the Newtonsoft.Json-based formatters can be configured using 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.SerializerOptions.Converters.Add(new MyCustomJsonConverter());
});

Les options de sérialisation de sortie, en fonction de l’action, peuvent être configurées à l’aide de JsonResult.Output serialization options, on a per-action basis, can be configured using JsonResult. Par exemple :For example:

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

Ajouter la prise en charge du format XMLAdd XML format support

La mise en forme XML requiert le package NuGet Microsoft. AspNetCore. Mvc. Formatters. xml .XML formatting requires the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

Les formateurs XML implémentés à l’aide de XmlSerializer sont configurés en appelant AddXmlSerializerFormatters:XML formatters implemented using XmlSerializer are configured by calling AddXmlSerializerFormatters:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
        .AddXmlSerializerFormatters();
}

Le code précédent sérialise les résultats à l’aide de XmlSerializer.The preceding code serializes results using XmlSerializer.

Lorsque vous utilisez le code précédent, les méthodes de contrôleur doivent retourner le format approprié en fonction de l’en-tête Accept de la requête.When using the preceding code, controller methods should return the appropriate format based on the request's Accept header.

Spécifier un formatSpecify a format

Pour limiter les formats de réponse, appliquez le filtre [Produces] .To restrict the response formats, apply the [Produces] filter. Comme la plupart des filtres, [Produces] peut être appliqué au niveau de l’action, du contrôleur ou de l’étendue globale :Like most Filters, [Produces] can be applied at the action, controller, or global scope:

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

Le filtre de [Produces] précédent :The preceding [Produces] filter:

  • Force toutes les actions du contrôleur à retourner des réponses au format JSON.Forces all actions within the controller to return JSON-formatted responses.
  • Si d’autres formateurs sont configurés et que le client spécifie un format différent, JSON est retourné.If other formatters are configured and the client specifies a different format, JSON is returned.

Pour plus d’informations, consultez filtres.For more information, see Filters.

Formateurs de cas spéciauxSpecial case formatters

Certains cas spéciaux sont implémentés avec des formateurs intégrés.Some special cases are implemented using built-in formatters. Par défaut, les string types de retour sont mis en forme en tant que texte/brut (texte/html si demandé via l’en-tête Accept).By default, string return types are formatted as text/plain (text/html if requested via the Accept header). Ce comportement peut être supprimé en supprimant l' StringOutputFormatter.This behavior can be deleted by removing the StringOutputFormatter. Les formateurs sont supprimés de la méthode ConfigureServices.Formatters are removed in the ConfigureServices method. Les actions qui ont un type de retour d’objet de modèle retournent 204 No Content lors du retour de null.Actions that have a model object return type return 204 No Content when returning null. Ce comportement peut être supprimé en supprimant l' HttpNoContentOutputFormatter.This behavior can be deleted by removing the HttpNoContentOutputFormatter. Le code suivant supprime StringOutputFormatter et HttpNoContentOutputFormatter.The following code removes the StringOutputFormatter and HttpNoContentOutputFormatter.

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

    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

Sans la StringOutputFormatter, le format de formateur JSON intégré string les types de retour.Without the StringOutputFormatter, the built-in JSON formatter formats string return types. Si le formateur JSON intégré est supprimé et qu’un formateur XML est disponible, le formateur XML met en forme string types de retour.If the built-in JSON formatter is removed and an XML formatter is available, the XML formatter formats string return types. Sinon, les types de retour string retournent 406 Not Acceptable.Otherwise, string return types return 406 Not Acceptable.

Sans HttpNoContentOutputFormatter, les objets null sont mis en forme avec le formateur configuré.Without the HttpNoContentOutputFormatter, null objects are formatted using the configured formatter. Par exemple :For example:

  • Le formateur JSON retourne une réponse avec un corps de null.The JSON formatter returns a response with a body of null.
  • Le formateur XML retourne un élément XML vide avec l’attribut xsi:nil="true" Set.The XML formatter returns an empty XML element with the attribute xsi:nil="true" set.

Mappages d’URL de format de réponseResponse format URL mappings

Les clients peuvent demander un format particulier dans le cadre de l’URL, par exemple :Clients can request a particular format as part of the URL, for example:

  • Dans la chaîne de requête ou dans une partie du chemin d’accès.In the query string or part of the path.
  • En utilisant une extension de fichier spécifique au format, par exemple. XML ou. JSON.By using a format-specific file extension such as .xml or .json.

Le mappage du chemin de la requête doit être spécifié dans la route utilisée par l’API.The mapping from request path should be specified in the route the API is using. Par exemple :For example:

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

L’itinéraire précédent permet de spécifier le format demandé en tant qu’extension de fichier facultative.The preceding route allows the requested format to be specified as an optional file extension. L’attribut [FormatFilter] vérifie l’existence de la valeur de format dans le RouteData et mappe le format de réponse au formateur approprié lors de la création de la réponse.The [FormatFilter] attribute checks for the existence of the format value in the RouteData and maps the response format to the appropriate formatter when the response is created.

RouteRoute FormatterFormatter
/api/products/5 Le formateur de sortie par défautThe default output formatter
/api/products/5.json Le formateur JSON (s’il est configuré)The JSON formatter (if configured)
/api/products/5.xml Le formateur XML (s’il est configuré)The XML formatter (if configured)