Använda Utf8JsonWriter i System.Text.Json

Den här artikeln visar hur du använder Utf8JsonWriter typen för att skapa anpassade serialiserare.

Utf8JsonWriter är ett högpresterande sätt att skriva UTF-8-kodad JSON-text från vanliga .NET-typer som String, Int32och DateTime. Skrivaren är en lågnivåtyp som kan användas för att skapa anpassade serialiserare. Metoden JsonSerializer.Serialize används Utf8JsonWriter under täcket.

I följande exempel visas hur du Utf8JsonWriter använder klassen:

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)

Skriva med UTF-8-text

För att uppnå bästa möjliga prestanda när du använder Utf8JsonWriter, skriver du JSON-nyttolaster som redan kodas som UTF-8-text i stället för som UTF-16-strängar. Använd JsonEncodedText för att cachelagera och förkoda kända strängegenskapsnamn och värden som statiska värden och skicka dem till skrivaren i stället för att använda UTF-16-strängliteraler. Detta går snabbare än cachelagring och användning av UTF-8 byte-matriser.

Den här metoden fungerar också om du behöver göra en anpassad undflyende. System.Text.Json tillåter inte att du inaktiverar undflyende när du skriver en sträng. Du kan dock skicka in din egen anpassade JavaScriptEncoder som ett alternativ till skrivaren, eller skapa en egen JsonEncodedText som använder din JavascriptEncoder för att göra flykten och sedan skriva JsonEncodedText i stället för strängen. Mer information finns i Anpassa teckenkodning.

Skriv rå JSON

I vissa scenarier kanske du vill skriva "raw" JSON till en JSON-nyttolast som du skapar med Utf8JsonWriter. Du kan använda Utf8JsonWriter.WriteRawValue för att göra det. Här är vanliga scenarier:

• Du har en befintlig JSON-nyttolast som du vill omsluta i ny JSON.

• Du vill formatera värden på ett annat sätt än standardformateringen Utf8JsonWriter .

  Du kanske till exempel vill anpassa talformatering. Som standard System.Text.Json utelämnar decimaltecknet för heltal, skriver 1 i stället 1.0för , till exempel. Anledningen är att skriva färre byte är bra för prestanda. Anta dock att JSON-konsumenten behandlar tal med decimaler som dubblar och tal utan decimaler som heltal. Du kanske vill se till att talen i en matris identifieras som dubblar genom att skriva en decimalpunkt och noll för heltal. I följande exempel visas hur du gör det:

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

Anpassa teckenundflytande

StringEscapeHandling-inställningen JsonTextWriter för erbjuder alternativ för att undkomma alla icke-ASCII-tecken eller HTML-tecken. Som standard Utf8JsonWriter undflys alla icke-ASCII - och HTML-tecken. Den här utrymningen görs av försvarsdjupa säkerhetsskäl. Om du vill ange en annan princip för undantag skapar du en JavaScriptEncoder och anger JsonWriterOptions.Encoder. Mer information finns i Anpassa teckenkodning.

Skriva null-värden

Om du vill skriva null-värden med hjälp Utf8JsonWriterav anropar du:

• WriteNull för att skriva ett nyckel/värde-par med null som värde.
• WriteNullValue för att skriva null som ett element i en JSON-matris.

Om strängen är null WriteString för en strängegenskap och WriteStringValue motsvarar WriteNull och WriteNullValue.

Skriv tidsintervall, Uri eller teckenvärden

Om du vill skriva , eller värden formaterar du dem som strängar (genom att anropa ToString(), till exempel) och anropa WriteStringValue.charUriTimespan

Se även

• Använda Utf8JsonReader i System.Text.Json