CKTIS / C#
Utf8JsonReader – čtení tokenů JSON z UTF-8
Utf8JsonReader z System.Text.Json čte bajty JSON v kódování UTF-8 po jednotlivých tokenech a pouze směrem vpřed. Umožňuje vybrat potřebné hodnoty bez vytváření stromu dokumentu nebo deserializace dokumentu na objekty.
Verze: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Syntaxe
var reader = new Utf8JsonReader(utf8Json);
while (reader.Read())
{
// Inspect reader.TokenType and read the current token's value.
}Utf8JsonReader je měnitelný ref struct z System.Text.Json, dostupný v .NET 10. Přijímá ReadOnlySpan<byte> nebo ReadOnlySequence<byte>. Nevytváří strom dokumentu; volající kód sám interpretuje následující tokeny a strukturu JSON.
Read() přejde na další token a TokenType určuje jeho druh. Metody jako GetInt32() čtou aktuální hodnotu, aniž by posunuly čtečku. Před jejich voláním ověřte druh tokenu; číslo se také musí vejít do cílového typu. ValueTextEquals() porovnává název nebo text se zohledněním escape sekvencí JSON, aniž by vytvářelo pomocný string.
Čtečku nelze uložit do pole třídy ani ji zachovat přes hranici await. Předejte ji pomocné funkci pomocí ref, pokud má posunout původní čtečku; kopie má nezávislou pozici. U vícesegmentového vstupu ověřte HasValueSequence, než zvolíte ValueSequence nebo ValueSpan.
Konstruktor použitý v příkladu předpokládá úplný dokument. Při načítání po blocích použijte isFinalBlock, zachovejte CurrentState a nespotřebované bajty určené pomocí BytesConsumed a po dodání dalších dat vytvořte novou čtečku. Samotný stav tyto bajty neuchovává. Pokud Read() zjistí syntaktickou chybu v JSON, vyvolá výjimku JsonException. Řetězec v uvozovkách však může rozpoznat jako token i tehdy, když obsahuje neplatné sekvence UTF-8. Při dekódování takového tokenu může GetString() vyvolat výjimku InvalidOperationException namísto JsonException. Komentáře a koncové čárky jsou ve výchozím nastavení zakázány.
Příklady
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());
}
}
Výsledek
25
Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.