Taal

Utf8JsonWriter gebruiken in System.Text.Json

In dit artikel wordt uitgelegd hoe u het type Utf8JsonWriter gebruikt om aangepaste serialisatoren te bouwen.

Utf8JsonWriter is een krachtige manier om UTF-8 gecodeerde JSON-tekst te schrijven van veelgebruikte .NET-typen, zoals String, Int32en DateTime. De schrijver is een type op laag niveau dat kan worden gebruikt voor het bouwen van aangepaste serializers. De JsonSerializer.Serialize methode gebruikt Utf8JsonWriter achter de schermen.

In het volgende voorbeeld ziet u hoe u de Utf8JsonWriter klasse gebruikt:

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)

Een schrijver opnieuw gebruiken

Vanaf .NET 11 roept u Reset(Stream, JsonWriterOptions) of Reset(IBufferWriter<Byte>, JsonWriterOptions) aan om een writer opnieuw te gebruiken. Deze overbelastingen wijzigen de bestemming en opties zonder een andere Utf8JsonWritertoe te wijzen.

Voordat u de writer opnieuw instelt, rondt u de huidige JSON-payload af en roept u Flush aan. Reset hiermee wordt de schrijfstatus gewist en wordt de uitvoer in behandeling niet leeggemaakt:

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

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

writer.WriteEndObject()
writer.Flush()

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

Schrijven met UTF-8-tekst

Schrijf JSON-nettoladingen die al zijn gecodeerd als UTF-8-tekst in plaats van als UTF-16-tekenreeksen om de best mogelijke prestaties te bereiken tijdens het gebruik van de Utf8JsonWriterJSON-nettoladingen. Gebruik JsonEncodedText dit om namen en waarden van bekende tekenreekseigenschappen in de cache op te slaan en vooraf te coderen als statische waarden en deze door te geven aan de schrijver, in plaats van letterlijke waarden voor UTF-16-tekenreeksen te gebruiken. Dit is sneller dan het opslaan in cache en het gebruik van UTF-8-bytematrices.

Deze aanpak werkt ook als u aangepaste escape-elementen moet uitvoeren. System.Text.Json u kunt geen ontsnapping uitschakelen tijdens het schrijven van een tekenreeks. U kunt echter uw eigen aangepaste JavaScriptEncoder meegeven als optie aan de writer, of uw eigen JsonEncodedText maken die uw JavascriptEncoder gebruikt om het escapen uit te voeren, en vervolgens de JsonEncodedText schrijven in plaats van de tekenreeks. Zie Tekencodering aanpassen voor meer informatie.

Onbewerkte JSON schrijven

In sommige situaties wilt u mogelijk "ruwe" JSON toevoegen aan een JSON-payload die u maakt met Utf8JsonWriter. U kunt Utf8JsonWriter.WriteRawValue gebruiken om dat te doen. Hier volgen typische scenario's:

  • U hebt bestaande JSON-gegevens die u wilt opnemen in nieuwe JSON.

  • U wilt waarden anders opmaken dan de standaardopmaak Utf8JsonWriter .

    U kunt bijvoorbeeld de getalnotatie aanpassen. Standaard laat System.Text.Json de decimale punt weg bij gehele getallen, waarbij bijvoorbeeld 1 wordt geschreven in plaats van 1.0. De reden hiervoor is dat het schrijven van minder bytes goed is voor prestaties. Stel dat de consument van uw JSON getallen met decimalen als dubbele getallen behandelt en getallen zonder decimalen als gehele getallen. U wilt er misschien voor zorgen dat de getallen in een matrix allemaal worden herkend als dubbele waarden door een decimaalteken en nul voor gehele getallen te schrijven. In het volgende voorbeeld ziet u hoe u dit doet:

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

Escaping van tekens aanpassen

De instelling StringEscapeHandling van JsonTextWriter biedt opties om alle niet-ASCII-tekens of HTML-tekens van escapes te voorzien. Utf8JsonWriter Standaard worden alle niet-ASCII- en HTML-tekens escapen. Deze ontsnapping wordt gedaan om diepgaande beveiligingsredenen. Als u een ander escapebeleid wilt opgeven, maakt u een JavaScriptEncoder en stel deze in JsonWriterOptions.Encoder. Zie Tekencodering aanpassen voor meer informatie.

Null-waarden schrijven

Als u null-waarden wilt schrijven met behulp van Utf8JsonWriter, roept u het volgende aan:

  • WriteNull om een sleutel-waardepaar te schrijven met null als waarde.
  • WriteNullValue null schrijven als een element van een JSON-matrix.

Voor een tekenreekseigenschap geldt: als de tekenreeks null is, zijn WriteString en WriteStringValue equivalent aan WriteNull en WriteNullValue.

Tijdspanne, URI- of tekenwaarden schrijven

Als u Uri-, Timespan- of ToString()-waarden wilt schrijven, moet u deze als tekenreeksen opmaken (bijvoorbeeld door WriteStringValue aan te roepen) en char aanroepen.

Zie ook

  • Laatst bijgewerkt om