CKTIS / C#
Bidirektionale JSON-Konverter: Token lesen, schreiben und prüfen
Erstelle einen System.Text.Json-Konverter, der ein JSON-Objekt liest und schreibt, ungültige Token ablehnt und camelCase sowie das Weglassen von null ausdrücklich umsetzt.
Version: C# 12 and .NET 8; later runtimes may add compatible features
Syntax
using System.Text.Json;
using System.Text.Json.Serialization;
// Members of JsonConverter<T>:
public abstract T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options);
public abstract void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options);
// Inspect reader.TokenType (a JsonTokenType) before reading a value.
// Reject incompatible input with new JsonException("Expected a JSON string.").In C# 12 und .NET 8 definiert JsonConverter<T> aus System.Text.Json.Serialization beide Konvertierungsrichtungen. Registriere ihn in options.Converters. Utf8JsonReader, Utf8JsonWriter, JsonTokenType und JsonException gehören zu System.Text.Json. Der Reader liest UTF-8-Daten nur vorwärts. Er ist ein veränderlicher ref struct: Übergib ihn per ref, damit du die Position des Originals statt einer Kopie änderst. Speichere ihn nicht in einem Klassenfeld.
Read des Konverters beginnt auf dem ersten Token des Werts. Prüfe bei einem Objekt auf StartObject, lies die Eigenschaften und kehre auf dem zugehörigen EndObject zurück, nicht dahinter. Für Arrays gilt dieselbe Regel; bei einem Skalar bleibst du auf dessen Token. reader.TokenType liefert einen Wert der Enumeration JsonTokenType. Prüfe ihn vor dem Abruf des Werts. Number garantiert nicht, dass die Zahl in einen int passt; verwende TryGetInt32. Löse bei unpassenden Eingaben eine JsonException aus. Der Serializer kann Path, LineNumber und BytePositionInLine ergänzen. Auch zu kurzes oder zu weites Lesen kann eine JsonException auslösen.
Write schreibt genau einen vollständigen Wert mit dem bereitgestellten Utf8JsonWriter; rufe darauf weder Dispose noch Flush auf. Der Serializer wendet PropertyNamingPolicy = JsonNamingPolicy.CamelCase und DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull auf die von ihm verwalteten Eigenschaften an, nicht auf manuelle Writer-Aufrufe. Das Beispiel berechnet dieselben Namen in beiden Richtungen und lässt ganze Eigenschaften mit dem Wert null nur bei WhenWritingNull weg; 0 wird geschrieben. Es unterscheidet Groß- und Kleinschreibung, weist unbekannte und doppelte Namen zurück und setzt die Auslassungsregeln Never und WhenWritingNull um, nicht alle Serializer-Einstellungen.
string? ist eine Annotation für die Nullanalyse des Compilers, kein neuer Laufzeittyp und keine JSON-Validierung. int? ist der eigenständige Werttyp Nullable<int> und steht für eine Ganzzahl oder das Fehlen eines Werts. Standardmäßig behandelt der Serializer null bei Referenztypen und Nullable<T>, ohne deren Konverter aufzurufen. Soll der Konverter diese Fälle selbst behandeln, überschreibe HandleNull mit dem Rückgabewert true. Das Weglassen von Eigenschaften ist davon getrennt: WhenWritingNull wirkt nur beim Schreiben. Ob fehlende Eigenschaften oder explizites JSON-null beim Lesen erlaubt sind, bestimmt der Vertrag. Hier sind beide Formen für Note und Rank erlaubt, nicht aber für DisplayName.
Beispiele
#nullable enable
using System;
using System.Collections.Generic;
using System.Text.Json;
using System.Text.Json.Serialization;
var options = new JsonSerializerOptions
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
options.Converters.Add(new ProfileCardConverter());
var card = new ProfileCard("Ada", null, null);
Console.WriteLine(JsonSerializer.Serialize(card, options));
var keepNulls = new JsonSerializerOptions(options)
{
DefaultIgnoreCondition = JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(card, keepNulls));
var read = JsonSerializer.Deserialize<ProfileCard>(
"""{"displayName":"Ada","note":null,"rank":0}""", options)
?? throw new JsonException("Expected a non-null profile card.");
Console.WriteLine(JsonSerializer.Serialize(read, options));
try
{
_ = JsonSerializer.Deserialize<ProfileCard>("""{"displayName":42}""", options);
}
catch (JsonException)
{
Console.WriteLine("Rejected: JsonException");
}
sealed record ProfileCard(string DisplayName, string? Note, int? Rank);
sealed class ProfileCardConverter : JsonConverter<ProfileCard>
{
private static string Name(JsonSerializerOptions options, string clrName) =>
options.PropertyNamingPolicy?.ConvertName(clrName) ?? clrName;
public override ProfileCard Read(ref Utf8JsonReader reader, Type typeToConvert,
JsonSerializerOptions options)
{
if (reader.TokenType != JsonTokenType.StartObject)
throw new JsonException("Expected an object.");
string displayNameKey = Name(options, nameof(ProfileCard.DisplayName));
string noteKey = Name(options, nameof(ProfileCard.Note));
string rankKey = Name(options, nameof(ProfileCard.Rank));
var seen = new HashSet<string>(StringComparer.Ordinal);
string? displayName = null;
string? note = null;
int? rank = null;
while (reader.Read())
{
if (reader.TokenType == JsonTokenType.EndObject)
return new ProfileCard(
displayName ?? throw new JsonException("Missing display name."), note, rank);
if (reader.TokenType != JsonTokenType.PropertyName)
throw new JsonException("Expected a property name.");
string key = reader.GetString() ?? throw new JsonException("Missing property name.");
if (!seen.Add(key))
throw new JsonException("Duplicate property.");
if (!reader.Read())
throw new JsonException("Missing property value.");
if (key == displayNameKey && reader.TokenType == JsonTokenType.String)
displayName = reader.GetString();
else if (key == noteKey && reader.TokenType is JsonTokenType.String or JsonTokenType.Null)
note = reader.GetString();
else if (key == rankKey && reader.TokenType == JsonTokenType.Null)
rank = null;
else if (key == rankKey && reader.TokenType == JsonTokenType.Number &&
reader.TryGetInt32(out int number))
rank = number;
else
throw new JsonException("Unknown property or invalid value.");
}
throw new JsonException("Expected the end of the object.");
}
public override void Write(Utf8JsonWriter writer, ProfileCard value, JsonSerializerOptions options)
{
bool omitNulls = options.DefaultIgnoreCondition == JsonIgnoreCondition.WhenWritingNull;
writer.WriteStartObject();
writer.WriteString(Name(options, nameof(ProfileCard.DisplayName)), value.DisplayName);
if (value.Note is not null || !omitNulls)
writer.WriteString(Name(options, nameof(ProfileCard.Note)), value.Note);
if (value.Rank is int rank)
writer.WriteNumber(Name(options, nameof(ProfileCard.Rank)), rank);
else if (!omitNulls)
writer.WriteNull(Name(options, nameof(ProfileCard.Rank)));
writer.WriteEndObject();
}
}Ergebnis
{"displayName":"Ada"}
{"displayName":"Ada","note":null,"rank":null}
{"displayName":"Ada","rank":0}
Rejected: JsonExceptionDie erste Zeile lässt beide Eigenschaften mit null weg, die zweite schreibt beide als null, und die dritte behält nach dem Lesen rank mit dem Wert 0 bei. Eine Zahl statt Text in displayName führt zu einer JsonException.
Zugehörige Lektionen
- C# · Lektion 39 · Fortgeschritten · Version: 3
Quellen
- How to write custom converters for JSON serialization
- How to use Utf8JsonReader in System.Text.Json
- Utf8JsonWriter Class
- JsonTokenType Enum
- JsonException Class
- How to customize property names and values with System.Text.Json
- How to ignore properties with System.Text.Json
- Nullable reference types
- Nullable value types