CKTIS / C#
Tweerichtingsconverters voor JSON: tokens lezen, schrijven en valideren
Bouw een System.Text.Json-converter die een JSON-object leest en schrijft, ongeldige tokens weigert en camelCase en het weglaten van null-waarden expliciet toepast.
Versie: 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 en .NET 8 definieert JsonConverter<T> uit System.Text.Json.Serialization beide conversierichtingen. Registreer de converter in options.Converters. Utf8JsonReader, Utf8JsonWriter, JsonTokenType en JsonException staan in System.Text.Json. De reader beweegt alleen vooruit door UTF-8-invoer. Het is een veranderlijke ref struct: geef hem door met ref zodat je de oorspronkelijke cursor verplaatst, niet een kopie. Sla hem niet op in een klasseveld.
Read van de converter begint op het eerste token van de waarde. Controleer voor een object op StartObject, lees de eigenschappen en keer terug op de bijbehorende EndObject, niet erna. Dezelfde regel geldt voor arrays; blijf bij een scalaire waarde op het token zelf. reader.TokenType geeft een lid van de enumeratie JsonTokenType terug. Controleer het voordat je de waarde ophaalt. Number garandeert niet dat het getal in een int past, dus gebruik TryGetInt32. Werp bij ongeschikte invoer een JsonException; de serializer kan Path, LineNumber en BytePositionInLine invullen. Te weinig of te ver lezen kan ook een JsonException opleveren.
Write schrijft precies één volledige waarde met de meegeleverde Utf8JsonWriter; roep daarop geen Dispose of Flush aan. De serializer past PropertyNamingPolicy = JsonNamingPolicy.CamelCase en DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull toe op eigenschappen die hij zelf beheert, niet op handmatige aanroepen van de writer. Het voorbeeld berekent dezelfde namen in beide richtingen en laat volledige eigenschappen met waarde null alleen bij WhenWritingNull weg; 0 wordt wel geschreven. Het vergelijkt namen hoofdlettergevoelig, weigert onbekende en dubbele namen en implementeert de weglaatregels Never en WhenWritingNull, niet alle instellingen van de serializer.
string? is een annotatie voor de null-analyse door de compiler, geen nieuw runtime-type en geen JSON-validatie. int? is het afzonderlijke waardetype Nullable<int>, dat een geheel getal of de afwezigheid van een waarde voorstelt. Standaard verwerkt de serializer null-waarden voor referentietypen en Nullable<T> zonder hun converter aan te roepen. Overschrijf HandleNull zodat het true retourneert als de converter ze zelf moet afhandelen. Dit staat los van het weglaten van eigenschappen: WhenWritingNull geldt alleen bij schrijven. Het contract bepaalt of ontbrekende eigenschappen en expliciete JSON-null bij lezen zijn toegestaan. Hier mag beide voor Note en Rank, maar niet voor DisplayName.
Voorbeelden
#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();
}
}Resultaat
{"displayName":"Ada"}
{"displayName":"Ada","note":null,"rank":null}
{"displayName":"Ada","rank":0}
Rejected: JsonExceptionDe eerste regel laat beide eigenschappen met waarde null weg, de tweede schrijft beide als null en de derde behoudt na het lezen de waarde 0 voor rank. Een getal in plaats van tekst in displayName levert een JsonException op.
Gerelateerde lessen
- C# · Les 39 · Gevorderd · Versie: 3
Bronnen
- 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