Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / C#

Utf8JsonReader: lectura de tokens JSON desde UTF-8

Utf8JsonReader de System.Text.Json lee bytes JSON codificados en UTF-8 token a token y solo hacia delante. Permite seleccionar los valores necesarios sin crear un árbol del documento ni deserializarlo en objetos.

Versión: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Sintaxis

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

Utf8JsonReader es un ref struct mutable de System.Text.Json, disponible en .NET 10. Acepta ReadOnlySpan<byte> o ReadOnlySequence<byte>. No crea un árbol del documento; el código que lo llama interpreta por sí mismo los tokens sucesivos y la estructura JSON.

Read() avanza al token siguiente y TokenType indica de qué tipo es. Métodos como GetInt32() leen el valor actual sin avanzar el lector. Comprueba el tipo del token antes de llamarlos; además, el número debe caber en el tipo de destino. ValueTextEquals() compara un nombre o texto teniendo en cuenta las secuencias de escape JSON, sin crear un string intermedio.

El lector no se puede almacenar en un campo de clase ni conservar al cruzar un límite await. Pásalo mediante ref a una función auxiliar que deba avanzar el lector original; una copia tiene una posición independiente. Para una entrada con varios segmentos, comprueba HasValueSequence antes de elegir ValueSequence o ValueSpan.

El constructor del ejemplo presupone un documento completo. Para entradas por bloques, usa isFinalBlock, conserva CurrentState y los bytes no consumidos que indica BytesConsumed, y crea un lector nuevo después de proporcionar más datos. El estado por sí solo no conserva esos bytes. Cuando Read() detecta un error de sintaxis JSON, lanza una JsonException. Sin embargo, puede reconocer una cadena entre comillas como un token aunque contenga secuencias UTF-8 mal formadas. Al decodificar ese token, GetString() puede lanzar una InvalidOperationException en lugar de una JsonException. De forma predeterminada no se permiten comentarios ni comas finales.

Ejemplos

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

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes