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

CKTIS / C#

Utf8JsonWriter — escritura secuencial de JSON en UTF-8

Utf8JsonWriter de System.Text.Json permite escribir JSON manualmente como bytes UTF-8 en un Stream o un IBufferWriter<byte>. Tú controlas el orden de las propiedades y la estructura del documento, mientras que el writer se ocupa de la sintaxis JSON y del escape de cadenas.

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

Sintaxis

using var writer = new Utf8JsonWriter(destination, new JsonWriterOptions { Indented = false });
writer.WriteStartObject();
writer.WriteString("name", "Ada");
writer.WriteEndObject();
writer.Flush();

Utf8JsonWriter, del espacio de nombres System.Text.Json, es un mecanismo de bajo nivel para escribir JSON secuencialmente como bytes UTF-8 en un Stream o un IBufferWriter<byte>. En lugar de serializar automáticamente un objeto completo, escribes explícitamente sus propiedades y valores. Es útil para crear serializadores personalizados, pero no es un árbol de documento editable.

Las llamadas WriteStartObject() y WriteEndObject() delimitan un objeto. WriteString("name", "Ada") escribe un par nombre-valor, mientras que WriteStringValue("csharp") escribe solo un valor, como un elemento de un array. WriteStartArray("tags") inicia una propiedad de array, que se cierra con WriteEndArray(). Los métodos para escribir cadenas se encargan del escape necesario: no construyas JSON concatenando texto.

De forma predeterminada, la salida es compacta y la validación estructural está activada; una secuencia de operaciones no válida puede provocar una InvalidOperationException. JsonWriterOptions permite configurar, entre otras opciones, Indented y SkipValidation. Si desactivas la validación, el código que llama al writer pasa a ser responsable de la corrección estructural.

Antes de leer el resultado, llama a Flush() para enviar al destino los bytes pendientes. Esto no sustituye el cierre de objetos y arrays con los métodos correspondientes. Usa using para liberar el writer. En el ejemplo, Encoding.UTF8.GetString(...) convierte los bytes escritos en texto únicamente para mostrarlos. Las API utilizadas están disponibles en .NET 10 y no requieren características del lenguaje en versión preliminar.

Ejemplos

using System;
using System.IO;
using System.Text;
using System.Text.Json;

using var stream = new MemoryStream();
using var writer = new Utf8JsonWriter(stream);

writer.WriteStartObject();
writer.WriteString("name", "Ada");
writer.WriteNumber("score", 42);
writer.WriteStartArray("tags");
writer.WriteStringValue("csharp");
writer.WriteStringValue("json");
writer.WriteEndArray();
writer.WriteEndObject();
writer.Flush();

Console.WriteLine(Encoding.UTF8.GetString(stream.ToArray()));

Resultado

{"name":"Ada","score":42,"tags":["csharp","json"]}

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