Idioma

Como usar Utf8JsonWriter com System.Text.Json

Este artigo mostra como usar o Utf8JsonWriter tipo para criar serializadores personalizados.

Utf8JsonWriter é uma forma de alto desempenho para escrita de texto JSON codificado em UTF-8 com base em tipos .NET comuns como String, Int32 e DateTime. O gravador é um tipo de baixo nível que pode ser usado para criar serializadores personalizados. O método JsonSerializer.Serialize usa Utf8JsonWriter internamente.

O exemplo a seguir mostra como usar a Utf8JsonWriter classe:

var options = new JsonWriterOptions
{
    Indented = true
};

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

writer.WriteStartObject();
writer.WriteString("date", DateTimeOffset.UtcNow);
writer.WriteNumber("temp", 42);
writer.WriteEndObject();
writer.Flush();

string json = Encoding.UTF8.GetString(stream.ToArray());
Console.WriteLine(json);

Dim options As JsonWriterOptions = New JsonWriterOptions With {
    .Indented = True
}

Dim stream As MemoryStream = New MemoryStream
Dim writer As Utf8JsonWriter = New Utf8JsonWriter(stream, options)

writer.WriteStartObject()
writer.WriteString("date", DateTimeOffset.UtcNow)
writer.WriteNumber("temp", 42)
writer.WriteEndObject()
writer.Flush()

Dim json As String = Encoding.UTF8.GetString(stream.ToArray())
Console.WriteLine(json)

Reutilizar um escritor

A partir do .NET 11, chame Reset(Stream, JsonWriterOptions) ou Reset(IBufferWriter<Byte>, JsonWriterOptions) para reutilizar um gravador. Essas sobrecargas alteram o destino e as opções sem precisar alocar outra Utf8JsonWriter.

Antes de redefinir o gravador, conclua a carga JSON atual e chame Flush. Reset limpa o estado do gravador e não libera a saída pendente:

writer.WriteEndObject();
writer.Flush();

writer.Reset(nextStream, new JsonWriterOptions { Indented = true });

writer.WriteEndObject()
writer.Flush()

writer.Reset(nextStream, New JsonWriterOptions With {.Indented = True})

Gravar com texto UTF-8

Para obter o melhor desempenho possível ao usar o Utf8JsonWriter, grave payloads JSON já codificados como texto UTF-8 em vez de como cadeias de caracteres UTF-16. Use JsonEncodedText para armazenar em cache e pré-codificar nomes e valores de propriedade de cadeia de caracteres conhecidos como estáticos e passá-los para o gravador, em vez de usar literais de cadeia de caracteres UTF-16. Isso é mais rápido do que armazenar em cache e usar matrizes de bytes UTF-8.

Essa abordagem também funcionará se você precisar fazer escape personalizado. System.Text.Json não permite desativar o escape ao escrever uma string. No entanto, você pode passar seu JavaScriptEncoder personalizado como uma opção para o writer, ou criar seu próprio JsonEncodedText que usa seu JavascriptEncoder para fazer o escape e, em seguida, escrever o JsonEncodedText em vez da string. Para obter mais informações, consulte Personalizar a codificação de caracteres.

Gravar JSON bruto

Em alguns cenários, talvez você queira gravar JSON "bruto" em uma carga JSON que está criando com Utf8JsonWriter. Você pode usar Utf8JsonWriter.WriteRawValue para fazer isso. Aqui estão cenários típicos:

  • Você tem uma carga JSON existente que deseja colocar em um novo JSON.

  • Você deseja formatar valores de forma diferente da formatação padrão Utf8JsonWriter .

    Por exemplo, talvez você queira personalizar a formatação numérica. Por padrão, System.Text.Json omite o ponto decimal para números inteiros, gravando 1 em vez de 1.0, por exemplo. A lógica é que escrever menos bytes é bom para o desempenho. Mas suponha que o consumidor de seu JSON trate números com decimais como duplos e números sem decimais como inteiros. Talvez você queira garantir que os números em uma matriz sejam todos reconhecidos como duplos, escrevendo um ponto decimal e zero para números inteiros. O seguinte exemplo mostra como fazer isso:

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

namespace WriteRawJson;

public class Program
{
    public static void Main()
    {
        JsonWriterOptions writerOptions = new() { Indented = true, };

        using MemoryStream stream = new();
        using Utf8JsonWriter writer = new(stream, writerOptions);

        writer.WriteStartObject();

        writer.WriteStartArray("defaultJsonFormatting");
        foreach (double number in new double[] { 50.4, 51 })
        {
            writer.WriteStartObject();
            writer.WritePropertyName("value");
            writer.WriteNumberValue(number);
            writer.WriteEndObject();
        }
        writer.WriteEndArray();

        writer.WriteStartArray("customJsonFormatting");
        foreach (double result in new double[] { 50.4, 51 })
        {
            writer.WriteStartObject();
            writer.WritePropertyName("value");
            writer.WriteRawValue(
                FormatNumberValue(result), skipInputValidation: true);
            writer.WriteEndObject();
        }
        writer.WriteEndArray();

        writer.WriteEndObject();
        writer.Flush();

        string json = Encoding.UTF8.GetString(stream.ToArray());
        Console.WriteLine(json);
    }
    static string FormatNumberValue(double numberValue)
    {
        return numberValue == Convert.ToInt32(numberValue) ? 
            numberValue.ToString() + ".0" : numberValue.ToString();
    }
}
// output:
//{
//  "defaultJsonFormatting": [
//    {
//      "value": 50.4
//    },
//    {
//      "value": 51
//    }
//  ],
//  "customJsonFormatting": [
//    {
//      "value": 50.4
//    },
//    {
//      "value": 51.0
//    }
//  ]
//}

Personalizar o escape de caracteres

A configuração StringEscapeHandling de JsonTextWriter oferece opções para escapar de todos os caracteres não ASCII ou caracteres HTML. Por padrão, Utf8JsonWriter escapa todos os caracteres não ASCII e HTML. Esse escape é feita por razões de segurança detalhadas. Para especificar uma política de escape diferente, crie um JavaScriptEncoder e defina JsonWriterOptions.Encoder. Para obter mais informações, consulte Personalizar a codificação de caracteres.

Gravar valores nulos

Para gravar valores nulos usando Utf8JsonWriter, chame:

  • WriteNull para escrever um par chave-valor com null como valor.
  • WriteNullValue para gravar nulo como um elemento de uma matriz JSON.

Para uma propriedade de cadeia de caracteres, se a cadeia de caracteres for nula WriteString e WriteStringValue for equivalente a WriteNull e WriteNullValue.

Escrever valores de Timespan, Uri ou char

Para gravar valores Timespan, Uri ou char, formate-os como cadeias de caracteres (chamando ToString(), por exemplo) e chame WriteStringValue.

Consulte também

  • Última atualização em