CKTIS / C#
JsonSerializerOptions — JSON-Lesen und -Schreiben konfigurieren
System.Text.Json.JsonSerializerOptions steuert, wie .NET-Objekte JSON zugeordnet und wieder daraus gelesen werden. Damit lassen sich Eigenschaftsnamen, Kommentare, unbekannte Eigenschaften, Zahlen und das Weglassen von null-Werten konfigurieren. Richten Sie eine Instanz vor der ersten Verwendung ein und verwenden Sie sie danach wieder.
Version: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Syntax
var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, ReadCommentHandling = JsonCommentHandling.Skip, UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow, NumberHandling = JsonNumberHandling.AllowReadingFromString, DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
var value = JsonSerializer.Deserialize<T>(json, options);
string result = JsonSerializer.Serialize(value, options);System.Text.Json.JsonSerializerOptions stellt JsonSerializer.Serialize und JsonSerializer.Deserialize Konfiguration bereit. Das Beispiel zielt auf .NET 10; UnmappedMemberHandling ist ab .NET 8 verfügbar. Es ist keine Preview-Sprachfunktion erforderlich. new JsonSerializerOptions() ohne weitere Einstellungen behält Eigenschaftsnamen bei, unterscheidet beim Lesen zwischen Groß- und Kleinschreibung und verwendet eine strenge Zahlenbehandlung; die Standardwerte für Webanwendungen können abweichen.
JsonNamingPolicy beschreibt eine Regel zur Umwandlung von Namen. PropertyNamingPolicy = JsonNamingPolicy.CamelCase wandelt ItemCount beim Schreiben und Lesen in itemCount um. Dadurch wird der Abgleich nicht unabhängig von Groß- und Kleinschreibung: Dafür dient PropertyNameCaseInsensitive. Ein [JsonPropertyName]-Attribut hat Vorrang vor der Regel.
ReadCommentHandling verwendet JsonCommentHandling: Der Standardwert Disallow weist Kommentare zurück, während Skip sie akzeptiert und ignoriert. Der für Reader gedachte Wert Allow wird von dieser Serializeroption nicht unterstützt. UnmappedMemberHandling verwendet JsonUnmappedMemberHandling: Der Standardwert Skip ignoriert nicht zugeordnete JSON-Eigenschaften, sofern sie nicht als Erweiterungsdaten erfasst werden. Gilt für einen Typ Disallow, löst eine nicht zugeordnete JSON-Eigenschaft eine JsonException aus. Eine typspezifische Konfiguration kann die Einstellung in den Serializeroptionen außer Kraft setzen. Ist Disallow nur in den Optionen gesetzt, kann ein mit [JsonExtensionData] gekennzeichnetes Mitglied nicht zugeordnete Eigenschaften erfassen, statt dass eine Ausnahme ausgelöst wird. Diese Einstellung verlangt nicht, dass jede Modelleigenschaft in der Eingabe vorkommt.
NumberHandling verwendet die Flags von JsonNumberHandling. Der Standardwert Strict verlangt Zahlentokens; AllowReadingFromString erlaubt zusätzlich, "3" als Zahl zu lesen, schreibt sie aber weiterhin als 3. Das separate Flag WriteAsString schreibt Zahlen in Anführungszeichen. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull lässt Eigenschaften mit dem Wert null beim Schreiben aus; 0 oder false werden dadurch nicht ausgelassen und das Lesen von null wird nicht verhindert.
Konfigurieren Sie die Optionen vor der ersten Serialisierung oder Deserialisierung: Danach wird die Instanz unveränderlich. Verwenden Sie sie erneut, um die Metadatencaches beizubehalten; die gemeinsame Verwendung über mehrere Threads ist sicher. Das Beispiel überspringt einen Kommentar, liest eine Zahl in Anführungszeichen und schreibt das Objekt ohne Note. Beim Deserialisieren des Beispieltyps Payload würde eine nicht zugeordnete JSON-Eigenschaft eine JsonException auslösen.
Beispiele
#nullable enable
using System;
using System.Text.Json;
using System.Text.Json.Serialization;
var options = new JsonSerializerOptions
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
ReadCommentHandling = JsonCommentHandling.Skip,
UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow,
NumberHandling = JsonNumberHandling.AllowReadingFromString,
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
const string json = "{ /* input */ \"itemCount\": \"3\", \"note\": null }";
var value = JsonSerializer.Deserialize<Payload>(json, options)
?? throw new InvalidOperationException();
Console.WriteLine(JsonSerializer.Serialize(value, options));
public sealed class Payload
{
public int ItemCount { get; set; }
public string? Note { get; set; }
}
Ergebnis
{"itemCount":3}Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.
Quellen
- .NET API browser
- JsonSerializerOptions Class
- How to instantiate JsonSerializerOptions instances with System.Text.Json
- How to customize property names and values with System.Text.Json
- JsonSerializerOptions.ReadCommentHandling Property
- Handle unmapped members during deserialization
- JsonNumberHandling Enum
- JsonIgnoreCondition Enum