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

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

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

Um die Optionen für die Serialisierung der Ausgabe für bestimmte Aktionen zu konfigurieren, verwenden Sie JsonResult. 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() });

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.");

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.

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

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. 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	Der JSON-Formatierer (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)