Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / C#

Utf8JsonWriter — sekwencyjny zapis JSON w UTF-8

Utf8JsonWriter z System.Text.Json pozwala ręcznie zapisywać JSON jako bajty UTF-8 do Stream lub IBufferWriter<byte>. Kontrolujesz kolejność właściwości i strukturę dokumentu, a writer obsługuje składnię JSON oraz kodowanie ciągów.

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

Składnia

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

Utf8JsonWriter z przestrzeni nazw System.Text.Json to niskopoziomowy mechanizm sekwencyjnego zapisu JSON jako bajtów UTF-8 do Stream lub IBufferWriter<byte>. Zamiast automatycznie serializować cały obiekt, jawnie zapisujesz jego właściwości i wartości. Jest przydatny przy tworzeniu własnych serializatorów; nie jest edytowalnym drzewem dokumentu.

Wywołania WriteStartObject() i WriteEndObject() wyznaczają granice obiektu. WriteString("name", "Ada") zapisuje parę nazwa–wartość, natomiast WriteStringValue("csharp") zapisuje samą wartość, na przykład element tablicy. WriteStartArray("tags") rozpoczyna właściwość tablicową, którą zamyka WriteEndArray(). Metody zapisujące ciągi obsługują wymagane znaki ucieczki — nie buduj JSON przez sklejanie tekstu.

Domyślnie wynik jest zwarty, a walidacja struktury włączona; nieprawidłowa kolejność operacji może spowodować InvalidOperationException. JsonWriterOptions pozwala ustawić między innymi Indented oraz SkipValidation. Wyłączenie walidacji przenosi odpowiedzialność za poprawną strukturę na kod wywołujący.

Przed odczytem wyniku wywołaj Flush(), aby przekazać oczekujące bajty do miejsca docelowego. Nie zastępuje to zamknięcia obiektów i tablic odpowiednimi metodami. Użyj using, aby zwolnić writer. W przykładzie Encoding.UTF8.GetString(...) zamienia zapisane bajty na tekst wyłącznie w celu wyświetlenia. Użyte API jest dostępne w .NET 10 i nie wymaga funkcji języka w wersji preview.

Przykłady

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()));

Wynik

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

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła