CKTIS / C#
Utf8JsonReader – čitanje JSON tokena iz UTF-8
Utf8JsonReader iz System.Text.Json čita JSON bajtove kodirane u UTF-8, token po token i samo prema naprijed. Omogućuje odabir potrebnih vrijednosti bez izrade stabla dokumenta ili deserijalizacije dokumenta u objekte.
Verzija: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Sintaksa
var reader = new Utf8JsonReader(utf8Json);
while (reader.Read())
{
// Inspect reader.TokenType and read the current token's value.
}Utf8JsonReader je promjenjivi ref struct iz System.Text.Json, dostupan u .NET 10. Prihvaća ReadOnlySpan<byte> ili ReadOnlySequence<byte>. Ne izrađuje stablo dokumenta; pozivajući kod sam tumači uzastopne tokene i strukturu JSON-a.
Read() prelazi na sljedeći token, a TokenType određuje njegovu vrstu. Metode kao što je GetInt32() čitaju trenutačnu vrijednost bez pomicanja čitača. Prije poziva provjerite vrstu tokena; broj također mora stati u ciljni tip. ValueTextEquals() uspoređuje naziv ili tekst uz uvažavanje JSON escape sekvenci, bez stvaranja privremene vrijednosti tipa string.
Čitač se ne može pohraniti u polje klase ni zadržati preko granice await. Proslijedite ga pomoću ref pomoćnoj funkciji koja treba pomaknuti izvorni čitač; kopija ima neovisan položaj. Za ulaz s više segmenata provjerite HasValueSequence prije odabira ValueSequence ili ValueSpan.
Konstruktor u primjeru pretpostavlja potpun dokument. Za ulaz u blokovima upotrijebite isFinalBlock, sačuvajte CurrentState i nepotrošene bajtove naznačene s BytesConsumed, a zatim nakon isporuke dodatnih podataka izradite novi čitač. Samo stanje ne pohranjuje te bajtove. Kad Read() otkrije sintaktičku pogrešku u JSON-u, baca iznimku JsonException. No niz znakova u navodnicima može prepoznati kao token čak i ako sadrži neispravne UTF-8 sekvence. Pri dekodiranju takvog tokena GetString() može baciti iznimku InvalidOperationException umjesto JsonException. Komentari i završni zarezi prema zadanim postavkama nisu dopušteni.
Primjeri
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());
}
}
Rezultat
25
Prikazani kôd i navedeni rezultat provjereni su u izoliranom okruženju metodom zabilježenom u dokazu provjere za ovu točnu verziju.