Sprache

So verwenden Sie Utf8JsonWriter in System.Text.Json

In diesem Artikel wird erläutert, wie Sie den Utf8JsonWriter Typ zum Erstellen von benutzerdefinierten Serialisierern verwenden.

Mit Utf8JsonWriter können UTF-8-codierte JSON-Texte effizient aus gängigen .NET-Typen wie String, Int32 und DateTime geschrieben werden. Der Writer ist ein Low-Level-Typ, der zum Erstellen von benutzerdefinierten Serialisierungsmodulen genutzt werden kann. Die JsonSerializer.Serialize Methode verwendet Utf8JsonWriter unter den Deckeln.

Das folgende Beispiel zeigt die Verwendung der Utf8JsonWriter Klasse:

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)

Wiederverwenden eines Writer

Ab .NET 11 rufen Sie Reset(Stream, JsonWriterOptions) oder Reset(IBufferWriter<Byte>, JsonWriterOptions) auf, um einen Writer wiederzuverwenden. Diese Überladungen ändern das Ziel und die Optionen, ohne ein weiteres Utf8JsonWriter zuzuweisen.

Bevor Sie den Writer zurücksetzen, beenden Sie die aktuelle JSON-Nutzlast und rufen Sie Flush auf. Reset löscht den Writer-Zustand und löscht die ausstehende Ausgabe nicht:

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

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

writer.WriteEndObject()
writer.Flush()

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

Schreiben mit UTF-8-Text

Um bei der Verwendung von Utf8JsonWriter die bestmögliche Leistung zu erzielen, schreiben Sie JSON-Nutzdaten bereits als UTF-8-Text statt als UTF-16-Zeichenfolgen. Verwenden Sie JsonEncodedText, um bekannte Zeichenfolgeneigenschaftsnamen und -werte zwischenzuspeichern und vorab als statische Werte zu codieren und diese an den Ausgabeschreiber zu übergeben, anstatt UTF-16-Zeichenfolgenliterale zu verwenden. Dies ist schneller als das Zwischenspeichern und Verwenden von UTF-8-Bytearrays.

Dieser Ansatz funktioniert auch, wenn Sie eine benutzerdefinierte Escapemethode ausführen müssen. System.Text.Json gestattet Ihnen nicht, während des Schreibens einer Zeichenfolge das Escapen zu deaktivieren. Sie können jedoch eine eigene benutzerdefinierte JavaScriptEncoder als Option an den Writer übergeben oder ein eigenes JavascriptEncoder erstellen, das Ihr JsonEncodedText zum Escaping verwendet, und dann das JsonEncodedText anstelle der Zeichenfolge schreiben. Weitere Informationen finden Sie unter Anpassen der Zeichencodierung.

Roh-JSON schreiben

In einigen Szenarien möchten Sie möglicherweise rohes JSON in eine JSON-Nutzlast schreiben, die Sie mit Utf8JsonWriter erstellen. Sie können dazu Utf8JsonWriter.WriteRawValue verwenden. Hier sind typische Szenarien:

  • Sie verfügen über eine vorhandene JSON-Nutzlast, die Sie in neuen JSON-Code einschließen möchten.

  • Sie möchten Werte anders formatieren als die Standardformatierung Utf8JsonWriter .

    Beispielsweise möchten Sie die Zahlenformatierung anpassen. Standardmäßig lässt System.Text.Json bei ganzen Zahlen das Dezimaltrennzeichen weg und schreibt beispielsweise 1 statt 1.0. Der Grund dafür ist, dass das Schreiben weniger Bytes für die Leistung gut ist. Aber nehmen wir an, der Empfänger Ihres JSON behandelt Zahlen mit Dezimalstellen als Double-Werte und Zahlen ohne Dezimalstellen als ganze Zahlen. Möglicherweise möchten Sie sicherstellen, dass alle Zahlen in einem Array als Double-Werte erkannt werden, indem Sie bei ganzen Zahlen einen Punkt und eine Null schreiben. Das folgende Beispiel zeigt, wie Sie dabei vorgehen müssen:

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

Anpassen des Ausfangens von Zeichen

Die Einstellung "JsonTextWriter StringEscapeHandling" bietet Optionen zum Escapen aller Nicht-ASCII-Zeichen oder HTML-Zeichen. Standardmäßig maskiert Utf8JsonWriter alle Nicht-ASCII-und HTML-Zeichen. Dieses Escapen erfolgt als tief greifende Abwehr aus Gründen des Schutzes. Um eine andere Escape-Richtlinie anzugeben, erstellen Sie eine JavaScriptEncoder und legen Sie JsonWriterOptions.Encoder fest. Weitere Informationen finden Sie unter Anpassen der Zeichencodierung.

Nullwerte schreiben

Um NULL-Werte mithilfe von Utf8JsonWriter zu schreiben, rufen Sie Folgendes auf:

  • WriteNull um ein Schlüssel-Wert-Paar mit NULL als Wert zu schreiben.
  • WriteNullValue null als Element eines JSON-Arrays zu schreiben.

Bei einer Zeichenfolgeneigenschaft sind, wenn die Zeichenfolge null ist, WriteString und WriteStringValue äquivalent zu WriteNull und WriteNullValue.

Schreiben von TimeSpan-, Uri- oder char-Werten

Um Timespan-, Uri- oder char-Werte zu schreiben, formatieren Sie sie als Zeichenfolgen, indem Sie beispielsweise ToString() aufrufen, und rufen Sie WriteStringValue auf.

Siehe auch

  • Zuletzt aktualisiert um