CKTIS / C#
Utf8JsonReader — odczyt tokenów JSON z UTF-8
Utf8JsonReader z System.Text.Json odczytuje JSON zapisany jako bajty UTF-8, token po tokenie i tylko do przodu. Umożliwia wybieranie potrzebnych wartości bez budowania drzewa dokumentu ani deserializowania go do obiektów.
Wersja: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Składnia
var reader = new Utf8JsonReader(utf8Json);
while (reader.Read())
{
// Inspect reader.TokenType and read the current token's value.
}Utf8JsonReader to modyfikowalny ref struct z przestrzeni System.Text.Json, dostępny w .NET 10. Przyjmuje ReadOnlySpan<byte> albo ReadOnlySequence<byte>. Nie buduje drzewa dokumentu; kod wywołujący sam interpretuje kolejne tokeny i strukturę JSON.
Read() przechodzi do następnego tokenu, a TokenType określa jego rodzaj. Metody takie jak GetInt32() odczytują bieżącą wartość i nie przesuwają czytnika. Przed użyciem należy sprawdzić rodzaj tokenu; liczba musi także mieścić się w docelowym typie. ValueTextEquals() porównuje nazwę lub tekst z uwzględnieniem sekwencji ucieczki JSON, bez tworzenia pośredniego string.
Czytnika nie można przechowywać w polu klasy ani zachowywać przez granicę await. Do funkcji pomocniczej, która ma przesunąć oryginalny czytnik, przekazuj go przez ref; kopia ma niezależną pozycję. Dla wejścia wielosegmentowego sprawdzaj HasValueSequence, zanim wybierzesz ValueSequence lub ValueSpan.
Konstruktor użyty w przykładzie zakłada kompletny dokument. Przy odczycie porcjami użyj isFinalBlock, zachowaj CurrentState i niezużyte bajty wskazane przez BytesConsumed, a następnie utwórz nowy czytnik po dostarczeniu danych. Sam stan nie przechowuje tych bajtów. Gdy Read() wykryje błąd składni JSON, zgłasza JsonException. Może jednak rozpoznać token tekstowy ujęty w cudzysłowy mimo nieprawidłowej sekwencji UTF-8 w jego treści. Przy dekodowaniu takiego tokenu GetString() może zgłosić InvalidOperationException zamiast JsonException. Komentarze i końcowe przecinki są domyślnie niedozwolone.
Przykłady
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());
}
}
Wynik
25
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.