Bagikan melalui

Jenis koleksi yang didukung di System.Text.Json

  • Artikel

Artikel ini memberikan gambaran umum tentang koleksi mana yang didukung untuk serialisasi dan deserialisasi. System.Text.Json.JsonSerializer mendukung jenis koleksi untuk serialisasi jika:

Serializer memanggil GetEnumerator() metode dan menulis elemen.

Deserialisasi lebih rumit dan tidak didukung untuk beberapa jenis koleksi.

Bagian berikut diatur menurut namespace layanan dan menunjukkan jenis mana yang didukung untuk serialisasi dan deserialisasi.

Namespace System.Array

Jenis Serialisasi Deserialisasi
Array Satu Dimensi ✔️ ✔️
Array multi-dimensi ❌ ❌
Array Bergerigi ✔️ ✔️

Namespace layanan System.Collections

Jenis Serialisasi Deserialisasi
ArrayList ✔️ ✔️
BitArray ✔️ ❌
DictionaryEntry ✔️ ✔️
Hashtable ✔️ ✔️
ICollection ✔️ ✔️
IDictionary ✔️ ✔️
IEnumerable ✔️ ✔️
IList ✔️ ✔️
Queue ✔️ ✔️
SortedList ✔️ ✔️
Stack * ✔️ ✔️

* Lihat Dukungan pulang pergi untuk Stack jenis.

Namespace layanan System.Collections.Generic

Jenis Serialisasi Deserialisasi
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> ‡ ✔️ ✔️

* Lihat Jenis kunci yang didukung.

† Lihat bagian berikut di IAsyncEnumerable<T>.

‡ Lihat Dukungan pulang pergi untuk Stack jenis.

IAsyncEnumerable<T>

Contoh berikut menggunakan aliran sebagai representasi dari sumber data asinkron apa pun. Sumbernya bisa berupa file di komputer lokal, atau hasil dari kueri database atau panggilan API layanan web.

Serialisasi aliran

System.Text.Json mendukung serialisasi nilai IAsyncEnumerable<T> sebagai array JSON, seperti yang ditunjukkan dalam contoh berikut:

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

Nilai IAsyncEnumerable<T> hanya didukung oleh metode serialisasi asinkron, seperti JsonSerializer.SerializeAsync.

Deserialisasi aliran

Metode DeserializeAsyncEnumerable ini mendukung deserialisasi streaming, seperti yang ditunjukkan dalam contoh berikut:

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

Metode DeserializeAsyncEnumerable ini hanya mendukung pembacaan dari array JSON tingkat-akar.

Metode DeserializeAsync ini mendukung IAsyncEnumerable<T>, tetapi tanda tangannya tidak mengizinkan streaming. Metode ini mengembalikan hasil akhir sebagai nilai tunggal, seperti yang ditunjukkan dalam contoh berikut.

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

Dalam contoh ini, deserializer menyangga semua konten IAsyncEnumerable<T> dalam memori sebelum mengembalikan objek yang dideserialisasi. Perilaku ini diperlukan karena deserializer perlu membaca seluruh payload JSON sebelum mengembalikan hasil.

Namespace layanan System.Collections.Immutable

Jenis Serialisasi Deserialisasi
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> * ✔️ ✔️

* Lihat Dukungan pulang pergi untuk Stack jenis.

† Lihat Jenis kunci yang didukung.

Namespace layanan System.Collections.Specialized

Jenis Serialisasi Deserialisasi
BitVector32 ✔️ ❌*
HybridDictionary ✔️ ✔️
IOrderedDictionary ✔️ ❌
ListDictionary ✔️ ✔️
NameValueCollection ✔️ ❌
StringCollection ✔️ ❌
StringDictionary ✔️ ❌

* Ketika BitVector32 dideserialisasi, properti Data dilewati karena tidak memiliki setter publik. Tidak ada pengecualian yang ditampilkan.

Namespace layanan System.Collections.Concurrent

Jenis Serialisasi Deserialisasi
BlockingCollection<T> ✔️ ❌
ConcurrentBag<T> ✔️ ❌
ConcurrentDictionary<TKey,TValue> † ✔️ ✔️
ConcurrentQueue<T> ✔️ ✔️
ConcurrentStack<T> * ✔️ ✔️

* Lihat Dukungan pulang pergi untuk Stack jenis.

† Lihat Jenis kunci yang didukung.

Namespace layanan System.Collections.ObjectModel

Jenis Serialisasi Deserialisasi
Collection<T> ✔️ ✔️
String KeyedCollection<, TValue> * ✔️ ❌
ObservableCollection<T> ✔️ ✔️
ReadOnlyCollection<T> ✔️ ❌
ReadOnlyDictionary<TKey,TValue> ✔️ ❌
ReadOnlyObservableCollection<T> ✔️ ❌

* Non-kuncistring tidak didukung.

Koleksi kustom

Jenis koleksi apa pun yang tidak ada di salah satu namespace layanan sebelumnya dianggap sebagai koleksi kustom. Jenis semacam ini termasuk jenis yang ditentukan pengguna dan jenis yang ditentukan oleh ASP.NET Core. Misalnya, Microsoft.Extensions.Primitives ada dalam kelompok ini.

Semua koleksi kustom (semua yang berasal dari IEnumerable) didukung untuk serialisasi, selama jenis elemennya didukung.

Koleksi kustom dengan dukungan deserialisasi

Koleksi kustom didukung untuk deserialisasi jika:

Koleksi kustom dengan masalah yang diketahui

Ada masalah yang diketahui pada koleksi kustom berikut:

Untuk informasi selengkapnya tentang masalah umum, lihat buka masalah diSystem.Text.Json.

Jenis kunci yang didukung

Jenis yang didukung untuk kunci dan jenis Dictionary dan SortedList meliputi yang berikut ini:

  • Boolean
  • Byte
  • DateTime
  • DateTimeOffset
  • Decimal
  • Double
  • Enum
  • Guid
  • Int16
  • Int32
  • Int64
  • Object (Hanya pada serialisasi dan jika jenis runtime adalah salah satu jenis yang didukung dalam daftar ini.)
  • SByte
  • Single
  • String
  • UInt16
  • UInt32
  • UInt64

Namespace layanan System.Data

Tidak ada konverter bawaan untuk DataSet, DataTable, dan jenis terkait di namespace System.Data. Deserialisasi jenis ini dari input yang tidak tepercaya tidak aman, seperti yang dijelaskan dalam panduan keamanan. Namun, Anda dapat menulis pengonversi kustom untuk mendukung jenis ini. Untuk contoh kode pengonversi kustom yang menserialisasikan dan mendeserialisasi DataTable, lihat RoundtripDataTable.cs.

Baca juga