Sdílet prostřednictvím

Podporované typy v System.Text.Json

  • Článek

Tento článek poskytuje přehled typů podporovaných pro serializaci a deserializaci.

Typy, které serializují jako objekty JSON

Následující typy serializují jako objekty JSON:

  • Třídy*
  • Struktury
  • Rozhraní
  • Záznamy a záznamy struktury

* Typy bez slovníku, které implementují IEnumerable<T> serializovat jako pole JSON. Typy slovníku, které implementují IEnumerable<T>, serializovat jako objekty JSON.

Následující fragment kódu ukazuje serializaci jednoduché struktury.

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

Typy serializované jako pole JSON

Typy kolekcí .NET serializují jako pole JSON. System.Text.Json.JsonSerializer podporuje typ kolekce pro serializaci, pokud:

Serializátor volá GetEnumerator() metodu a zapisuje prvky.

Deserializace je složitější a u některých typů kolekcí se nepodporuje.

Následující části jsou uspořádány podle oboru názvů a ukazují, které typy jsou podporovány pro serializaci a deserializaci.

Obor názvů System.Array

Typ Serializace Deserializace
jednorozměrných polích ✔️ ✔️
vícerozměrných polích ❌ ❌
jagged arrays ✔️ ✔️

System.Collections – obor názvů

Typ Serializace Deserializace
ArrayList ✔️ ✔️
BitArray ✔️ ❌
DictionaryEntry ✔️ ✔️
Hashtable ✔️ ✔️
ICollection ✔️ ✔️
IDictionary ✔️ ✔️
IEnumerable ✔️ ✔️
IList ✔️ ✔️
Queue ✔️ ✔️
SortedList ✔️ ✔️
Stack * ✔️ ✔️

* Viz Podpora pro Stack typy.

System.Collections.Generic – obor názvů

Typ Serializace Deserializace
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> : ✔️ ✔️

* Viz Podporované typy klíčů.

† Viz následující část IAsyncEnumerable<T>.

• Viz Podpora odezvy pro Stack typy.

IAsyncEnumerable<T>

Následující příklady používají streamy jako reprezentaci libovolného asynchronního zdroje dat. Zdrojem můžou být soubory na místním počítači nebo výsledky z databázového dotazu nebo volání rozhraní API webové služby.

Serializace streamu

System.Text.Json podporuje serializaci hodnot IAsyncEnumerable<T> jako pole JSON, jak je znázorněno v následujícím příkladu:

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> hodnoty jsou podporovány pouze asynchronními serializačními metodami, například JsonSerializer.SerializeAsync.

Deserializace datových proudů

Metoda DeserializeAsyncEnumerable podporuje deserializaci streamování, jak je znázorněno v následujícím příkladu:

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

Metoda DeserializeAsyncEnumerable podporuje čtení pouze z polí JSON na kořenové úrovni.

Metoda DeserializeAsync podporuje IAsyncEnumerable<T>, ale jeho podpis neumožňuje streamování. Vrátí konečný výsledek jako jednu hodnotu, jak je znázorněno v následujícím příkladu.

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

V tomto příkladu deserializátor vyrovnávací paměti všechny IAsyncEnumerable<T> obsah před vrácením deserializovaného objektu. Toto chování je nezbytné, protože deserializátor musí před vrácením výsledku přečíst celou datovou část JSON.

System.Collections.Immutable – obor názvů

Typ Serializace Deserializace
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> * ✔️ ✔️

* Viz Podpora pro Stack typy.

† Viz podporované typy klíčů.

System.Collections.Specialized – obor názvů

Typ Serializace Deserializace
BitVector32 ✔️ ❌*
HybridDictionary ✔️ ✔️
IOrderedDictionary ✔️ ❌
ListDictionary ✔️ ✔️
NameValueCollection ✔️ ❌
StringCollection ✔️ ❌
StringDictionary ✔️ ❌

* Při deserializaci BitVector32 se vlastnost Data přeskočí, protože nemá veřejnou setter. Není vyvolán žádná výjimka.

System.Collections.Concurrent – obor názvů

Typ Serializace Deserializace
BlockingCollection<T> ✔️ ❌
ConcurrentBag<T> ✔️ ❌
ConcurrentDictionary<TKey,TValue> † ✔️ ✔️
ConcurrentQueue<T> ✔️ ✔️
ConcurrentStack<T> * ✔️ ✔️

* Viz Podpora pro Stack typy.

† Viz podporované typy klíčů.

System.Collections.ObjectModel – obor názvů

Typ Serializace Deserializace
Collection<T> ✔️ ✔️
keyedCollection<řetězec, TValue> * ✔️ ❌
ObservableCollection<T> ✔️ ✔️
ReadOnlyCollection<T> ✔️ ❌
ReadOnlyDictionary<TKey,TValue> ✔️ ❌
ReadOnlyObservableCollection<T> ✔️ ❌

* Klíče, které nejsoustring, nejsou podporované.

Vlastní kolekce

Každý typ kolekce, který není v jednom z předchozích oborů názvů, se považuje za vlastní kolekci. Tyto typy zahrnují uživatelem definované typy a typy definované ASP.NET Core. Například Microsoft.Extensions.Primitives je v této skupině.

Všechny vlastní kolekce (vše, co je odvozeno z IEnumerable) jsou podporovány pro serializaci, pokud jsou podporovány jejich typy prvků.

Podpora deserializace

Vlastní kolekce se podporuje pro deserializaci, pokud:

Známé problémy

Existují známé problémy s následujícími vlastními kolekcemi:

Další informace o známých problémech naleznete v otevřené problémy v System.Text.Json.

Podporované typy klíčů

Při použití jako klíče Dictionary a SortedList typů mají následující typy integrovanou podporu:

  • Boolean
  • Byte
  • DateTime
  • DateTimeOffset
  • Decimal
  • Double
  • Enum
  • Guid
  • Int16
  • Int32
  • Int64
  • Object (pouze při serializaci a pokud je typ modulu runtime jedním z podporovaných typů v tomto seznamu.)
  • SByte
  • Single
  • String
  • TimeSpan
  • UInt16
  • UInt32
  • UInt64
  • Uri
  • Version

Kromě toho metody JsonConverter<T>.WriteAsPropertyName(Utf8JsonWriter, T, JsonSerializerOptions) a JsonConverter<T>.ReadAsPropertyName(Utf8JsonReader, Type, JsonSerializerOptions) umožňují přidat podporu klíče slovníku pro libovolný typ vašeho výběru.

Nepodporované typy

Serializace nepodporuje následující typy:

System.Data – obor názvů

Neexistují žádné integrované převaděče pro DataSet, DataTablea související typy v oboru názvů System.Data. Deserializace těchto typů z nedůvěryhodného vstupu není bezpečná, jak je vysvětleno v pokyny k zabezpečení. Můžete však napsat vlastní převaděč pro podporu těchto typů. Vzorový kód vlastního převaděče, který serializuje a deserializuje DataTable, viz RoundtripDataTable.cs.

Viz také