Az Utf8JsonWriter használata System.Text.Json

Ez a cikk bemutatja, hogyan használható a Utf8JsonWriter típus egyéni szerializálók készítéséhez.

Utf8JsonWriteraz UTF-8 kódolású JSON-szövegek írásának nagy teljesítményű módja a gyakori .NET-típusokból, például Stringa DateTime. Int32 Az író egy alacsony szintű típus, amely egyéni szerializálók készítésére használható. A JsonSerializer.Serialize módszer a fedelek alatt használja Utf8JsonWriter .

Az alábbi példa az osztály használatát Utf8JsonWriter mutatja be:

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)

Írás UTF-8 szöveggel

A lehető legjobb teljesítmény elérése érdekében az Utf8JsonWriterUTF-16 sztringek helyett már UTF-8 szövegként kódolt JSON-hasznos adatok írása. Az JsonEncodedText ismert sztringtulajdonságok neveit és értékeit statikusként gyorsítótárazhatja és előre kódolhatja, és UTF-16 sztringkonstansok helyett továbbíthatja azokat az írónak. Ez gyorsabb, mint az UTF-8 bájttömbök gyorsítótárazása és használata.

Ez a módszer akkor is működik, ha egyéni menekülést kell végrehajtania. System.Text.Json sztring írása közben nem tilthatja le a menekülést. A saját egyéni beállításokat JavaScriptEncoder azonban átadhatja az írónak, vagy létrehozhatja a sajátját JsonEncodedText , amely a meneküléshez használja JavascriptEncoder , majd a sztring helyett írja be a JsonEncodedText sajátját. További információ: Karakterkódolás testreszabása.

Nyers JSON írása

Bizonyos esetekben érdemes lehet "nyers" JSON-t írni egy JSON-hasznos adatba, amellyel Utf8JsonWriterlétrehoz. Erre használhatja Utf8JsonWriter.WriteRawValue . Íme néhány tipikus forgatókönyv:

• Van egy meglévő JSON-hasznos adata, amelyet az új JSON-ba szeretne belefoglalni.

• Az értékeket az alapértelmezett Utf8JsonWriter formázástól eltérően szeretné formázni.

  Előfordulhat például, hogy testre szeretné szabni a számformázást. Alapértelmezés szerint System.Text.Json kihagyja a tizedesvesszőt egész számok esetében, például írás 1 helyett 1.0. Az ok az, hogy kevesebb bájt írása jó a teljesítményhez. Tegyük fel azonban, hogy a JSON-felhasználó a számokat tizedesjellel, a tizedesjel nélküli számokat pedig egész számként kezeli. Érdemes lehet meggyőződni arról, hogy a tömbben lévő számok mindegyike kettősként van felismerve, ha egész számokhoz tizedesvesszőt és nullát ír. Az alábbi példa bemutatja, hogyan teheti ezt meg:

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

A karakterek szökésének testreszabása

A StringEscapeHandling beállítás az JsonTextWriter összes nem ASCII-karaktert vagy HTML-karaktert elkerülő lehetőségeket kínál. Alapértelmezés szerint Utf8JsonWriter az összes nem ASCII - és HTML-karaktert feloldja. Ez a menekülés védelmi okokból történik. Egy másik menekülési szabályzat megadásához hozzon létre egy és állítsa be a következőt JavaScriptEncoderJsonWriterOptions.Encoder: További információ: Karakterkódolás testreszabása.

Null értékek írása

Null értékek írásához hívja Utf8JsonWritermeg a következőt:

• WriteNull kulcs-érték pár megírása null értékkel.
• WriteNullValue null érték írása JSON-tömb elemeként.

Sztringtulajdonság esetén, ha a sztring null értékű, WriteString és WriteStringValue megegyezik a következővel WriteNull : és WriteNullValue.

Írási idő, Uri vagy karakterértékek

Az íráshoz és az értékek formázásához formázza őket sztringekként (például hívássalToString()) és híváskéntWriteStringValue.charTimespanUri

Lásd még

• Az Utf8JsonReader használata System.Text.Json