Formattare i dati di risposta nell'API Web ASP.NET CoreFormat response data in ASP.NET Core Web API

Rick Anderson e Steve SmithBy Rick Anderson and Steve Smith

ASP.NET Core MVC supporta la formattazione dei dati di risposta.ASP.NET Core MVC has support for formatting response data. I dati di risposta possono essere formattati usando formati specifici o in risposta al formato richiesto dal client.Response data can be formatted using specific formats or in response to client requested format.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

Risultati azione specifici del formatoFormat-specific Action Results

Alcuni tipi di risultati di azioni sono specifici di un particolare formato, ad esempio JsonResult e ContentResult.Some action result types are specific to a particular format, such as JsonResult and ContentResult. Le azioni possono restituire risultati formattati in un formato specifico, indipendentemente dalle preferenze dei client.Actions can return results that are formatted in a particular format, regardless of client preferences. Ad esempio, la restituzione di JsonResult restituisce dati in formato JSON.For example, returning JsonResult returns JSON-formatted data. La restituzione di ContentResult o una stringa restituisce dati di stringa in formato testo normale.Returning ContentResult or a string returns plain-text-formatted string data.

Non è necessario eseguire un'azione per restituire un tipo specifico.An action isn't required to return any specific type. ASP.NET Core supporta qualsiasi valore restituito da un oggetto.ASP.NET Core supports any object return value. I risultati di azioni che restituiscono oggetti che non sono tipi IActionResult vengono serializzati usando l'implementazione IOutputFormatter appropriata.Results from actions that return objects that are not IActionResult types are serialized using the appropriate IOutputFormatter implementation. Per ulteriori informazioni, vedere Tipi restituiti dall'azione del controller nell'API Web ASP.NET Core.For more information, see Tipi restituiti dall'azione del controller nell'API Web ASP.NET Core.

Il metodo helper predefinito Ok restituisce dati in formato JSON: [!code-csharp @ no__t-2The built-in helper method Ok returns JSON-formatted data: [!code-csharp]

Il download di esempio restituisce l'elenco degli autori.The sample download returns the list of authors. Utilizzando gli strumenti di sviluppo del browser F12 o l' autore del codice precedente:Using the F12 browser developer tools or Postman with the previous code:

  • Viene visualizzata l'intestazione della risposta contenente Content-Type: application/json; charset=utf-8.The response header containing content-type: application/json; charset=utf-8 is displayed.
  • Verranno visualizzate le intestazioni della richiesta.The request headers are displayed. Ad esempio, l'intestazione Accept.For example, the Accept header. L'intestazione Accept viene ignorata dal codice precedente.The Accept header is ignored by the preceding code.

Per restituire dati in formato testo normale, usare Content e l'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.");
}

Nel codice precedente, il Content-Type restituito è text/plain.In the preceding code, the Content-Type returned is text/plain. La restituzione di una stringa fornisce Content-Type di 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";
}

Per le azioni con più tipi restituiti, restituire IActionResult.For actions with multiple return types, return IActionResult. Ad esempio, la restituzione di codici di stato HTTP diversi in base al risultato delle operazioni eseguite.For example, returning different HTTP status codes based on the result of operations performed.

Negoziazione del contenutoContent negotiation

La negoziazione del contenuto si verifica quando il client specifica un' intestazione Accept.Content negotiation occurs when the client specifies an Accept header. Il formato predefinito usato da ASP.NET Core è JSON.The default format used by ASP.NET Core is JSON. Negoziazione del contenuto:Content negotiation is:

  • Implementato da ObjectResult.Implemented by ObjectResult.
  • Incorporata nei risultati dell'azione specifici del codice di stato restituiti dai metodi helper.Built into the status code-specific action results returned from the helper methods. I metodi helper dei risultati delle azioni sono basati su ObjectResult.The action results helper methods are based on ObjectResult.

Quando viene restituito un tipo di modello, il tipo restituito è ObjectResult.When a model type is returned, the return type is ObjectResult.

Il metodo di azione seguente usa i metodi helper Ok e 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);
}

Per impostazione predefinita, ASP.NET Core supporta i tipi di supporto application/json, text/json e text/plain.By default, ASP.NET Core supports application/json, text/json, and text/plain media types. Gli strumenti, ad esempio Fiddler o post , possono impostare l'intestazione della richiesta Accept per specificare il formato restituito.Tools such as Fiddler or Postman can set the Accept request header to specify the return format. Quando l'intestazione Accept contiene un tipo supportato dal server, viene restituito tale tipo.When the Accept header contains a type the server supports, that type is returned. Nella sezione successiva viene illustrato come aggiungere formattatori aggiuntivi.The next section shows how to add additional formatters.

Le azioni del controller possono restituire POCO (Plain Old CLR Objects).Controller actions can return POCOs (Plain Old CLR Objects). Quando viene restituito un oggetto POCO, il runtime crea automaticamente un ObjectResult che esegue il wrapping dell'oggetto.When a POCO is returned, the runtime automatically creates an ObjectResult that wraps the object. Il client ottiene l'oggetto serializzato formattato.The client gets the formatted serialized object. Se l'oggetto restituito è null, viene restituita una risposta 204 No Content.If the object being returned is null, a 204 No Content response is returned.

Restituzione di un tipo di oggetto:Returning an object type:

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

Nel codice precedente, una richiesta di un alias autore valido restituisce una risposta 200 OK con i dati dell'autore.In the preceding code, a request for a valid author alias returns a 200 OK response with the author's data. Una richiesta di un alias non valido restituisce una risposta 204 No Content.A request for an invalid alias returns a 204 No Content response.

Intestazione AcceptThe Accept header

La negoziazione del contenuto viene verificata quando viene visualizzata un'intestazione Accept nella richiesta.Content negotiation takes place when an Accept header appears in the request. Quando una richiesta contiene un'intestazione Accept, ASP.NET Core:When a request contains an accept header, ASP.NET Core:

  • Enumera i tipi di supporto nell'intestazione Accept in ordine di preferenza.Enumerates the media types in the accept header in preference order.
  • Tenta di trovare un formattatore in grado di generare una risposta in uno dei formati specificati.Tries to find a formatter that can produce a response in one of the formats specified.

Se non viene trovato alcun formattatore in grado di soddisfare la richiesta del client, ASP.NET Core:If no formatter is found that can satisfy the client's request, ASP.NET Core:

  • Restituisce 406 Not Acceptable se è stato impostato MvcOptions oppure-Returns 406 Not Acceptable if MvcOptions has been set, or -
  • Tenta di trovare il primo formattatore in grado di generare una risposta.Tries to find the first formatter that can produce a response.

Se non è configurato alcun formattatore per il formato richiesto, viene utilizzato il primo formattatore in grado di formattare l'oggetto.If no formatter is configured for the requested format, the first formatter that can format the object is used. Se nella richiesta non è presente alcuna intestazione Accept:If no Accept header appears in the request:

  • Il primo formattatore in grado di gestire l'oggetto viene utilizzato per serializzare la risposta.The first formatter that can handle the object is used to serialize the response.
  • Non si verifica alcuna negoziazione.There isn't any negotiation taking place. Il server sta determinando il formato da restituire.The server is determining what format to return.

Se l'intestazione Accept contiene */*, l'intestazione viene ignorata a meno che RespectBrowserAcceptHeader non sia impostato su true in MvcOptions.If the Accept header contains */*, the Header is ignored unless RespectBrowserAcceptHeader is set to true on MvcOptions.

Browser e negoziazione del contenutoBrowsers and content negotiation

A differenza dei client API tipici, i Web browser forniscono intestazioni Accept.Unlike typical API clients, web browsers supply Accept headers. Web browser specificare molti formati, inclusi i caratteri jolly.Web browser specify many formats, including wildcards. Per impostazione predefinita, quando il Framework rileva che la richiesta viene ricevuta da un browser:By default, when the framework detects that the request is coming from a browser:

  • L'intestazione Accept viene ignorata.The Accept header is ignored.
  • Il contenuto viene restituito in JSON, a meno che non sia configurato diversamente.The content is returned in JSON, unless otherwise configured.

Ciò offre un'esperienza più coerente nei browser quando si utilizzano le API.This provides a more consistent experience across browsers when consuming APIs.

Per configurare un'app in modo da rispettare le intestazioni Accept del browser, impostare RespectBrowserAcceptHeader su 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);
}

Configura formattatoriConfigure formatters

Le app che devono supportare formati aggiuntivi possono aggiungere i pacchetti NuGet appropriati e configurare il supporto.Apps that need to support additional formats can add the appropriate NuGet packages and configure support. Esistono formattatori separati per input e output.There are separate formatters for input and output. I formattatori di input vengono utilizzati dall' associazione di modelli.Input formatters are used by Model Binding. I formattatori di output vengono utilizzati per formattare le risposte.Output formatters are used to format responses. Per informazioni sulla creazione di un formattatore personalizzato, vedere formattatori personalizzati.For information on creating a custom formatter, see Custom Formatters.

Aggiungere il supporto per il formato XMLAdd XML format support

I formattatori XML implementati con XmlSerializer sono configurati chiamando AddXmlSerializerFormatters:XML formatters implemented using XmlSerializer are configured by calling AddXmlSerializerFormatters:

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

Il codice precedente serializza i risultati usando XmlSerializer.The preceding code serializes results using XmlSerializer.

Quando si usa il codice precedente, i metodi del controller devono restituire il formato appropriato in base all'intestazione Accept della richiesta.When using the preceding code, controller methods should return the appropriate format based on the request's Accept header.

Configurare i formattatori basati su System.Text.JsonConfigure System.Text.Json-based formatters

Le funzionalità per i formattatori basati su System.Text.Json possono essere configurate tramite 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());
});

È possibile configurare le opzioni di serializzazione dell'output, in base alle singole azioni, usando JsonResult.Output serialization options, on a per-action basis, can be configured using JsonResult. Esempio:For example:

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

Aggiungere il supporto del formato JSON basato su Newtonsoft.JsonAdd Newtonsoft.Json-based JSON format support

Prima del ASP.NET Core 3,0, i formattatori JSON usati per impostazione predefinita sono stati implementati usando il pacchetto Newtonsoft.Json.Prior to ASP.NET Core 3.0, the default used JSON formatters implemented using the Newtonsoft.Json package. In ASP.NET Core 3.0 o versione successiva, i formattatori JSON predefiniti sono basati su System.Text.Json.In ASP.NET Core 3.0 or later, the default JSON formatters are based on System.Text.Json. Il supporto per formattatori e funzionalità basati su Newtonsoft.Json è disponibile installando il pacchetto NuGet Microsoft. AspNetCore. Mvc. NewtonsoftJson e configurarlo in 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();
}

Alcune funzionalità potrebbero non funzionare correttamente con i formattatori basati su System.Text.Json e richiedono un riferimento ai formattatori basati su @no__t 1.Some features may not work well with System.Text.Json-based formatters and require a reference to the Newtonsoft.Json-based formatters. Continuare a usare i formattatori basati su Newtonsoft.Json se l'app:Continue using the Newtonsoft.Json-based formatters if the app:

  • USA gli attributi Newtonsoft.Json.Uses Newtonsoft.Json attributes. Ad esempio, [JsonProperty] o [JsonIgnore].For example, [JsonProperty] or [JsonIgnore].
  • Personalizza le impostazioni di serializzazione.Customizes the serialization settings.
  • Si basa sulle funzionalità fornite da Newtonsoft.Json.Relies on features that Newtonsoft.Json provides.
  • Configura Microsoft.AspNetCore.Mvc.JsonResult.SerializerSettings.Configures Microsoft.AspNetCore.Mvc.JsonResult.SerializerSettings. Prima di ASP.NET Core 3.0 JsonResult.SerializerSettings accetta un'istanza di JsonSerializerSettings specifica di Newtonsoft.Json.Prior to ASP.NET Core 3.0, JsonResult.SerializerSettings accepts an instance of JsonSerializerSettings that is specific to Newtonsoft.Json.
  • Genera documentazione OpenAPI.Generates OpenAPI documentation.

È possibile configurare le funzionalità per i formattatori basati su @no__t 0 con 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());
});

È possibile configurare le opzioni di serializzazione dell'output, in base alle singole azioni, usando JsonResult.Output serialization options, on a per-action basis, can be configured using JsonResult. Esempio:For example:

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

Aggiungere il supporto per il formato XMLAdd XML format support

Per la formattazione XML è necessario il pacchetto NuGet Microsoft. AspNetCore. Mvc. Formatters. XML .XML formatting requires the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

I formattatori XML implementati con XmlSerializer sono configurati chiamando AddXmlSerializerFormatters:XML formatters implemented using XmlSerializer are configured by calling AddXmlSerializerFormatters:

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

Il codice precedente serializza i risultati usando XmlSerializer.The preceding code serializes results using XmlSerializer.

Quando si usa il codice precedente, i metodi del controller devono restituire il formato appropriato in base all'intestazione Accept della richiesta.When using the preceding code, controller methods should return the appropriate format based on the request's Accept header.

Specificare un formatoSpecify a format

Per limitare i formati di risposta, applicare il filtro [Produces] .To restrict the response formats, apply the [Produces] filter. Come la maggior parte dei filtri, [Produces] può essere applicato all'azione, al controller o all'ambito 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
{

Il filtro [Produces] precedente:The preceding [Produces] filter:

  • Impone a tutte le azioni all'interno del controller di restituire risposte in formato JSON.Forces all actions within the controller to return JSON-formatted responses.
  • Se sono configurati altri formattatori e il client specifica un formato diverso, viene restituito JSON.If other formatters are configured and the client specifies a different format, JSON is returned.

Per ulteriori informazioni, vedere filtri.For more information, see Filters.

Formattatori case specialiSpecial case formatters

Alcuni casi speciali vengono implementati tramite formattatori predefiniti.Some special cases are implemented using built-in formatters. Per impostazione predefinita, i tipi restituiti string vengono formattati come text/plain (text/html se richiesto tramite l'intestazione Accept).By default, string return types are formatted as text/plain (text/html if requested via the Accept header). Questo comportamento può essere eliminato rimuovendo il StringOutputFormatter.This behavior can be deleted by removing the StringOutputFormatter. I formattatori vengono rimossi nel metodo ConfigureServices.Formatters are removed in the ConfigureServices method. Le azioni che hanno un tipo restituito da un oggetto modello restituiscono 204 No Content quando restituisce null.Actions that have a model object return type return 204 No Content when returning null. Questo comportamento può essere eliminato rimuovendo il HttpNoContentOutputFormatter.This behavior can be deleted by removing the HttpNoContentOutputFormatter. Il codice seguente rimuove StringOutputFormatter e 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);
}

Senza il StringOutputFormatter, il formattatore JSON incorporato formatta i tipi restituiti string.Without the StringOutputFormatter, the built-in JSON formatter formats string return types. Se il formattatore JSON incorporato viene rimosso ed è disponibile un formattatore XML, il formattatore XML formatta i tipi restituiti string.If the built-in JSON formatter is removed and an XML formatter is available, the XML formatter formats string return types. In caso contrario, i tipi restituiti string restituiscono 406 Not Acceptable.Otherwise, string return types return 406 Not Acceptable.

Senza HttpNoContentOutputFormatter, gli oggetti Null vengono formattati tramite il formattatore configurato.Without the HttpNoContentOutputFormatter, null objects are formatted using the configured formatter. Esempio:For example:

  • Il formattatore JSON restituisce una risposta con un corpo di null.The JSON formatter returns a response with a body of null.
  • Il formattatore XML restituisce un elemento XML vuoto con l'attributo @no__t set-0.The XML formatter returns an empty XML element with the attribute xsi:nil="true" set.

Mapping URL formato rispostaResponse format URL mappings

I client possono richiedere un particolare formato come parte dell'URL, ad esempio:Clients can request a particular format as part of the URL, for example:

  • Nella stringa di query o in una parte del percorso.In the query string or part of the path.
  • Utilizzando un'estensione di file specifica del formato, ad esempio XML o JSON.By using a format-specific file extension such as .xml or .json.

Il mapping dal percorso della richiesta deve essere specificato nella route usata dall'API.The mapping from request path should be specified in the route the API is using. Esempio:For example:

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

La route precedente consente di specificare il formato richiesto come estensione di file facoltativa.The preceding route allows the requested format to be specified as an optional file extension. Con l'attributo [FormatFilter] viene verificata l'esistenza del valore del formato nel RouteData e viene eseguito il mapping del formato della risposta al formattatore appropriato al momento della creazione della risposta.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 FormattatoreFormatter
/api/products/5 Formattatore di output predefinitoThe default output formatter
/api/products/5.json Formattatore JSON (se configurato)The JSON formatter (if configured)
/api/products/5.xml Formattatore XML (se configurato)The XML formatter (if configured)