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

CKTIS / C#

Utf8JsonWriter — escrita sequencial de JSON em UTF-8

Utf8JsonWriter de System.Text.Json permite escrever JSON manualmente como bytes UTF-8 para um Stream ou IBufferWriter<byte>. Controla a ordem das propriedades e a estrutura do documento, enquanto o writer trata da sintaxe JSON e do escape das cadeias de caracteres.

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

Sintaxe

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

Utf8JsonWriter, no espaço de nomes System.Text.Json, é um mecanismo de baixo nível para escrever JSON sequencialmente como bytes UTF-8 para um Stream ou IBufferWriter<byte>. Em vez de serializar automaticamente um objeto completo, escreve explicitamente as respetivas propriedades e valores. É útil para criar serializadores personalizados, mas não é uma árvore de documentos editável.

As chamadas WriteStartObject() e WriteEndObject() delimitam um objeto. WriteString("name", "Ada") escreve um par nome-valor, enquanto WriteStringValue("csharp") escreve apenas um valor, como um elemento de uma matriz. WriteStartArray("tags") inicia uma propriedade de matriz, que é fechada com WriteEndArray(). Os métodos de escrita de cadeias de caracteres tratam do escape necessário: não construa JSON através da concatenação de texto.

Por predefinição, a saída é compacta e a validação estrutural está ativada; uma sequência de operações inválida pode causar uma InvalidOperationException. JsonWriterOptions permite configurar, entre outras opções, Indented e SkipValidation. Ao desativar a validação, a responsabilidade pela correção estrutural passa para o código que faz a chamada.

Antes de ler o resultado, chame Flush() para transferir os bytes pendentes para o destino. Isto não substitui o fecho de objetos e matrizes com os métodos adequados. Utilize using para libertar o writer. No exemplo, Encoding.UTF8.GetString(...) converte os bytes escritos em texto apenas para apresentação. As API utilizadas estão disponíveis no .NET 10 e não requerem funcionalidades da linguagem em versão preview.

Exemplos

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"]}

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