Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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.

Źródła