Dil

System.Text.Json içinde Utf8JsonWriter nasıl kullanılır

Bu makale, özel serileştiriciler oluşturmak için Utf8JsonWriter türünün nasıl kullanılacağını gösterir.

Utf8JsonWriter, Stringve Int32gibi DateTimeyaygın .NET türlerinden UTF-8 kodlu JSON metni yazmanın yüksek performanslı bir yoludur. Yazıcı, özel seri hale getiriciler oluşturmak için kullanılabilecek düşük düzeyli bir türdür. JsonSerializer.Serialize yöntemi perde arkasında Utf8JsonWriter kullanır.

Aşağıdaki örnekte sınıfın nasıl kullanılacağı gösterilmektedir Utf8JsonWriter :

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)

Yazma aracını yeniden kullan

.NET 11’den itibaren, bir yazıcı nesnesini yeniden kullanmak için Reset(IBufferWriter<Byte>, JsonWriterOptions) veya Reset(Stream, JsonWriterOptions) çağırın. Bu aşırı yüklemeler, başka bir Utf8JsonWriter tahsis etmeden hedefi ve seçenekleri değiştirir.

Yazıcıyı sıfırlamadan önce mevcut JSON yükünü tamamlayın ve Flush çağrısını yapın. Reset yazma durumunu temizler ve bekleyen çıktıyı boşaltmaz:

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

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

writer.WriteEndObject()
writer.Flush()

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

UTF-8 metniyle yazma

Utf8JsonWriter kullanırken mümkün olan en iyi performansı elde etmek için JSON yüklerini UTF-16 dizeleri yerine önceden UTF-8 olarak kodlanmış metin olarak yazın. UTF-16 dize değişmezleri kullanmak yerine, bilinen dize özellik adlarını ve değerlerini statik olarak önbelleğe almak ve önceden kodlamak ve bunları yazıcıya geçirmek için JsonEncodedText kullanın. Bu, UTF-8 bayt dizilerini önbelleğe almaktan ve kullanmaktan daha hızlıdır.

Bu yaklaşım, özel kaçış yapmanız gerekiyorsa da çalışır. System.Text.Json dize yazarken kaçışı devre dışı bırakmanıza izin vermez. Ancak, yazıcıya bir seçenek olarak kendi özel JavaScriptEncoder öğenizi geçirebilir veya escape işlemini gerçekleştirmek için JavascriptEncoder öğenizi kullanan kendi JsonEncodedText öğenizi oluşturabilir ve ardından dize yerine JsonEncodedText öğesini yazabilirsiniz. Daha fazla bilgi için bkz. Karakter kodlamasını özelleştirme.

Ham JSON yazdır

Bazı senaryolarda, ile Utf8JsonWriteroluşturduğunuz bir JSON yüküne "ham" JSON yazmak isteyebilirsiniz. Bunu yapmak için kullanabilirsiniz Utf8JsonWriter.WriteRawValue . Tipik senaryolar şunlardır:

  • Yeni JSON içine almak istediğiniz mevcut bir JSON yükünüz var.

  • Değerleri varsayılan Utf8JsonWriter biçimlendirmeden farklı biçimlendirmek istiyorsunuz.

    Örneğin, sayı biçimlendirmesini özelleştirmek isteyebilirsiniz. Varsayılan olarak, System.Text.Json tam sayılar için ondalık noktayı atlar; örneğin, 1.0 yerine 1 yazar. Bunun mantığı, daha az bayt yazmanın performans için iyi olmasıdır. Ancak, JSON verinizi kullanan tarafın ondalıklı sayıları double, ondalık içermeyen sayıları ise tamsayı olarak ele aldığını varsayalım. Tam sayılar için ondalık nokta ve sıfır yazarak, bir dizideki sayıların tümünün double olarak algılanmasını sağlamak isteyebilirsiniz. Aşağıdaki örnek bunun nasıl yapılacağını gösterir:

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

Karakter kaçışını özelleştirin

StringEscapeHandling ayarıJsonTextWriter, ASCII olmayan tüm karakterlerden veya HTML karakterlerinden kaçış seçenekleri sunar. Varsayılan olarak, Utf8JsonWriter ASCII olmayan ve HTML olmayan tüm karakterlerden kaçar. Bu kaçış işlemi, katmanlı savunma güvenliği amacıyla yapılır. Farklı bir kaçış ilkesi belirtmek için bir JavaScriptEncoder oluşturun ve JsonWriterOptions.Encoder ayarını yapın. Daha fazla bilgi için bkz. Karakter kodlamasını özelleştirme.

Null değerler yazma

Utf8JsonWriter kullanarak null değerler yazmak için şunu çağırın:

  • WriteNull değeri null olan bir anahtar/değer çifti yazmak için.
  • WriteNullValue JSON dizisinde bir öğe olarak null yazmak için.

Bir dize özelliğinde, dize null ise WriteString ve WriteStringValue, WriteNull ve WriteNullValue ile eşdeğerdir.

Zaman aralığı, Uri veya karakter değerlerini yaz

Timespan, ToString() veya WriteStringValue değerlerini yazmak için, bunları dize olarak biçimlendirin (örneğin, char çağırarak) ve Uri çağrısı yapın.

Ayrıca bakınız

  • Last updated on