Aracılığıyla paylaş

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> ✔️ ✔️
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üş.

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.

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

DeserializeAsyncEnumerable yöntemi yalnızca kök düzeyindeki JSON dizilerinden okumayı destekler.

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:

  • Boolean
  • Byte
  • DateTime
  • DateTimeOffset
  • Decimal
  • 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.

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