Język

Jak używać narzędzia Utf8JsonWriter w programie System.Text.Json

W tym artykule pokazano, jak używać Utf8JsonWriter typu do tworzenia niestandardowych serializatorów.

Utf8JsonWriter to wysokowydajny sposób pisania zakodowanego w formacie UTF-8 tekstu JSON z typowych typów platformy .NET, takich jak String, Int32i DateTime. Moduł zapisywania jest typem niskiego poziomu, który może służyć do tworzenia niestandardowych serializatorów. Metoda JsonSerializer.Serialize wewnętrznie używa Utf8JsonWriter.

W poniższym przykładzie pokazano, jak używać Utf8JsonWriter klasy:

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)

Użyj ponownie modułu zapisującego

Od wersji .NET 11 wywołaj Reset(Stream, JsonWriterOptions) lub Reset(IBufferWriter<Byte>, JsonWriterOptions), aby ponownie użyć modułu zapisującego. Te przeciążenia zmieniają miejsce docelowe i opcje bez przydzielania innego Utf8JsonWriterelementu .

Przed zresetowaniem modułu zapisywania zakończ bieżący ładunek JSON i wywołaj metodę Flush. Reset czyści stan modułu zapisującego i nie opróżnia buforowanych danych wyjściowych:

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

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

writer.WriteEndObject()
writer.Flush()

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

Pisanie przy użyciu tekstu UTF-8

Aby uzyskać najlepszą możliwą wydajność podczas używania Utf8JsonWriter, zapisuj ładunki JSON już zakodowane jako tekst UTF-8, a nie jako ciągi UTF-16. Użyj JsonEncodedText, aby przechowywać w pamięci podręcznej i wstępnie kodować znane nazwy i wartości właściwości typu string jako elementy statyczne, a następnie przekazywać je do modułu zapisującego zamiast używać literałów ciągów UTF-16. Jest to szybsze niż buforowanie i używanie tablic bajtów UTF-8.

Takie podejście działa również w przypadku konieczności wykonania niestandardowego ucieczki. System.Text.Json nie pozwala wyłączyć ucieczki podczas pisania ciągu. Można jednak przekazać własny JavaScriptEncoder jako opcję dla obiektu zapisującego albo utworzyć własny JsonEncodedText, który używa elementu JavascriptEncoder do tworzenia sekwencji ucieczki, a następnie zapisać JsonEncodedText zamiast ciągu. Aby uzyskać więcej informacji, zobacz Dostosowywanie kodowania znaków.

Zapisywanie nieprzetworzonego kodu JSON

W niektórych scenariuszach możesz chcieć zapisać kod JSON "raw" do ładunku JSON tworzonego za pomocą polecenia Utf8JsonWriter. Możesz użyć Utf8JsonWriter.WriteRawValue, aby to zrobić. Oto typowe scenariusze:

  • Masz istniejący ładunek JSON, który chcesz ująć w nowy kod JSON.

  • Chcesz formatować wartości inaczej niż domyślne Utf8JsonWriter formatowanie.

    Na przykład możesz dostosować formatowanie liczb. Domyślnie System.Text.Json pomija punkt dziesiętny dla liczb całkowitych, zapisując 1 zamiast 1.0, na przykład. Uzasadnieniem jest to, że zapisywanie mniejszej liczby bajtów jest dobre dla wydajności. Załóżmy jednak, że użytkownik kodu JSON traktuje liczby z liczbami dziesiętnymi jako liczbami podwójnymi i liczbami bez liczb dziesiętnych jako liczb całkowitych. Warto upewnić się, że liczby w tablicy są rozpoznawane jako podwójne, zapisując punkt dziesiętny i zero dla liczb całkowitych. W poniższym przykładzie pokazano, jak to zrobić:

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

Dostosowywanie maskowania znaków

Ustawienie JsonTextWriterStringEscapeHandling ofert oferuje opcje ucieczki wszystkich znaków innych niż ASCII lub znaków HTML. Domyślnie zamienia na encje wszystkie znaki spoza ASCII Utf8JsonWriter wszystkie znaki HTML. To ucieczka jest wykonywana ze względów bezpieczeństwa w głębi systemu obrony. Aby określić inne zasady ucieczki, utwórz element JavaScriptEncoder i ustaw .JsonWriterOptions.Encoder Aby uzyskać więcej informacji, zobacz Dostosowywanie kodowania znaków.

Zapisywanie wartości null

Aby zapisać wartości null przy użyciu metody Utf8JsonWriter, wywołaj metodę :

  • WriteNull aby zapisać parę klucz-wartość, w której wartość to null.
  • WriteNullValue w celu zapisania wartości null jako elementu tablicy JSON.

W przypadku właściwości typu string, jeśli ciąg ma wartość null, WriteString i WriteStringValue są równoważne WriteNull i WriteNullValue.

Zapisz wartości typu Timespan, Uri lub char

Aby zapisać wartości Timespan, Uri lub char, sformatuj je jako ciągi znaków (na przykład, wywołując ToString()) i wywołaj WriteStringValue.

Zobacz także

  • Last updated on