Formatieren von Antwortdaten in Web-APIs in ASP.NET Core

Artikel
11/06/2024

ASP.NET Core MVC unterstützt die Formatierung von Antwortdaten mithilfe festgelegter Formate oder als Antwort auf eine Anforderung des Clients.

Formatspezifische Aktionsergebnisse

Einige Aktionsergebnistypen sind für ein bestimmtes Format spezifisch, wie z.B. JsonResult und ContentResult. Aktionen können Ergebnisse zurückgeben, die immer ein bestimmtes Format verwenden und die Anforderung eines Clients zur Verwendung eines anderen Formats ignorieren. Die Rückgabe von JsonResult gibt z. B. JSON-formatierte Daten zurück und die Rückgabe von ContentResult gibt Zeichenfolgen im Nur-Text-Format zurück.

Zum Zurückgeben eines bestimmten Typs ist keine Aktion erforderlich. ASP.NET Core unterstützt jeden Objektrückgabewert. Ergebnisse von Aktionen, die Objekte zurückgeben, deren Typ nicht IActionResult ist, werden mit der entsprechenden IOutputFormatter-Implementierung serialisiert. Weitere Informationen finden Sie unter Rückgabetypen für Controlleraktionen in der ASP.NET Core-Web-API.

Die integrierte Hilfsprogrammmethode ControllerBase.Ok gibt standardmäßig JSON-formatierte Daten zurück:

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

Der Beispielcode gibt eine Liste von Aufgabenelementen zurück. Bei Verwendung der F12-Entwicklungstools im Browser oder von http-repl mit dem obigen Code wird Folgendes angezeigt:

Der Antwortheader enthält content-type: application/json; charset=utf-8.
Die Anforderungsheader. Beispiel: Der Header Accept. Der Accept-Header wird vom vorangehenden Code ignoriert.

Wenn Sie Daten im Textformat zurückgeben möchten, verwenden Sie ContentResult und das Content-Hilfsprogramm:

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

Im obigen Code wird text/plain als Content-Type zurückgegeben.

Bei Aktionen mit mehreren Rückgabetypen wird IActionResult zurückgegeben. Beispiel: Die Rückgabe von verschiedenen HTTP-Statuscodes basierend auf dem Ergebnis des Vorgangs.

Inhaltsaushandlung

Eine Inhaltsaushandlung tritt auf, wenn der Client einen Accept-Header angibt. Das von ASP.NET Core verwendete Standardformat ist JSON. Für die Inhaltsaushandlung gilt:

Sie wird durch ObjectResult implementiert.
Sie ist in die Statuscode-spezifischen Aktionsergebnisse integriert, die von den Hilfsmethoden zurückgegeben werden. Die Hilfsmethoden für Aktionsergebnisse basieren auf ObjectResult.

Wenn ein Modelltyp zurückgegeben wird, lautet der Rückgabetyp ObjectResult.

Die folgende Aktionsmethode verwendet die Hilfsmethoden Ok und NotFound:

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

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

    return Ok(todo);
}

ASP.NET Core unterstützt standardmäßig die folgenden Medientypen:

application/json
text/json
text/plain

Tools wie Fiddler oder curl können den Accept-Anforderungsheader so festlegen, dass dieser das Rückgabeformat angibt. Wenn der Accept-Header einen vom Server unterstützten Typ enthält, wird dieser Typ zurückgegeben. Der nächste Abschnitt zeigt, wie zusätzliche Formatierer hinzugefügt werden.

Controlleraktionen können POCOs (Plain Old CLR Objects) zurückgeben. Wenn ein POCO zurückgegeben wird, erstellt die Runtime automatisch ein ObjectResult, das das Objekt umschließt. Der Client empfängt das formatierte serialisierte Objekt. Wenn das zurückgegebene Objekt null ist, wird eine 204 No Content-Antwort zurückgegeben.

Im folgenden Beispiel wird ein Objekttyp zurückgegeben:

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

Im vorangehenden Code gibt eine Anforderung für ein gültiges Aufgabenelement eine 200 OK-Antwort zurück. Eine Anforderung für ein ungültiges Aufgabenelement gibt eine 204 No Content-Antwort zurück.

Der Accept-Header

Eine Aushandlung des Inhalts findet statt, wenn in der Anforderung ein Accept-Header angezeigt wird. Wenn eine Anforderung einen Accept-Header enthält, führt ASP.NET Core Folgendes aus:

Die Medientypen im Accept-Header werden in der bevorzugten Reihenfolge aufgelistet.
Es wird versucht, einen Formatierer zu finden, der eine Antwort in einem der angegebenen Formate erzeugen kann.

Wenn kein Formatierer gefunden wird, der die Clientanforderung erfüllen kann, führt ASP.NET Core Folgendes aus:

Gibt 406 Not Acceptable zurück, wenn MvcOptions.ReturnHttpNotAcceptable auf true festgelegt ist oder -
Es wird versucht, den ersten Formatierer zu finden, der eine Antwort erzeugen kann.

Wenn kein Formatierer für das angeforderte Format konfiguriert wurde, wird der erste Formatierer verwendet, der das Objekt formatieren kann. Wenn in der Anforderung kein Accept-Header vorhanden ist, gilt Folgendes:

Der erste Formatierer, der das Objekt verarbeiten kann, wird zum Serialisieren der Antwort verwendet.
Es findet keine Aushandlung statt. Der Server bestimmt, welches Format zurückgegeben werden soll.

Enthält der Accept-Header */*, wird der Header ignoriert, es sei denn, RespectBrowserAcceptHeader ist in MvcOptions auf TRUE festgelegt.

Browser und Inhaltsaushandlung

Im Gegensatz zu typischen API-Clients, stellen Webbrowser Accept-Header bereit. Webbrowser geben viele Formate an, einschließlich Platzhaltern. Wenn das Framework erkennt, dass eine Anforderung von einem Browser stammt, wird standardmäßig Folgendes ausgeführt:

Der Accept-Header wird ignoriert.
Der Inhalt wird im JSON-Format zurückgegeben, sofern nicht anders konfiguriert.

Dieser Ansatz sorgt bei der Verwendung von APIs für ein konsistenteres browserübergreifendes Benutzererlebnis.

Um eine App so zu konfigurieren, dass sie Accept-Header von Browsern berücksichtigt, legen Sie die Eigenschaft RespectBrowserAcceptHeader auf true fest:

var builder = WebApplication.CreateBuilder(args);

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

Konfigurieren von Formatierern

Apps, die zusätzliche Formate unterstützen müssen, können die geeigneten NuGet-Pakete hinzufügen und die Unterstützung konfigurieren. Es gibt unterschiedliche Formatierungsprogramme für Ein- und für Ausgaben. Eingabeformatierer werden von der Modellbindung verwendet. Ausgabeformatierer werden zum Formatieren von Antworten verwendet. Informationen zum Erstellen eines benutzerdefinierten Formatierers finden Sie unter Benutzerdefinierte Formatierer.

Hinzufügen von Unterstützung für das XML-Format

Um XML-Formatierer zu konfigurieren, die mithilfe von XmlSerializer implementiert wurden, rufen Sie AddXmlSerializerFormatters auf:

var builder = WebApplication.CreateBuilder(args);

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

Bei Verwendung dieses Codes geben Controllermethoden das geeignete Format basierend auf dem Accept-Header der Anforderung zurück.

Konfigurieren von `System.Text.Json`-basierten Formatierern

Um Features für die System.Text.Json-basierten Formatierer zu konfigurieren, verwenden Sie Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions. Der folgende hervorgehobene Code konfiguriert die PascalCase-Formatierung anstelle der standardmäßigen camelCase-Formatierung:

var builder = WebApplication.CreateBuilder(args);

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

Die folgende Aktionsmethode ruft ControllerBase.Problem auf, um eine ProblemDetails-Antwort zu erstellen:

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

Eine ProblemDetails-Antwort weist immer die camelCase-Formatierung auf, auch wenn die App das Format auf PascalCase festlegt. ProblemDetails folgt RFC 7807, worin die Kleinschreibung angegeben ist.

Um die Optionen für die Serialisierung der Ausgabe für bestimmte Aktionen zu konfigurieren, verwenden Sie JsonResult. Zum Beispiel:

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

Hinzufügen der Unterstützung für `Newtonsoft.Json`-basiertes JSON-Format

Die JSON-Standardformatierer verwenden System.Text.Json. Um die Newtonsoft.Json-basierten Formatierer zu verwenden, installieren Sie das NuGet-Paket Microsoft.AspNetCore.Mvc.NewtonsoftJson und konfigurieren es in Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

Im vorangehenden Code konfiguriert der Aufruf von AddNewtonsoftJson die folgenden Web API-, MVC- und Razor Pages-Features, um Newtonsoft.Json zu verwenden:

Eingabe- und Ausgabeformatierer, die JSON lesen und schreiben
JsonResult
JSON Patch
IJsonHelper
TempData

Einige Features funktionieren mit System.Text.Json-basierten Formatierern möglicherweise nicht gut und erfordern einen Verweis auf die Newtonsoft.Json-basierten Formatierer. Verwenden Sie weiterhin Newtonsoft.Json-basierte Formatierer, wenn für die App Folgendes gilt:

Sie verwendet Newtonsoft.Json-Attribute. Zum Beispiel: [JsonProperty] oder [JsonIgnore].
Sie passt die Serialisierungseinstellungen an.
Sie nutzt Features, die von Newtonsoft.Json bereitgestellt werden.

Um Features für die Newtonsoft.Json-basierten Formatierer zu konfigurieren, verwenden Sie SerializerSettings:

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

Um die Optionen für die Serialisierung der Ausgabe für bestimmte Aktionen zu konfigurieren, verwenden Sie JsonResult. Beispiel:

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

Angeben eines Formats

Um Verweisformate einzuschränken, wenden Sie den [Produces]-Filter an. Wie die meisten Filter kann [Produces] auf Aktions-, Controller- oder globaler Ebene angewendet werden:

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

Mit dem oben stehenden [Produces]-Filter wird Folgendes ausgeführt:

Erzwingt, dass alle Aktionen innerhalb des Controllers JSON-formatierte Antworten für POCOs (Plain Old CLR Objects) oder ObjectResult und deren abgeleitete Typen zurückgeben.
Gibt JSON-formatierte Antworten zurück, auch wenn andere Formatierer konfiguriert sind und der Client ein anderes Format angibt.

Weitere Informationen finden Sie unter Filter.

Formatierer für besondere Fälle

Einige besondere Fälle werden mithilfe von integrierten Formatierungsprogrammen implementiert. Standardmäßig werden string-Rückgabetypen als text/plain formatiert (bzw. als text/html, wenn sie über den Accept-Header angefordert werden). Dieses Verhalten kann durch Entfernen von StringOutputFormatter gelöscht werden. Formatierer werden in Program.cs entfernt. Aktionen mit einem Modellobjekt-Rückgabetyp geben null zurück, wenn der Rückgabewert 204 No Content lautet. Dieses Verhalten kann durch Entfernen von HttpNoContentOutputFormatter gelöscht werden. Der folgende Code entfernt StringOutputFormatter und HttpNoContentOutputFormatter.

var builder = WebApplication.CreateBuilder(args);

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

Ohne den StringOutputFormatter formatiert der integrierte JSON-Formatierer string-Rückgabetypen. Wenn der integrierte JSON-Formatierer entfernt wird und ein XML-Formatierer verfügbar ist, formatiert der XML-Formatierer string-Rückgabetypen. Andernfalls geben string-Rückgabetypen 406 Not Acceptable zurück.

Ohne HttpNoContentOutputFormatter werden NULL-Objekte mithilfe des konfigurierten Formatierungsprogramms formatiert. Zum Beispiel:

Der JSON-Formatierer gibt eine Antwort mit dem Text null zurück.
Der XML-Formatierer gibt ein leeres XML-Element mit festgelegtem Attribut xsi:nil="true" zurück.

Zuordnung des Antwortformats durch URLs

Clients können in der URL ein bestimmtes Format anfordern, beispielsweise folgendermaßen:

In der Abfragezeichenfolge oder als Teil des Pfads.
Durch Verwendung einer formatspezifischen Dateierweiterung wie „.xml“ oder „.json“.

Die Zuordnung des Anforderungspfads sollte in der Route angegeben werden, die die API verwendet. Beispiel:

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

Mit der oben genannten Route kann das angeforderte Format mithilfe einer optionalen Dateierweiterung angegeben werden. Das Attribut [FormatFilter] überprüft, ob in den RouteData ein Formatwert vorhanden ist, und ordnet das Antwortformat beim Erstellen der Antwort dem entsprechenden Formatierer zu.

Route	Formatter
`/api/todoitems/5`	Standard-Ausgabeformatierungsprogramm
`/api/todoitems/5.json`	JSON-Formatierungsprogramm (falls konfiguriert)
`/api/todoitems/5.xml`	XML-Formatierungsprogramm (falls konfiguriert)

Polymorphe Deserialisierung

Integrierte Funktionen bieten einen begrenzten Funktionsbereich der polymorphen Serialisierung, aber gar keine Unterstützung für Deserialisierung. Die Deserialisierung erfordert einen benutzerdefinierten Konverter. Ein vollständiges Beispiel der polymorphen Deserialisierung finden Sie unter Polymorphe Deserialisierung.

Zusätzliche Ressourcen

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

ASP.NET Core MVC unterstützt das Formatieren von Antwortdaten. Antwortdaten können mithilfe bestimmter Formate oder durch Übernahme des vom Client angeforderten Formats formatiert werden.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Formatspezifische Aktionsergebnisse

Einige Aktionsergebnistypen sind für ein bestimmtes Format spezifisch, wie z.B. JsonResult und ContentResult. Aktionen können Ergebnisse zurückgeben, die in einem bestimmten Format formatiert sind, unabhängig von den Clienteinstellungen. Mit JsonResult beispielsweise werden JSON-formatierte Daten zurückgegeben. Mit ContentResult oder einer Zeichenfolge werden Zeichenfolgendaten in Nur-Text-Format zurückgegeben.

Die integrierte Hilfsmethode Ok gibt JSON-formatierte Daten zurück:

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

Der Beispieldownload gibt die Liste der Autoren zurück. Bei Verwendung der F12-Entwicklungstools im Browser oder von http-repl mit dem obigen Code:

Der Antwortheader mit content-type: application/json; charset=utf-8 wird angezeigt.
Die Anforderungsheader werden angezeigt. Beispiel: Der Header Accept. Der Accept-Header wird vom vorangehenden Code ignoriert.

Wenn Sie Daten im Textformat zurückgeben möchten, verwenden Sie ContentResult und das Content-Hilfsprogramm:

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

Im obigen Code wird text/plain als Content-Type zurückgegeben. Das Zurückgeben einer Zeichenfolge liefert text/plain als Content-Type:

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

Bei Aktionen mit mehreren Rückgabetypen wird IActionResult zurückgegeben. Beispiel: Die Rückgabe von verschiedenen HTTP-Statuscodes basierend auf dem Ergebnis der ausgeführten Vorgänge.

Inhaltsaushandlung

Eine Inhaltsaushandlung tritt auf, wenn der Client einen Accept-Header angibt. Das von ASP.NET Core verwendete Standardformat ist JSON. Für die Inhaltsaushandlung gilt:

Sie wird durch ObjectResult implementiert.
Sie ist in die Statuscode-spezifischen Aktionsergebnisse integriert, die von den Hilfsmethoden zurückgegeben werden. Die Hilfsmethoden für Aktionsergebnisse basieren auf ObjectResult.

Wenn ein Modelltyp zurückgegeben wird, lautet der Rückgabetyp ObjectResult.

Die folgende Aktionsmethode verwendet die Hilfsmethoden Ok und NotFound:

// GET: api/authors/search?namelike=th
[HttpGet("Search")]
public IActionResult Search(string namelike)
{
    var result = _authors.GetByNameSubstring(namelike);
    if (!result.Any())
    {
        return NotFound(namelike);
    }
    return Ok(result);
}

Standardmäßig unterstützt ASP.NET Core application/json-, text/json- und text/plain-Medientypen. Tools wie Fiddler oder http-repl können den Accept-Anforderungsheader festlegen, um das Rückgabeformat anzugeben. Wenn der Accept-Header einen vom Server unterstützten Typ enthält, wird dieser Typ zurückgegeben. Der nächste Abschnitt zeigt, wie zusätzliche Formatierer hinzugefügt werden.

Zurückgeben eines Objekttyps:

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

Im oben stehenden Code gibt die Anforderung eines gültigen Autoralias eine 200 OK-Antwort mit den Daten des Autors zurück. Die Anforderung eines ungültigen Alias gibt eine 204 No Content-Antwort zurück.

Der Accept-Header

Eine Aushandlung des Inhalts findet statt, wenn in der Anforderung ein Accept-Header angezeigt wird. Wenn eine Anforderung einen Accept-Header enthält, führt ASP.NET Core Folgendes aus:

Die Medientypen im Accept-Header werden in der bevorzugten Reihenfolge aufgelistet.
Es wird versucht, einen Formatierer zu finden, der eine Antwort in einem der angegebenen Formate erzeugen kann.

Wenn kein Formatierer gefunden wird, der die Clientanforderung erfüllen kann, führt ASP.NET Core Folgendes aus:

Gibt 406 Not Acceptable zurück, wenn MvcOptions.ReturnHttpNotAcceptable auf true festgelegt ist oder -
Es wird versucht, den ersten Formatierer zu finden, der eine Antwort erzeugen kann.

Der erste Formatierer, der das Objekt verarbeiten kann, wird zum Serialisieren der Antwort verwendet.
Es findet keine Aushandlung statt. Der Server bestimmt, welches Format zurückgegeben werden soll.

Enthält der Accept-Header */*, wird der Header ignoriert, es sei denn, RespectBrowserAcceptHeader ist in MvcOptions auf TRUE festgelegt.

Browser und Inhaltsaushandlung

Der Accept-Header wird ignoriert.
Der Inhalt wird im JSON-Format zurückgegeben, sofern nicht anders konfiguriert.

Dieser Ansatz sorgt bei der Verwendung von APIs für ein konsistenteres browserübergreifendes Benutzererlebnis.

Um eine App so zu konfigurieren, dass Accept-Header in Browsern berücksichtigt werden, legen Sie RespectBrowserAcceptHeader auf true fest:

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

Konfigurieren von Formatierern

Hinzufügen von Unterstützung für das XML-Format

XML-Formatierer, die mithilfe von XmlSerializer implementiert wurden, werden durch Aufruf von AddXmlSerializerFormatters konfiguriert:

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

Der oben stehende Code serialisiert Ergebnisse mithilfe von XmlSerializer.

Bei Verwendung dieses Codes geben Controllermethoden das geeignete Format basierend auf dem Accept-Header der Anforderung zurück.

Konfigurieren von `System.Text.Json`-basierten Formatierern

Features für die System.Text.Json-basierten Formatierer können mithilfe von Microsoft.AspNetCore.Mvc.JsonOptions.JsonSerializerOptions konfiguriert werden. Die Standardformatierung ist „camelCase“. Der folgende hervorgehobene Code legt die PascalCase-Formatierung fest:

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

Die folgende Aktionsmethode ruft ControllerBase.Problem auf, um eine ProblemDetails-Antwort zu erstellen:

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

Mit dem vorangehenden Code:

https://localhost:5001/WeatherForecast/temperature gibt PascalCase zurück.
https://localhost:5001/WeatherForecast/error gibt camelCase zurück. Di Fehlerantwort weist immer die camelCase-Formatierung auf, auch wenn die App das Format auf PascalCase festlegt. ProblemDetails folgt RFC 7807, worin die Kleinschreibung angegeben ist.

Der folgende Code legt PascalCase fest und fügt einen benutzerdefinierten Konverter hinzu:

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

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

Optionen zur Ausgabeserialisierung können aktionsweise mithilfe von JsonResult konfiguriert werden. Zum Beispiel:

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

Hinzufügen von Newtonsoft.Json-basierter Unterstützung für das JSON-Format

Die JSON-Standardformatierer basieren auf System.Text.Json. Unterstützung für Newtonsoft.Json-basierte Formatierer und Features erhalten Sie durch die Installation des Microsoft.AspNetCore.Mvc.NewtonsoftJson-NuGet-Pakets und dessen Konfiguration in Startup.ConfigureServices.

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

Im vorangehenden Code konfiguriert der Aufruf von AddNewtonsoftJson die folgenden Web API-, MVC- und Razor Pages-Features, um Newtonsoft.Json zu verwenden:

Eingabe- und Ausgabeformatierer, die JSON lesen und schreiben
JsonResult
JSON Patch
IJsonHelper
TempData

Sie verwendet Newtonsoft.Json-Attribute. Zum Beispiel: [JsonProperty] oder [JsonIgnore].
Sie passt die Serialisierungseinstellungen an.
Sie nutzt Features, die von Newtonsoft.Json bereitgestellt werden.

Funktionen für die Newtonsoft.Json-basierten Formatierer können mithilfe von Microsoft.AspNetCore.Mvc.MvcNewtonsoftJsonOptions.SerializerSettings konfiguriert werden:

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

Optionen zur Ausgabeserialisierung können aktionsweise mithilfe von JsonResult konfiguriert werden. Beispiel:

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

Angeben eines Formats

Um Verweisformate einzuschränken, wenden Sie den [Produces]-Filter an. Wie die meisten Filter kann [Produces] auf Aktions-, Controller- oder globaler Ebene angewendet werden:

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

Mit dem oben stehenden [Produces]-Filter wird Folgendes ausgeführt:

Erzwingt, dass alle Aktionen innerhalb des Controllers JSON-formatierte Antworten für POCOs (Plain Old CLR Objects) oder ObjectResult und deren abgeleitete Typen zurückgeben.
Wenn andere Formatierer konfiguriert sind und der Client ein anderes Format angibt, wird JSON zurückgegeben.

Weitere Informationen finden Sie unter Filter.

Formatierer für besondere Fälle

Einige besondere Fälle werden mithilfe von integrierten Formatierungsprogrammen implementiert. Standardmäßig werden string-Rückgabetypen als text/plain formatiert (bzw. als text/html, wenn sie über den Accept-Header angefordert werden). Dieses Verhalten kann durch Entfernen von StringOutputFormatter gelöscht werden. Formatierer werden in der ConfigureServices-Methode entfernt. Aktionen mit einem Modellobjekt-Rückgabetyp geben null zurück, wenn der Rückgabewert 204 No Content lautet. Dieses Verhalten kann durch Entfernen von HttpNoContentOutputFormatter gelöscht werden. Der folgende Code entfernt StringOutputFormatter und HttpNoContentOutputFormatter.

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

Ohne HttpNoContentOutputFormatter werden NULL-Objekte mithilfe des konfigurierten Formatierungsprogramms formatiert. Zum Beispiel:

Der JSON-Formatierer gibt eine Antwort mit dem Text null zurück.
Der XML-Formatierer gibt ein leeres XML-Element mit festgelegtem Attribut xsi:nil="true" zurück.

Zuordnung des Antwortformats durch URLs

Clients können in der URL ein bestimmtes Format anfordern, beispielsweise folgendermaßen:

In der Abfragezeichenfolge oder als Teil des Pfads.
Durch Verwendung einer formatspezifischen Dateierweiterung wie „.xml“ oder „.json“.

Die Zuordnung des Anforderungspfads sollte in der Route angegeben werden, die die API verwendet. Beispiel:

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

Mit der oben genannten Route kann das angeforderte Format als optionale Dateierweiterung angegeben werden. Das Attribut [FormatFilter] überprüft, ob in den RouteData ein Formatwert vorhanden ist, und ordnet das Antwortformat beim Erstellen der Antwort dem entsprechenden Formatierer zu.

Route	Formatter
`/api/products/5`	Standard-Ausgabeformatierungsprogramm
`/api/products/5.json`	JSON-Formatierungsprogramm (falls konfiguriert)
`/api/products/5.xml`	XML-Formatierungsprogramm (falls konfiguriert)

ASP.NET Core MVC unterstützt die Formatierung von Antwortdaten mithilfe festgelegter Formate oder als Antwort auf eine Anforderung des Clients.

Formatspezifische Aktionsergebnisse

Die integrierte Hilfsprogrammmethode ControllerBase.Ok gibt standardmäßig JSON-formatierte Daten zurück:

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

Der Beispielcode gibt eine Liste von Aufgabenelementen zurück. Bei Verwendung der F12-Entwicklungstools im Browser oder von http-repl mit dem obigen Code wird Folgendes angezeigt:

Der Antwortheader enthält content-type: application/json; charset=utf-8.
Die Anforderungsheader. Beispiel: Der Header Accept. Der Accept-Header wird vom vorangehenden Code ignoriert.

Wenn Sie Daten im Textformat zurückgeben möchten, verwenden Sie ContentResult und das Content-Hilfsprogramm:

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

Im obigen Code wird text/plain als Content-Type zurückgegeben.

Bei Aktionen mit mehreren Rückgabetypen wird IActionResult zurückgegeben. Beispiel: Die Rückgabe von verschiedenen HTTP-Statuscodes basierend auf dem Ergebnis des Vorgangs.

Inhaltsaushandlung

Eine Inhaltsaushandlung tritt auf, wenn der Client einen Accept-Header angibt. Das von ASP.NET Core verwendete Standardformat ist JSON. Für die Inhaltsaushandlung gilt:

Sie wird durch ObjectResult implementiert.
Sie ist in die Statuscode-spezifischen Aktionsergebnisse integriert, die von den Hilfsmethoden zurückgegeben werden. Die Hilfsmethoden für Aktionsergebnisse basieren auf ObjectResult.

Wenn ein Modelltyp zurückgegeben wird, lautet der Rückgabetyp ObjectResult.

Die folgende Aktionsmethode verwendet die Hilfsmethoden Ok und NotFound:

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

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

    return Ok(todo);
}

ASP.NET Core unterstützt standardmäßig die folgenden Medientypen:

application/json
text/json
text/plain

Tools wie Fiddler oder http-repl können den Accept-Anforderungsheader festlegen, um das Rückgabeformat anzugeben. Wenn der Accept-Header einen vom Server unterstützten Typ enthält, wird dieser Typ zurückgegeben. Der nächste Abschnitt zeigt, wie zusätzliche Formatierer hinzugefügt werden.

Im folgenden Beispiel wird ein Objekttyp zurückgegeben:

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

Der Accept-Header

Eine Aushandlung des Inhalts findet statt, wenn in der Anforderung ein Accept-Header angezeigt wird. Wenn eine Anforderung einen Accept-Header enthält, führt ASP.NET Core Folgendes aus:

Die Medientypen im Accept-Header werden in der bevorzugten Reihenfolge aufgelistet.
Es wird versucht, einen Formatierer zu finden, der eine Antwort in einem der angegebenen Formate erzeugen kann.

Wenn kein Formatierer gefunden wird, der die Clientanforderung erfüllen kann, führt ASP.NET Core Folgendes aus:

Gibt 406 Not Acceptable zurück, wenn MvcOptions.ReturnHttpNotAcceptable auf true festgelegt ist oder -
Es wird versucht, den ersten Formatierer zu finden, der eine Antwort erzeugen kann.

Der erste Formatierer, der das Objekt verarbeiten kann, wird zum Serialisieren der Antwort verwendet.
Es findet keine Aushandlung statt. Der Server bestimmt, welches Format zurückgegeben werden soll.

Enthält der Accept-Header */*, wird der Header ignoriert, es sei denn, RespectBrowserAcceptHeader ist in MvcOptions auf TRUE festgelegt.

Browser und Inhaltsaushandlung

Der Accept-Header wird ignoriert.
Der Inhalt wird im JSON-Format zurückgegeben, sofern nicht anders konfiguriert.

Dieser Ansatz sorgt bei der Verwendung von APIs für ein konsistenteres browserübergreifendes Benutzererlebnis.

Um eine App so zu konfigurieren, dass sie Accept-Header von Browsern berücksichtigt, legen Sie die Eigenschaft RespectBrowserAcceptHeader auf true fest:

var builder = WebApplication.CreateBuilder(args);

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

Konfigurieren von Formatierern

Hinzufügen von Unterstützung für das XML-Format

Um XML-Formatierer zu konfigurieren, die mithilfe von XmlSerializer implementiert wurden, rufen Sie AddXmlSerializerFormatters auf:

var builder = WebApplication.CreateBuilder(args);

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

Bei Verwendung dieses Codes geben Controllermethoden das geeignete Format basierend auf dem Accept-Header der Anforderung zurück.

Konfigurieren von `System.Text.Json`-basierten Formatierern

var builder = WebApplication.CreateBuilder(args);

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

Um die Optionen für die Serialisierung der Ausgabe für bestimmte Aktionen zu konfigurieren, verwenden Sie JsonResult. Zum Beispiel:

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

Hinzufügen der Unterstützung für `Newtonsoft.Json`-basiertes JSON-Format

var builder = WebApplication.CreateBuilder(args);

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

Im vorangehenden Code konfiguriert der Aufruf von AddNewtonsoftJson die folgenden Web API-, MVC- und Razor Pages-Features, um Newtonsoft.Json zu verwenden:

Eingabe- und Ausgabeformatierer, die JSON lesen und schreiben
JsonResult
JSON Patch
IJsonHelper
TempData

Sie verwendet Newtonsoft.Json-Attribute. Zum Beispiel: [JsonProperty] oder [JsonIgnore].
Sie passt die Serialisierungseinstellungen an.
Sie nutzt Features, die von Newtonsoft.Json bereitgestellt werden.

Um Features für die Newtonsoft.Json-basierten Formatierer zu konfigurieren, verwenden Sie SerializerSettings:

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

Um die Optionen für die Serialisierung der Ausgabe für bestimmte Aktionen zu konfigurieren, verwenden Sie JsonResult. Beispiel:

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

Formatieren von `ProblemDetails`- und `ValidationProblemDetails`-Antworten

Die folgende Aktionsmethode ruft ControllerBase.Problem auf, um eine ProblemDetails-Antwort zu erstellen:

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

Wenn das [ApiController]-Attribut auf eine Controllerklasse angewendet wird, erstellt der Controller eine ValidationProblemDetails-Antwort, wenn die Modellvalidierung fehlerhaft ist. Diese Antwort enthält ein Wörterbuch, das die Eigenschaftsnamen des Modells unverändert als Fehlerschlüssel verwendet. Das folgende Modell enthält z. B. eine einzelne Eigenschaft, die überprüft werden muss:

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

Standardmäßig verwendet die ValidationProblemDetails-Antwort, die zurückgegeben wird, wenn die Value-Eigenschaft ungültig ist, einen Fehlerschlüssel von Value, wie im folgenden Beispiel gezeigt:

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

Um die als Fehlerschlüssel verwendeten Eigenschaftsnamen zu formatieren, fügen Sie der MvcOptions.ModelMetadataDetailsProviders-Sammlung eine Implementierung von IMetadataDetailsProvider hinzu. Das folgende Beispiel fügt eine System.Text.Json-basierte Implementierung hinzu, SystemTextJsonValidationMetadataProvider, die Eigenschaftsnamen standardmäßig in camelCase formatiert:

builder.Services.AddControllers();

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

SystemTextJsonValidationMetadataProvider akzeptiert in seinem Konstruktor auch eine Implementierung von JsonNamingPolicy, die eine benutzerdefinierte Richtlinie für die Formatierung von Eigenschaftsnamen festlegt.

Um einen benutzerdefinierten Namen für eine Eigenschaft innerhalb eines Modells festzulegen, verwenden Sie das Attribut [JsonPropertyName] für die Eigenschaft:

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

Die ValidationProblemDetails-Antwort, die für das vorhergehende Modell zurückgegeben wird, wenn die Eigenschaft Value ungültig ist, verwendet einen Fehlerschlüssel von sampleValue, wie im folgenden Beispiel gezeigt:

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

Um die ValidationProblemDetails-Antwort mithilfe von Newtonsoft.Json zu formatieren, verwenden Sie NewtonsoftJsonValidationMetadataProvider:

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

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

Standardmäßig formatiert NewtonsoftJsonValidationMetadataProvider Eigenschaftsnamen als camelCase. NewtonsoftJsonValidationMetadataProvider akzeptiert in seinem Konstruktor auch eine Implementierung von NamingPolicy, die eine benutzerdefinierte Richtlinie für die Formatierung von Eigenschaftsnamen festlegt. Um einen benutzerdefinierten Namen für eine Eigenschaft innerhalb eines Modells festzulegen, verwenden Sie das Attribut [JsonProperty].

Angeben eines Formats

Um Verweisformate einzuschränken, wenden Sie den [Produces]-Filter an. Wie die meisten Filter kann [Produces] auf Aktions-, Controller- oder globaler Ebene angewendet werden:

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

Mit dem oben stehenden [Produces]-Filter wird Folgendes ausgeführt:

Erzwingt, dass alle Aktionen innerhalb des Controllers JSON-formatierte Antworten für POCOs (Plain Old CLR Objects) oder ObjectResult und deren abgeleitete Typen zurückgeben.
Gibt JSON-formatierte Antworten zurück, auch wenn andere Formatierer konfiguriert sind und der Client ein anderes Format angibt.

Weitere Informationen finden Sie unter Filter.

Formatierer für besondere Fälle

var builder = WebApplication.CreateBuilder(args);

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

Ohne HttpNoContentOutputFormatter werden NULL-Objekte mithilfe des konfigurierten Formatierungsprogramms formatiert. Zum Beispiel:

Der JSON-Formatierer gibt eine Antwort mit dem Text null zurück.
Der XML-Formatierer gibt ein leeres XML-Element mit festgelegtem Attribut xsi:nil="true" zurück.

Zuordnung des Antwortformats durch URLs

Clients können in der URL ein bestimmtes Format anfordern, beispielsweise folgendermaßen:

In der Abfragezeichenfolge oder als Teil des Pfads.
Durch Verwendung einer formatspezifischen Dateierweiterung wie „.xml“ oder „.json“.

Die Zuordnung des Anforderungspfads sollte in der Route angegeben werden, die die API verwendet. Beispiel:

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

Route	Formatter
`/api/todoitems/5`	Standard-Ausgabeformatierungsprogramm
`/api/todoitems/5.json`	JSON-Formatierungsprogramm (falls konfiguriert)
`/api/todoitems/5.xml`	XML-Formatierungsprogramm (falls konfiguriert)

Polymorphe Deserialisierung

Zusätzliche Ressourcen

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Freigeben über

Formatieren von Antwortdaten in Web-APIs in ASP.NET Core

Formatspezifische Aktionsergebnisse

Inhaltsaushandlung

Der Accept-Header

Browser und Inhaltsaushandlung

Konfigurieren von Formatierern

Hinzufügen von Unterstützung für das XML-Format

Konfigurieren von System.Text.Json-basierten Formatierern

Hinzufügen der Unterstützung für Newtonsoft.Json-basiertes JSON-Format

Angeben eines Formats

Formatierer für besondere Fälle

Zuordnung des Antwortformats durch URLs

Polymorphe Deserialisierung

Zusätzliche Ressourcen

Formatspezifische Aktionsergebnisse

Inhaltsaushandlung

Der Accept-Header

Browser und Inhaltsaushandlung

Konfigurieren von Formatierern

Hinzufügen von Unterstützung für das XML-Format

Konfigurieren von System.Text.Json-basierten Formatierern

Hinzufügen von Newtonsoft.Json-basierter Unterstützung für das JSON-Format

Angeben eines Formats

Formatierer für besondere Fälle

Zuordnung des Antwortformats durch URLs

Formatspezifische Aktionsergebnisse

Inhaltsaushandlung

Der Accept-Header

Browser und Inhaltsaushandlung

Konfigurieren von Formatierern

Hinzufügen von Unterstützung für das XML-Format

Konfigurieren von System.Text.Json-basierten Formatierern

Hinzufügen der Unterstützung für Newtonsoft.Json-basiertes JSON-Format

Formatieren von ProblemDetails- und ValidationProblemDetails-Antworten

Angeben eines Formats

Formatierer für besondere Fälle

Zuordnung des Antwortformats durch URLs

Polymorphe Deserialisierung

Zusätzliche Ressourcen

Zusätzliche Ressourcen

Konfigurieren von `System.Text.Json`-basierten Formatierern

Hinzufügen der Unterstützung für `Newtonsoft.Json`-basiertes JSON-Format

Konfigurieren von `System.Text.Json`-basierten Formatierern

Konfigurieren von `System.Text.Json`-basierten Formatierern

Hinzufügen der Unterstützung für `Newtonsoft.Json`-basiertes JSON-Format

Formatieren von `ProblemDetails`- und `ValidationProblemDetails`-Antworten