WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / C#

Eigene JSON-Konverter: Tokengrenzen, Fehler und kulturunabhängige Formatierung

Implementiere einen Konverter, der genau einen JSON-Wert liest und schreibt, ungeeignete Eingaben ablehnt und Text getrennt von JSON kulturunabhängig formatiert.

Version: C# 12 and .NET 8; later runtimes may add compatible features

Syntax

// C# 12 / .NET 8 — override signatures inside a JsonConverter<T> subclass
using System;
using System.Text.Json;
using System.Text.Json.Serialization;

public override T Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options)

// Typical expressions inside method bodies:
reader.TokenType == JsonTokenType.Number
reader.TryGetInt32(out int value)
throw new JsonException("Expected an Int32 JSON number.");
writer.WriteNumberValue(value);
FormattableString.Invariant($"temperature={value / 10m:F1}")

In C# 12 und .NET 8 legt JsonConverter<T> aus System.Text.Json.Serialization fest, wie ein einzelner Wert vom Typ T gelesen und geschrieben wird. Utf8JsonReader, Utf8JsonWriter, JsonTokenType und JsonException gehören zu System.Text.Json. Der Reader durchläuft die UTF-8-JSON-Token nur vorwärts; TokenType liefert ihre Art als Wert der Enumeration JsonTokenType. Number ist nicht dasselbe wie String mit Ziffern.

Beim Aufruf von Read steht der Reader auf dem ersten Token des Werts. Bei einem Skalar kehrst du ohne reader.Read() zurück, bei einem Objekt oder Array hältst du am zugehörigen EndObject oder EndArray an. Zu frühes Anhalten oder Weiterlesen verletzt den Konvertervertrag. Der Reader ist ein veränderlicher ref struct: Übergib ihn mit ref, wenn der Aufrufer den Fortschritt sehen muss. Deklariere ihn in C# 12 nicht als lokale Variable in einer async-Methode und verwende keine Sichten auf Tokenbytes, nachdem ihr Puffer an einen Pool zurückgegeben wurde.

Prüfe vor TryGetInt32(out int value) auf Number: Bei anderen Tokenarten löst die Methode InvalidOperationException aus; kann sie die Zahl nicht als int lesen, liefert sie false. || wertet die rechte Seite nicht aus, wenn die linke wahr ist. Wirf bei unpassenden Eingaben JsonException; der Serialisierer kann Path, LineNumber und BytePositionInLine ergänzen. Beim Lesen erhält ein Konverter für einen nicht nullfähigen Werttyp standardmäßig Null. Bei Referenztypen und Nullable<T> behandelt der Serialisierer null normalerweise selbst, sofern der Konverter HandleNull nicht auf true setzt.

Write schreibt genau einen Wert mit dem übergebenen Writer, ohne diesen freizugeben. WriteNumberValue(int) schreibt eine Zahl ohne Anführungszeichen. WriteStringValue(string?) schreibt eine Zeichenfolge, die nicht null ist, in Anführungszeichen und maskiert Sonderzeichen nach den JSON-Regeln. Beim Argument null schreibt die Methode das JSON-Literal null ohne Anführungszeichen. Setze JSON nicht per Interpolation zusammen und deaktiviere die Validierung nicht, um nicht vertrauenswürdige Eingaben durchzulassen.

System.FormattableString.Invariant(FormattableString) liefert einen string, dessen Argumente nach der invarianten Kultur formatiert sind. Übergib die Interpolation direkt oder bewahre sie als FormattableString auf; ein fertig formatierter string lässt sich so nicht neu formatieren. F1 ergibt eine Nachkommastelle, hier 12.5. Das ist Textformatierung, keine JSON-Serialisierung oder Maskierung.

Beispiele

using System;
using System.Globalization;
using System.Text.Json;
using System.Text.Json.Serialization;

var options = new JsonSerializerOptions();
options.Converters.Add(new TenthsConverter());

Tenths[] values = JsonSerializer.Deserialize<Tenths[]>("[125,-35]", options)!;
Console.WriteLine(JsonSerializer.Serialize(values, options));

FormattableString text = $"temperature={values[0].Value / 10m:F1}";
var commaFormat = new NumberFormatInfo { NumberDecimalSeparator = "," };
Console.WriteLine(text.ToString(commaFormat));
Console.WriteLine(FormattableString.Invariant(text));

foreach (string bad in new[] { "\"125\"", "2147483648", "null" })
{
    try
    {
        _ = JsonSerializer.Deserialize<Tenths>(bad, options);
        throw new InvalidOperationException("Expected JsonException.");
    }
    catch (JsonException)
    {
        Console.WriteLine($"rejected: {bad}");
    }
}

readonly record struct Tenths(int Value);

sealed class TenthsConverter : JsonConverter<Tenths>
{
    public override Tenths Read(ref Utf8JsonReader reader, Type typeToConvert,
        JsonSerializerOptions options)
    {
        if (reader.TokenType != JsonTokenType.Number || !reader.TryGetInt32(out int value))
            throw new JsonException("Expected an Int32 JSON number.");

        return new Tenths(value);
    }

    public override void Write(Utf8JsonWriter writer, Tenths value,
        JsonSerializerOptions options) => writer.WriteNumberValue(value.Value);
}

Ergebnis

[125,-35]
temperature=12,5
temperature=12.5
rejected: "125"
rejected: 2147483648
rejected: null

`Tenths` speichert die Temperatur in Zehntelgrad. Zwei Elemente prüfen die Lesegrenze; Ziffern in Anführungszeichen, Überlauf und `null` werden abgelehnt. Das explizite Kommaformat ergibt `temperature=12,5`, das invariante Format `temperature=12.5`. Das JSON bleibt `[125,-35]`.

Zugehörige Lektionen

  • C# · Lektion 58 · Fortgeschritten · Version: 3

Quellen