CKTIS / C#
Utf8JsonReader — lire des jetons JSON en UTF-8
Utf8JsonReader de System.Text.Json lit les octets JSON encodés en UTF-8 jeton par jeton, uniquement vers l’avant. Il permet de sélectionner les valeurs nécessaires sans construire un arbre de document ni désérialiser le document en objets.
Version : .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 est un ref struct modifiable de System.Text.Json, disponible dans .NET 10. Il accepte ReadOnlySpan<byte> ou ReadOnlySequence<byte>. Il ne construit pas d’arbre de document ; le code appelant interprète lui-même les jetons successifs et la structure JSON.
Read() passe au jeton suivant, et TokenType indique sa nature. Des méthodes comme GetInt32() lisent la valeur courante sans faire avancer le lecteur. Vérifiez le type du jeton avant de les appeler ; un nombre doit également tenir dans le type cible. ValueTextEquals() compare un nom ou un texte en tenant compte des séquences d’échappement JSON, sans créer de string intermédiaire.
Le lecteur ne peut pas être stocké dans un champ de classe ni conservé au-delà d’une frontière await. Passez-le par ref à une fonction auxiliaire qui doit faire avancer le lecteur d’origine ; une copie possède une position indépendante. Pour une entrée multisegment, vérifiez HasValueSequence avant de choisir ValueSequence ou ValueSpan.
Le constructeur utilisé dans l’exemple suppose un document complet. Pour une entrée par blocs, utilisez isFinalBlock, conservez CurrentState et les octets non consommés indiqués par BytesConsumed, puis créez un nouveau lecteur après avoir fourni davantage de données. L’état seul ne conserve pas ces octets. Lorsque Read() détecte une erreur de syntaxe JSON, cette méthode lève une JsonException. Elle peut toutefois reconnaître une chaîne entre guillemets comme un jeton même si la chaîne contient des séquences UTF-8 mal formées. Le décodage de ce jeton avec GetString() peut lever une InvalidOperationException plutôt qu’une JsonException. Les commentaires et les virgules finales sont interdits par défaut.
Exemples
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());
}
}
Résultat
25
Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.