WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / C#

Utf8JsonReader – JSON-Token aus UTF-8 lesen

Utf8JsonReader aus System.Text.Json liest UTF-8-kodierte JSON-Bytes Token für Token und ausschließlich vorwärts. So lassen sich benötigte Werte auswählen, ohne einen Dokumentbaum aufzubauen oder das Dokument in Objekte zu deserialisieren.

Version: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Syntax

var reader = new Utf8JsonReader(utf8Json);
while (reader.Read())
{
    // Inspect reader.TokenType and read the current token's value.
}

Utf8JsonReader ist ein veränderbarer ref struct in System.Text.Json und ist in .NET 10 verfügbar. Er akzeptiert ReadOnlySpan<byte> oder ReadOnlySequence<byte>. Er erstellt keinen Dokumentbaum; der aufrufende Code interpretiert die aufeinanderfolgenden Token und die JSON-Struktur selbst.

Read() wechselt zum nächsten Token, und TokenType gibt dessen Art an. Methoden wie GetInt32() lesen den aktuellen Wert, ohne den Reader weiterzubewegen. Prüfe vor dem Aufruf die Token-Art; außerdem muss eine Zahl in den Zieltyp passen. ValueTextEquals() vergleicht einen Namen oder Text unter Berücksichtigung von JSON-Escape-Sequenzen, ohne einen Zwischenschritt mit einem string zu erzeugen.

Der Reader kann weder in einem Klassenfeld gespeichert noch über eine await-Grenze hinweg beibehalten werden. Übergib ihn mit ref an eine Hilfsfunktion, die den ursprünglichen Reader weiterbewegen soll; eine Kopie hat eine unabhängige Position. Prüfe bei mehrsegmentiger Eingabe HasValueSequence, bevor du ValueSequence oder ValueSpan auswählst.

Der im Beispiel verwendete Konstruktor setzt ein vollständiges Dokument voraus. Verwende bei Eingaben in Blöcken isFinalBlock, bewahre CurrentState und die nicht verbrauchten, durch BytesConsumed angegebenen Bytes auf und erstelle nach dem Bereitstellen weiterer Daten einen neuen Reader. Der Zustand allein speichert diese Bytes nicht. Erkennt Read() einen JSON-Syntaxfehler, löst die Methode eine JsonException aus. Sie kann jedoch eine Zeichenfolge in Anführungszeichen als Token erkennen, auch wenn diese ungültige UTF-8-Sequenzen enthält. Beim Dekodieren dieses Tokens mit GetString() kann statt einer JsonException eine InvalidOperationException auftreten. Kommentare und nachgestellte Kommas sind standardmäßig nicht zulässig.

Beispiele

using System;
using System.Text.Json;

ReadOnlySpan<byte> json = "{\"name\":\"Ada\",\"age\":25}"u8;
var reader = new Utf8JsonReader(json);

while (reader.Read())
{
    if (reader.TokenType == JsonTokenType.PropertyName &&
        reader.ValueTextEquals("age"u8))
    {
        if (!reader.Read() || reader.TokenType != JsonTokenType.Number)
            throw new JsonException("Expected a number.");

        Console.WriteLine(reader.GetInt32());
    }
}

Ergebnis

25

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