CKTIS / C#
Utf8JsonWriter — sequenzielles Schreiben von JSON in UTF-8
Utf8JsonWriter aus System.Text.Json ermöglicht es, JSON manuell als UTF-8-Bytes in einen Stream oder IBufferWriter<byte> zu schreiben. Sie bestimmen die Reihenfolge der Eigenschaften und die Dokumentstruktur; der Writer kümmert sich um die JSON-Syntax und das Escaping von Zeichenfolgen.
Version: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Syntax
using var writer = new Utf8JsonWriter(destination, new JsonWriterOptions { Indented = false });
writer.WriteStartObject();
writer.WriteString("name", "Ada");
writer.WriteEndObject();
writer.Flush();Utf8JsonWriter im Namespace System.Text.Json ist eine Funktion auf niedriger Ebene, mit der JSON sequenziell als UTF-8-Bytes in einen Stream oder IBufferWriter<byte> geschrieben wird. Statt ein ganzes Objekt automatisch zu serialisieren, schreiben Sie dessen Eigenschaften und Werte ausdrücklich. Das ist nützlich, wenn Sie eigene Serialisierer erstellen; der Writer ist jedoch kein bearbeitbarer Dokumentbaum.
Die Aufrufe WriteStartObject() und WriteEndObject() markieren Anfang und Ende eines Objekts. WriteString("name", "Ada") schreibt ein Name-Wert-Paar, während WriteStringValue("csharp") nur einen Wert schreibt, etwa ein Arrayelement. WriteStartArray("tags") beginnt eine Array-Eigenschaft, die mit WriteEndArray() geschlossen wird. Methoden zum Schreiben von Zeichenfolgen übernehmen das erforderliche Escaping – erstellen Sie JSON nicht durch das Zusammenfügen von Text.
Standardmäßig ist die Ausgabe kompakt und die Strukturvalidierung aktiviert; eine ungültige Operationsfolge kann eine InvalidOperationException auslösen. Mit JsonWriterOptions können Sie unter anderem Indented und SkipValidation einstellen. Wenn Sie die Validierung deaktivieren, ist der aufrufende Code für die korrekte Struktur verantwortlich.
Rufen Sie vor dem Lesen des Ergebnisses Flush() auf, damit ausstehende Bytes an das Ziel übertragen werden. Dadurch wird das Schließen von Objekten und Arrays mit den entsprechenden Methoden nicht ersetzt. Verwenden Sie using, um den Writer freizugeben. Im Beispiel wandelt Encoding.UTF8.GetString(...) die geschriebenen Bytes ausschließlich zur Anzeige in Text um. Die verwendeten APIs sind in .NET 10 verfügbar und erfordern keine Preview-Sprachfunktionen.
Beispiele
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()));Ergebnis
{"name":"Ada","score":42,"tags":["csharp","json"]}Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.