Obsługiwane typy kolekcji w programie System.Text.Json
Ten artykuł zawiera omówienie kolekcji obsługiwanych w przypadku serializacji i deserializacji. System.Text.Json.JsonSerializer program obsługuje typ kolekcji dla serializacji, jeśli:
- Pochodzi z IEnumerable lub IAsyncEnumerable<T>
- Zawiera elementy, które można serializować.
Serializator wywołuje metodę GetEnumerator() i zapisuje elementy.
Deserializacja jest bardziej skomplikowana i nie jest obsługiwana w przypadku niektórych typów kolekcji.
Poniższe sekcje są uporządkowane według przestrzeni nazw i pokazują, które typy są obsługiwane w przypadku serializacji i deserializacji.
Przestrzeń nazw System.Array
Typ | Serializacja | Deserializacji |
---|---|---|
Tablice jednowymiarowe | ✔️ | ✔️ |
Tablice wielowymiarowe | ❌ | ❌ |
Tablice postrzępione | ✔️ | ✔️ |
Przestrzeń nazw System.Collections
Typ | Serializacja | Deserializacji |
---|---|---|
ArrayList | ✔️ | ✔️ |
BitArray | ✔️ | ❌ |
DictionaryEntry | ✔️ | ✔️ |
Hashtable | ✔️ | ✔️ |
ICollection | ✔️ | ✔️ |
IDictionary | ✔️ | ✔️ |
IEnumerable | ✔️ | ✔️ |
IList | ✔️ | ✔️ |
Queue | ✔️ | ✔️ |
SortedList | ✔️ | ✔️ |
Stack * | ✔️ | ✔️ |
* Zobacz Obsługa rundy dla Stack
typów.
System.Collections.Generic, przestrzeń nazw
Typ | Serializacja | Deserializacji |
---|---|---|
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> ‡ | ✔️ | ✔️ |
* Zobacz Obsługiwane typy kluczy.
† Zobacz następującą sekcję w temacie IAsyncEnumerable<T>
.
‹ Zobacz Obsługa rundy dla Stack
typów.
IAsyncEnumerable<T>
W poniższych przykładach strumienie są używane jako reprezentacja dowolnego asynchronicznego źródła danych. Źródłem mogą być pliki na komputerze lokalnym lub wyniki z zapytania bazy danych lub wywołania interfejsu API usługi internetowej.
Serializacja strumienia
System.Text.Json
program obsługuje serializacji IAsyncEnumerable<T> wartości jako tablice JSON, jak pokazano w poniższym przykładzie:
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>
wartości są obsługiwane tylko przez metody serializacji asynchronicznej, takie jak JsonSerializer.SerializeAsync.
Deserializacja strumienia
Metoda DeserializeAsyncEnumerable
obsługuje deserializacji przesyłania strumieniowego, jak pokazano w poniższym przykładzie:
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
obsługuje tylko odczytywanie z tablic JSON na poziomie głównym.
Metoda DeserializeAsync obsługuje IAsyncEnumerable<T>
metodę , ale jej podpis nie zezwala na przesyłanie strumieniowe. Zwraca końcowy wynik jako pojedynczą wartość, jak pokazano w poniższym przykładzie.
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
W tym przykładzie deserializator buforuje całą IAsyncEnumerable<T>
zawartość w pamięci przed zwróceniem zdeserializowanego obiektu. To zachowanie jest konieczne, ponieważ deserializator musi odczytać cały ładunek JSON przed zwróceniem wyniku.
System.Collections.Niezmienna przestrzeń nazw
Typ | Serializacja | Deserializacji |
---|---|---|
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> * | ✔️ | ✔️ |
* Zobacz Obsługa rundy dla Stack
typów.
† Zobacz Obsługiwane typy kluczy.
System.Collections.Wyspecjalizowana przestrzeń nazw
Typ | Serializacja | Deserializacji |
---|---|---|
BitVector32 | ✔️ | ❌* |
HybridDictionary | ✔️ | ✔️ |
IOrderedDictionary | ✔️ | ❌ |
ListDictionary | ✔️ | ✔️ |
NameValueCollection | ✔️ | ❌ |
StringCollection | ✔️ | ❌ |
StringDictionary | ✔️ | ❌ |
* W przypadku BitVector32 deserializacji właściwość jest pomijana, Data ponieważ nie ma publicznego zestawu. Wyjątek nie jest zgłaszany.
System.Collections.Concurrent, przestrzeń nazw
Typ | Serializacja | Deserializacji |
---|---|---|
BlockingCollection<T> | ✔️ | ❌ |
ConcurrentBag<T> | ✔️ | ❌ |
ConcurrentDictionary<TKey,TValue> † | ✔️ | ✔️ |
ConcurrentQueue<T> | ✔️ | ✔️ |
ConcurrentStack<T> * | ✔️ | ✔️ |
* Zobacz Obsługa rundy dla Stack
typów.
† Zobacz Obsługiwane typy kluczy.
Przestrzeń nazw System.Collections.ObjectModel
Typ | Serializacja | Deserializacji |
---|---|---|
Collection<T> | ✔️ | ✔️ |
Ciąg KeyedCollection<, TValue> * | ✔️ | ❌ |
ObservableCollection<T> | ✔️ | ✔️ |
ReadOnlyCollection<T> | ✔️ | ❌ |
ReadOnlyDictionary<TKey,TValue> | ✔️ | ❌ |
ReadOnlyObservableCollection<T> | ✔️ | ❌ |
* Klucze innestring
niż klucze nie są obsługiwane.
Kolekcje niestandardowe
Każdy typ kolekcji, który nie znajduje się w jednej z poprzednich przestrzeni nazw, jest uważany za kolekcję niestandardową. Takie typy obejmują typy zdefiniowane przez użytkownika i typy zdefiniowane przez ASP.NET Core. Na przykład Microsoft.Extensions.Primitives znajduje się w tej grupie.
Wszystkie kolekcje niestandardowe (wszystkie kolekcje pochodzące z IEnumerable
programu ) są obsługiwane na potrzeby serializacji, o ile ich typy elementów są obsługiwane.
Kolekcje niestandardowe z obsługą deserializacji
Kolekcja niestandardowa jest obsługiwana w przypadku deserializacji, jeśli:
Nie jest interfejsem ani abstrakcją.
Ma konstruktor bez parametrów.
Zawiera typy elementów obsługiwane przez JsonSerializerprogram .
Implementuje lub dziedziczy co najmniej jeden z następujących interfejsów lub klas:
- ConcurrentQueue<T>
- ConcurrentStack<T> *
- ICollection<T>
- IDictionary
- IDictionary<TKey,TValue> †
- IList
- IList<T>
- Queue
- Queue<T>
- Stack *
- Stack<T> *
* Zobacz Obsługa rundy dla
Stack
typów.† Zobacz Obsługiwane typy kluczy.
Kolekcje niestandardowe ze znanymi problemami
Istnieją znane problemy z następującymi kolekcjami niestandardowymi:
- ExpandoObject: zobacz dotnet/runtime#29690.
- DynamicObject: zobacz dotnet/runtime#1808.
- DataTable: Zobacz dotnet/docs#21366.
- Microsoft.AspNetCore.Http.FormFile: Zobacz dotnet/runtime#1559.
- Microsoft.AspNetCore.Http.IFormCollection: Zobacz dotnet/runtime#1559.
Aby uzyskać więcej informacji na temat znanych problemów, zobacz otwarte problemy w programie System.Text.Json.
Obsługiwane typy kluczy
Obsługiwane typy kluczy Dictionary
i SortedList
obejmują następujące typy:
Boolean
Byte
DateTime
DateTimeOffset
Decimal
Double
Enum
Guid
Int16
Int32
Int64
Object
(Tylko w przypadku serializacji i jeśli typ środowiska uruchomieniowego jest jednym z obsługiwanych typów na tej liście).SByte
Single
String
UInt16
UInt32
UInt64
Przestrzeń nazw System.Data
Brak wbudowanych konwerterów dla DataSettypów , DataTablei powiązanych w System.Data przestrzeni nazw. Deserializacja tych typów z niezaufanych danych wejściowych nie jest bezpieczna, jak wyjaśniono we wskazówkach dotyczących zabezpieczeń. Można jednak napisać konwerter niestandardowy, aby obsługiwać te typy. Aby uzyskać przykładowy kod konwertera niestandardowego, który serializuje i deserializuje element DataTable
, zobacz RoundtripDataTable.cs.
Zobacz też
Opinia
https://aka.ms/ContentUserFeedback.
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź:Prześlij i wyświetl opinię dla