System.Text.Json'da desteklenen türler

Bu makalede, serileştirme ve seri durumdan çıkarma için hangi türlerin desteklendiğine genel bir bakış sunulmaktadır.

JSON nesneleri olarak seri hale getiren türler

Aşağıdaki türler JSON nesneleri olarak seri hale getir:

  • Sınıflar*
  • Yapılar
  • Arabirim
  • Kayıtlar ve yapı kayıtları

* JSON dizileri olarak IEnumerable<T> serileştirme uygulayan sözlük dışı türler. IEnumerable<T>uygulayan sözlük türleri, JSON nesneleri olarak serileştirir.

Aşağıdaki kod parçacığı basit bir yapının serileştirmesini gösterir.

public static void Main()
{
    var coordinates = new Coords(1.0, 2.0);
    string json = JsonSerializer.Serialize(coordinates);
    Console.WriteLine(json);

    // Output:
    // {"X":1,"Y":2}
}

public readonly struct Coords
{
    public Coords(double x, double y)
    {
        X = x;
        Y = y;
    }

    public double X { get; }
    public double Y { get; }
}

JSON dizileri olarak seri hale getiren türler

.NET koleksiyon türleri JSON dizileri olarak seri hale getirir. System.Text.Json.JsonSerializer, serileştirme için bir koleksiyon türünü destekler:

Seri hale getirici GetEnumerator() yöntemini çağırır ve öğeleri yazar.

Seri durumdan çıkarma daha karmaşıktır ve bazı koleksiyon türleri için desteklenmez.

Aşağıdaki bölümler ad alanına göre düzenlenir ve serileştirme ve seri durumdan çıkarma için hangi türlerin desteklendiği gösterilir.

System.Array ad alanı

Tür Seri -leştirme Seri durumdan çıkarma
Tek boyutlu diziler* ✔️ ✔️
çok boyutlu diziler ❌ ❌
Pürüzlü diziler ✔️ ✔️

* byte[] özel olarak işlenir ve JSON dizisi olarak değil base64 dizesi olarak seri hale getirir.

System.Collections ad alanı

Tür Seri -leştirme Seri durumdan çıkarma
ArrayList ✔️ ✔️
BitArray ✔️ ❌
DictionaryEntry ✔️ ✔️
Hashtable ✔️ ✔️
ICollection ✔️ ✔️
IDictionary ✔️ ✔️
IEnumerable ✔️ ✔️
IList ✔️ ✔️
Queue ✔️ ✔️
SortedList ✔️ ✔️
Stack * ✔️ ✔️

* türleri için Destek gidiş dönüş bölümüne bakın.

System.Collections.Generic ad alanı

Tür Seri -leştirme Seri durumdan çıkarma
Dictionary<TKey,TValue> * ✔️ ✔️
HashSet<T> ✔️ ✔️
IAsyncEnumerable<T> † ✔️ ✔️
ICollection<T> ✔️ ✔️
IDictionary<TKey,TValue> * ✔️ ✔️
IEnumerable<T> ✔️ ✔️
IList<T> ✔️ ✔️
IReadOnlyCollection<T> ✔️ ✔️
IReadOnlyDictionary<TKey,TValue> * ✔️ ✔️
IReadOnlyList<T> ✔️ ✔️
IReadOnlySet<T> § ✔️ ✔️
ISet<T> ✔️ ✔️
KeyValuePair<TKey,TValue> ✔️ ✔️
LinkedList<T> ✔️ ✔️
LinkedListNode<T> ✔️ ❌
List<T> ✔️ ✔️
Queue<T> ✔️ ✔️
SortedDictionary<TKey,TValue> * ✔️ ✔️
SortedList<TKey,TValue> * ✔️ ✔️
SortedSet<T> ✔️ ✔️
Stack<T> ‡ ✔️ ✔️

* Bkz. Desteklenen anahtar türleri.

† IAsyncEnumerable<T>aşağıdaki bölüme bakın.

‡ türleri için bkz. Desteği gidiş dönüş.

§ System.Text.Json .NET 11 ve sonraki sürümlerde desteklerIReadOnlySet<T>. Arabirimi seri durumdan çıkardığınızda seri hale getirici bir HashSet<T> örnek oluşturur. Oluşturulan meta veriler JsonMetadataServices.CreateIReadOnlySetInfo için koleksiyon sözleşmesini oluşturur.

IAsyncEnumerable<T>

Aşağıdaki örneklerde akışlar, zaman uyumsuz veri kaynaklarının bir gösterimi olarak kullanılır. Kaynak, yerel makinedeki dosyalar veya veritabanı sorgusu veya web hizmeti API çağrısının sonuçları olabilir.

Akış serileştirme

System.Text.Json, aşağıdaki örnekte gösterildiği gibi IAsyncEnumerable<T> değerleri JSON dizileri olarak serileştirmeyi destekler:

using System.Text.Json;

namespace IAsyncEnumerableSerialize;

public class Program
{
    public static async Task Main()
    {
        using Stream stream = Console.OpenStandardOutput();
        var data = new { Data = PrintNumbers(3) };
        await JsonSerializer.SerializeAsync(stream, data);
    }

    static async IAsyncEnumerable<int> PrintNumbers(int n)
    {
        for (int i = 0; i < n; i++)
        {
            await Task.Delay(1000);
            yield return i;
        }
    }
}
// output:
//  {"Data":[0,1,2]}

IAsyncEnumerable<T> değerleri yalnızca JsonSerializer.SerializeAsyncgibi zaman uyumsuz serileştirme yöntemleri tarafından desteklenir.

.NET 11 ve sonraki sürümlerde, JsonSerializer.SerializeAsyncEnumerable veya PipeWriteröğesine Stream bir IAsyncEnumerable<T> dizi yazar. varsayılan topLevelValues: falseile yöntemi tek bir kök düzeyi JSON dizisi yazar. Bunun yerine JSON Satırları yazacak şekilde ayarlayıntopLevelValues: true; burada her öğe ayrı bir üst düzey değerdir:

{"id":1,"name":"apple"}
{"id":2,"name":"banana"}

yöntemi, son dahil olmak üzere her değerden sonra tek bir satır akışı (LF), \nyazar. ne olursa olsun JsonSerializerOptions.NewLineher zaman LF kullanır. yöntemi, her değerin tek bir satırda kalması için öğesini yoksayar JsonSerializerOptions.WriteIndented.

Akış seri durumdan çıkarma

DeserializeAsyncEnumerable yöntemi, aşağıdaki örnekte gösterildiği gibi akış seri durumdan çıkarma işlemini destekler:

using System.Text;
using System.Text.Json;

namespace IAsyncEnumerableDeserialize;

public class Program
{
    public static async Task Main()
    {
        using var stream = new MemoryStream(Encoding.UTF8.GetBytes("[0,1,2,3,4]"));
        await foreach (int item in JsonSerializer.DeserializeAsyncEnumerable<int>(stream))
        {
            Console.WriteLine(item);
        }
    }
}
// output:
//0
//1
//2
//3
//4

Varsayılan olarak, JsonSerializer.DeserializeAsyncEnumerable tek bir kök düzeyindeki JSON dizisinden öğeleri okur. Bunun yerine boşlukla ayrılmış üst düzey değerlerin sırasını okumak için ayarlayın topLevelValues: true . Bu giriş biçimi, JSON Çizgilerinin üst kümesidir. Aşırı yüklemeler veya PipeReaderkabul Stream eder.

DeserializeAsync yöntemi IAsyncEnumerable<T>destekler, ancak imzası akışa izin vermez. Aşağıdaki örnekte gösterildiği gibi son sonucu tek bir değer olarak döndürür.

using System.Text;
using System.Text.Json;

namespace IAsyncEnumerableDeserializeNonStreaming;

public class MyPoco
{
    public IAsyncEnumerable<int>? Data { get; set; }
}

public class Program
{
    public static async Task Main()
    {
        using var stream = new MemoryStream(Encoding.UTF8.GetBytes(@"{""Data"":[0,1,2,3,4]}"));
        MyPoco? result = await JsonSerializer.DeserializeAsync<MyPoco>(stream)!;
        await foreach (int item in result!.Data!)
        {
            Console.WriteLine(item);
        }
    }
}
// output:
//0
//1
//2
//3
//4

Bu örnekte seri durumdan çıkarıcı, seri durumdan çıkarılmış nesneyi döndürmeden önce bellekteki tüm IAsyncEnumerable<T> içeriği arabelleğe alır. Seri durumdan çıkarıcının bir sonuç döndürmeden önce JSON yükünün tamamını okuması gerektiğinden bu davranış gereklidir.

System.Collections.Immutable ad alanı

Tür Seri -leştirme Seri durumdan çıkarma
IImmutableDictionary<TKey,TValue> † ✔️ ✔️
IImmutableList<T> ✔️ ✔️
IImmutableQueue<T> ✔️ ✔️
IImmutableSet<T> ✔️ ✔️
IImmutableStack<T> * ✔️ ✔️
ImmutableArray<T> ✔️ ✔️
ImmutableDictionary<TKey,TValue> † ✔️ ✔️
ImmutableHashSet<T> ✔️ ✔️
ImmutableQueue<T> ✔️ ✔️
ImmutableSortedDictionary<TKey,TValue> † ✔️ ✔️
ImmutableSortedSet<T> ✔️ ✔️
ImmutableStack<T> * ✔️ ✔️

* türleri için Destek gidiş dönüş bölümüne bakın.

† Bkz. Desteklenen anahtar türleri.

System.Collections.Specialized ad alanı

Tür Seri -leştirme Seri durumdan çıkarma
BitVector32 ✔️ ❌*
HybridDictionary ✔️ ✔️
IOrderedDictionary ✔️ ❌
ListDictionary ✔️ ✔️
NameValueCollection ✔️ ❌
StringCollection ✔️ ❌
StringDictionary ✔️ ❌

* BitVector32 seri durumdan çıkarıldığında, Data özelliği ortak ayarlayıcıya sahip olmadığından atlanır. Hiçbir özel durum oluşturulur.

System.Collections.Concurrent ad alanı

Tür Seri -leştirme Seri durumdan çıkarma
BlockingCollection<T> ✔️ ❌
ConcurrentBag<T> ✔️ ❌
ConcurrentDictionary<TKey,TValue> † ✔️ ✔️
ConcurrentQueue<T> ✔️ ✔️
ConcurrentStack<T> * ✔️ ✔️

* türleri için Destek gidiş dönüş bölümüne bakın.

† Bkz. Desteklenen anahtar türleri.

System.Collections.ObjectModel ad alanı

Tür Seri -leştirme Seri durumdan çıkarma
Collection<T> ✔️ ✔️
KeyedCollection<dizesi, TValue> * ✔️ ❌
ObservableCollection<T> ✔️ ✔️
ReadOnlyCollection<T> ✔️ ❌
ReadOnlyDictionary<TKey,TValue> ✔️ ❌
ReadOnlyObservableCollection<T> ✔️ ❌

*string olmayan anahtarlar desteklenmez.

Özel koleksiyonlar

Önceki ad alanlarının birinde olmayan herhangi bir koleksiyon türü özel koleksiyon olarak kabul edilir. Bu tür türler, ASP.NET Core tarafından tanımlanan kullanıcı tanımlı türleri ve türleri içerir. Örneğin, Microsoft.Extensions.Primitives bu gruptadır.

Tüm özel koleksiyonlar (IEnumerabletüretilen her şey), öğe türleri desteklendiği sürece serileştirme için desteklenir.

Seri durumdan çıkarma desteği

Özel koleksiyon, seri durumdan çıkarma için şu durumda desteklenir:

Bilinen sorunlar

Aşağıdaki özel koleksiyonlarla ilgili bilinen sorunlar vardır:

Bilinen sorunlar hakkında daha fazla bilgi için bkz. açma sorunları.

Desteklenen anahtar türleri

Dictionary ve SortedList türlerinin anahtarları olarak kullanıldığında, aşağıdaki türlerin yerleşik desteği vardır:

  • BFloat16(.NET 11 ve üzeri)
  • Boolean
  • Byte
  • DateTime
  • DateTimeOffset
  • Decimal
  • Decimal32(.NET 11 ve üzeri)
  • Decimal64(.NET 11 ve üzeri)
  • Decimal128(.NET 11 ve üzeri)
  • Double
  • Enum
  • Guid
  • Int16
  • Int32
  • Int64
  • Object (Yalnızca serileştirmede ve çalışma zamanı türü bu listedeki desteklenen türlerden biriyse.)
  • SByte
  • Single
  • String
  • TimeSpan
  • UInt16
  • UInt32
  • UInt64
  • Uri
  • Version

Ayrıca, JsonConverter<T>.WriteAsPropertyName(Utf8JsonWriter, T, JsonSerializerOptions) ve JsonConverter<T>.ReadAsPropertyName(Utf8JsonReader, Type, JsonSerializerOptions) yöntemleri, seçtiğiniz her tür için sözlük anahtarı desteği eklemenize olanak sağlar.

BFloat16 ve ondalık kayan nokta türleri

.NET 11'den başlayarak , System.Text.Json , Decimal32Decimal64ve Decimal128 türleri için BFloat16yerleşik dönüştürücüler içerir. Sonlu değerler JSON numaraları olarak seri hale getir.

Bu türler, diğer yerleşik sayısal türler gibi davranır:

JsonMetadataServices kaynak tarafından oluşturulan meta veriler için dönüştürücü özelliklerini kullanıma sunar. Özellikleri JsonMetadataServices.BFloat16Converter, JsonMetadataServices.Decimal32Converter, JsonMetadataServices.Decimal64Converter ve JsonMetadataServices.Decimal128Converter'dür.

F# ayrımcı birleşimleri

.NET 11'den başlayarak, sınıf, System.Text.Json yapı ve özyinelemeli birleşimler de dahil olmak üzere F# ayrımcı birleşimlerini serileştirir ve seri durumdan çıkartır:

type Shape =
    | Point
    | Circle of radius: float
  • Alanları olmayan bir servis talebi, gibi büyük/küçük harf adını içeren bir JSON dizesi olarak "Point"seri hale getirmektedir.
  • Alanları olan bir servis talebi JSON nesnesi olarak seri hale getirilmiştir. nesnesi, $type bir ayırıcı ve ardından büyük/küçük harfe ait adlandırılmış alanlar (gibi {"$type":"Circle","radius":3.14}) içerir.

JsonSerializerOptions.PropertyNamingPolicy büyük/küçük harf adlarına ve alan adlarına uygulanır. Büyük/küçük harf düzeyi JsonPropertyNameAttribute önceliklidir. dışında $typebir ayrımcı özellik adı kullanmak için ayarlayın JsonPolymorphicAttribute.TypeDiscriminatorPropertyName.

Important

F# ayrımcı birleşim desteği yalnızca yansımadır. Dinamik kod ve denenmemiş yansıma meta verileri gerektirir. Bunu kaynak oluşturma veya Yerel AOT ile System.Text.Json kullanamazsınız.

Desteklenmeyen türler

Serileştirme için aşağıdaki türler desteklenmez:

System.Data ad alanı

DataSet ad alanında DataTable, System.Datave ilgili türler için yerleşik dönüştürücü yoktur. güvenlik kılavuzuaçıklandığı gibi, bu türlerin güvenilir olmayan girişlerden seri durumdan çıkarılması güvenli değildir. Ancak, bu türleri desteklemek için özel bir dönüştürücü yazabilirsiniz. bir DataTableseri hale getiren ve seri durumdan çıkaran örnek özel dönüştürücü kodu için bkz. RoundtripDataTable.cs.

Ayrıca bkz.

  • Last updated on