Utf8JsonWriter gebruiken in System.Text.Json

In dit artikel wordt beschreven hoe u het type gebruikt voor het Utf8JsonWriter bouwen van aangepaste serializers.

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 onder de dekkingen.

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)

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 uw eigen aangepaste JavaScriptEncoder gegevens echter doorgeven als een optie voor de schrijver of uw eigen JsonEncodedText maken die gebruikmaakt van uw JavascriptEncoder escape-bewerkingen en vervolgens de JsonEncodedText in plaats van de tekenreeks schrijven. Zie Tekencodering aanpassen voor meer informatie.

Onbewerkte JSON schrijven

In sommige scenario's wilt u mogelijk onbewerkte JSON schrijven naar een JSON-nettolading waarmee u maakt Utf8JsonWriter. U kunt dit doen Utf8JsonWriter.WriteRawValue . Hier volgen typische scenario's:

• U hebt een bestaande JSON-nettolading die u wilt insluiten in nieuwe JSON.

• U wilt waarden anders opmaken dan de standaardopmaak Utf8JsonWriter .

  U kunt bijvoorbeeld de getalnotatie aanpassen. System.Text.Json Laat standaard het decimaalteken weg voor gehele getallen, in 1 plaats 1.0van bijvoorbeeld. 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
  //    }
  //  ]
  //}
  

Tekenuitwijken aanpassen

De instelling StringEscapeHandling biedt JsonTextWriter opties om alle niet-ASCII-tekens of HTML-tekens te ontsnappen. 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 als u een sleutel-waardepaar met null wilt schrijven als de waarde.
• WriteNullValue null schrijven als een element van een JSON-matrix.

Als de tekenreeks voor een tekenreekseigenschap null is en WriteStringWriteStringValue gelijk is aan WriteNull en WriteNullValue.

Tijdspanne, URI- of tekenwaarden schrijven

Als u waarden wilt schrijven, Uriof waarden wilt schrijvenTimespan, moet u ze opmaken als tekenreeksen (bijvoorbeeld door aan te roepenToString()) en aanroepenWriteStringValuechar.

Zie ook

• Utf8JsonReader gebruiken in System.Text.Json