Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C#

Utf8JsonReader — ler tokens JSON a partir de UTF-8

Utf8JsonReader de System.Text.Json lê bytes JSON codificados em UTF-8, um token de cada vez e apenas para a frente. Permite selecionar os valores necessários sem criar uma árvore do documento nem o desserializar em objetos.

Versão: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Sintaxe

var reader = new Utf8JsonReader(utf8Json);
while (reader.Read())
{
    // Inspect reader.TokenType and read the current token's value.
}

Utf8JsonReader é um ref struct mutável de System.Text.Json, disponível no .NET 10. Aceita ReadOnlySpan<byte> ou ReadOnlySequence<byte>. Não cria uma árvore do documento; o código chamador interpreta os tokens sucessivos e a estrutura JSON.

Read() avança para o token seguinte e TokenType identifica o seu tipo. Métodos como GetInt32() leem o valor atual sem avançar o leitor. Verifique o tipo do token antes de os chamar; além disso, o número tem de caber no tipo de destino. ValueTextEquals() compara um nome ou texto tendo em conta as sequências de escape JSON, sem criar uma string intermédia.

O leitor não pode ser guardado num campo de classe nem mantido através de uma fronteira await. Passe-o por ref a uma função auxiliar que tenha de avançar o leitor original; uma cópia tem uma posição independente. Para uma entrada com vários segmentos, verifique HasValueSequence antes de escolher ValueSequence ou ValueSpan.

O construtor usado no exemplo pressupõe um documento completo. Para entradas por blocos, use isFinalBlock, preserve CurrentState e os bytes não consumidos indicados por BytesConsumed e, depois de fornecer mais dados, crie um novo leitor. O estado, por si só, não guarda esses bytes. Quando Read() deteta um erro de sintaxe JSON, lança uma JsonException. No entanto, pode reconhecer uma cadeia de caracteres entre aspas como um token, mesmo que contenha sequências UTF-8 malformadas. Ao descodificar esse token, GetString() pode lançar uma InvalidOperationException em vez de uma JsonException. Por predefinição, não são permitidos comentários nem vírgulas finais.

Exemplos

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());
    }
}

Resultado

25

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes