CKTIS / C#
Utf8JsonReader: leggere token JSON da UTF-8
Utf8JsonReader di System.Text.Json legge i byte JSON codificati in UTF-8 un token alla volta e solo in avanti. Permette di selezionare i valori necessari senza creare un albero del documento né deserializzarlo in oggetti.
Versione: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Sintassi
var reader = new Utf8JsonReader(utf8Json);
while (reader.Read())
{
// Inspect reader.TokenType and read the current token's value.
}Utf8JsonReader è un ref struct modificabile di System.Text.Json, disponibile in .NET 10. Accetta ReadOnlySpan<byte> o ReadOnlySequence<byte>. Non crea un albero del documento; il codice chiamante interpreta da sé i token successivi e la struttura JSON.
Read() passa al token successivo e TokenType ne indica il tipo. Metodi come GetInt32() leggono il valore corrente senza far avanzare il lettore. Controlla il tipo del token prima di chiamarli; inoltre, un numero deve rientrare nel tipo di destinazione. ValueTextEquals() confronta un nome o un testo tenendo conto delle sequenze di escape JSON, senza creare una string intermedia.
Il lettore non può essere memorizzato in un campo di classe né mantenuto oltre un confine await. Passalo tramite ref a una funzione di supporto che deve far avanzare il lettore originale; una copia ha una posizione indipendente. Per un input multisegmento, controlla HasValueSequence prima di scegliere ValueSequence o ValueSpan.
Il costruttore usato nell’esempio presuppone un documento completo. Per l’input a blocchi, usa isFinalBlock, conserva CurrentState e i byte non consumati indicati da BytesConsumed, quindi crea un nuovo lettore dopo aver fornito altri dati. Lo stato da solo non conserva quei byte. Quando Read() rileva un errore di sintassi JSON, genera una JsonException. Può però riconoscere una stringa tra virgolette come token anche se contiene sequenze UTF-8 malformate. Durante la decodifica di quel token, GetString() può generare una InvalidOperationException anziché una JsonException. Commenti e virgole finali non sono consentiti per impostazione predefinita.
Esempi
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());
}
}
Risultato
25
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.