CKTIS / C#
Utf8JsonReader – čítanie tokenov JSON z UTF-8
Utf8JsonReader zo System.Text.Json číta bajty JSON v kódovaní UTF-8 po jednom tokene a iba smerom dopredu. Umožňuje vybrať potrebné hodnoty bez vytvárania stromu dokumentu alebo deserializácie dokumentu na objekty.
Verzia: .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 je meniteľný ref struct zo System.Text.Json, dostupný v .NET 10. Prijíma ReadOnlySpan<byte> alebo ReadOnlySequence<byte>. Nevytvára strom dokumentu; volajúci kód sám interpretuje nasledujúce tokeny a štruktúru JSON.
Read() prejde na ďalší token a TokenType určuje jeho druh. Metódy ako GetInt32() čítajú aktuálnu hodnotu bez posunutia čítačky. Pred ich volaním skontrolujte druh tokenu; číslo sa tiež musí zmestiť do cieľového typu. ValueTextEquals() porovnáva názov alebo text so zohľadnením escape sekvencií JSON bez vytvorenia pomocného string.
Čítačku nemožno uložiť do poľa triedy ani ju zachovať cez hranicu await. Ak má pomocná funkcia posunúť pôvodnú čítačku, odovzdajte jej ju pomocou ref; kópia má nezávislú pozíciu. Pri viacsegmentovom vstupe skontrolujte HasValueSequence pred výberom ValueSequence alebo ValueSpan.
Konštruktor použitý v príklade predpokladá úplný dokument. Pri načítavaní po blokoch použite isFinalBlock, zachovajte CurrentState a nespotrebované bajty označené pomocou BytesConsumed a po dodaní ďalších údajov vytvorte novú čítačku. Samotný stav tieto bajty neuchováva. Ak Read() zistí syntaktickú chybu v JSON, vyvolá výnimku JsonException. Reťazec v úvodzovkách však môže rozpoznať ako token aj vtedy, keď obsahuje neplatné sekvencie UTF-8. Pri dekódovaní takého tokenu môže GetString() vyvolať výnimku InvalidOperationException namiesto JsonException. Komentáre a koncové čiarky sú predvolene zakázané.
Prí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ýsledok
25
Zobrazený kód a uvedený výsledok boli overené v izolovanom prostredí metódou zaznamenanou v dôkaze o overení tejto presnej verzie.