Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / C#

Utf8JsonWriter — sekvenční zápis JSON v UTF-8

Utf8JsonWriter z System.Text.Json umožňuje ručně zapisovat JSON jako bajty UTF-8 do Streamu nebo IBufferWriter<byte>. Řídíte pořadí vlastností i strukturu dokumentu, zatímco writer se stará o syntaxi JSON a escapování řetězců.

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

Syntaxe

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

Utf8JsonWriter v oboru názvů System.Text.Json je nízkoúrovňový mechanismus pro sekvenční zápis JSON jako bajtů UTF-8 do Stream nebo IBufferWriter<byte>. Místo automatické serializace celého objektu zapisujete jeho vlastnosti a hodnoty výslovně. Hodí se při vytváření vlastních serializátorů, ale nejde o upravitelný strom dokumentu.

Volání WriteStartObject() a WriteEndObject() vymezují objekt. WriteString("name", "Ada") zapisuje dvojici název–hodnota, zatímco WriteStringValue("csharp") zapisuje pouze hodnotu, například prvek pole. WriteStartArray("tags") zahájí vlastnost pole, kterou uzavře WriteEndArray(). Metody pro zápis řetězců zajišťují potřebné escapování — JSON nevytvářejte spojováním textu.

Ve výchozím nastavení je výstup kompaktní a strukturální validace je zapnutá; neplatná posloupnost operací může způsobit InvalidOperationException. JsonWriterOptions umožňuje nastavit mimo jiné Indented a SkipValidation. Vypnutím validace přechází odpovědnost za správnou strukturu na volající kód.

Před čtením výsledku zavolejte Flush(), aby se čekající bajty předaly do cíle. Tím se nenahrazuje uzavření objektů a polí příslušnými metodami. K uvolnění writeru použijte using. V příkladu převádí Encoding.UTF8.GetString(...) zapsané bajty na text pouze pro zobrazení. Použitá API jsou dostupná v .NET 10 a nevyžadují funkce jazyka ve verzi preview.

Příklady

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

Výsledek

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

Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.

Zdroje