Supported collection types in System.Text.Json
This article gives an overview of which collections are supported for serialization and deserialization. System.Text.Json.JsonSerializer supports a collection type for serialization if it:
- Derives from IEnumerable.
- Contains elements that are serializable.
The serializer calls the GetEnumerator() method, and writes the elements.
Deserialization is more complicated and is not supported for some collection types.
The following sections are organized by namespace and show which types are supported for serialization and deserialization.
System.Array namespace
Type | Serialization | Deserialization |
---|---|---|
Single-dimensional arrays | ✔️ | ✔️ |
Multi-dimensional arrays | ❌ | ❌ |
Jagged arrays | ✔️ | ✔️ |
System.Collections namespace
Type | Serialization | Deserialization |
---|---|---|
ArrayList | ✔️ | ✔️ |
BitArray | ✔️ | ❌ |
DictionaryEntry | ✔️ | ✔️ |
Hashtable | ✔️ | ✔️ |
Queue | ✔️ | ✔️ |
SortedList | ✔️ | ✔️ |
Stack | ✔️ | ✔️ |
ICollection | ✔️ | ✔️ |
IDictionary | ✔️ | ✔️ |
IEnumerable | ✔️ | ✔️ |
IList | ✔️ | ✔️ |
System.Collections.Generic namespace
Type | Serialization | Deserialization |
---|---|---|
Dictionary<TKey,TValue> * | ✔️ | ✔️ |
HashSet<T> | ✔️ | ✔️ |
KeyValuePair<TKey,TValue> | ✔️ | ✔️ |
LinkedList<T> | ✔️ | ✔️ |
LinkedListNode<T> | ✔️ | ❌ |
List<T> | ✔️ | ✔️ |
Queue<T> | ✔️ | ✔️ |
SortedDictionary<TKey,TValue> * | ✔️ | ✔️ |
SortedList<TKey,TValue> * | ✔️ | ✔️ |
SortedSet<T> | ✔️ | ✔️ |
Stack<T> | ✔️ | ✔️ |
IAsyncEnumerable<T> | ❌ | ❌ |
ICollection<T> | ✔️ | ✔️ |
IDictionary<TKey,TValue> * | ✔️ | ✔️ |
IEnumerable<T> | ✔️ | ✔️ |
IList<T> | ✔️ | ✔️ |
IReadOnlyCollection<T> | ✔️ | ✔️ |
IReadOnlyDictionary<TKey,TValue> * | ✔️ | ✔️ |
IReadOnlyList<T> | ✔️ | ✔️ |
ISet<T> | ✔️ | ✔️ |
Type | Serialization | Deserialization |
---|---|---|
Dictionary<string, TValue> * | ✔️ | ✔️ |
HashSet<T> | ✔️ | ✔️ |
KeyValuePair<TKey,TValue> | ✔️ | ✔️ |
LinkedList<T> | ✔️ | ✔️ |
LinkedListNode<T> | ✔️ | ❌ |
List<T> | ✔️ | ✔️ |
Queue<T> | ✔️ | ✔️ |
SortedDictionary<string, TValue> * | ✔️ | ✔️ |
SortedList<string, TValue> * | ✔️ | ✔️ |
SortedSet<T> | ✔️ | ✔️ |
Stack<T> | ✔️ | ✔️ |
IAsyncEnumerable<T> | ❌ | ❌ |
ICollection<T> | ✔️ | ✔️ |
IDictionary<string, TValue> * | ✔️ | ✔️ |
IEnumerable<T> | ✔️ | ✔️ |
IList<T> | ✔️ | ✔️ |
IReadOnlyCollection<T> | ✔️ | ✔️ |
IReadOnlyDictionary<string, TValue> * | ✔️ | ✔️ |
IReadOnlyList<T> | ✔️ | ✔️ |
ISet<T> | ✔️ | ✔️ |
* See Supported key types.
System.Collections.Immutable namespace
Type | Serialization | Deserialization |
---|---|---|
ImmutableArray<T> | ✔️ | ✔️ |
ImmutableDictionary<TKey,TValue> ** | ✔️ | ✔️ |
ImmutableHashSet<T> | ✔️ | ✔️ |
IImmutableList<T> | ✔️ | ✔️ |
ImmutableQueue<T> | ✔️ | ✔️ |
ImmutableSortedDictionary<TKey,TValue> ** | ✔️ | ✔️ |
ImmutableSortedSet<T> | ✔️ | ✔️ |
ImmutableStack<T> * | ✔️ | ✔️ |
IImmutableDictionary<TKey,TValue> ** | ✔️ | ✔️ |
IImmutableList<T> | ✔️ | ✔️ |
IImmutableQueue<T> | ✔️ | ✔️ |
IImmutableSet<T> | ✔️ | ✔️ |
IImmutableStack<T> * | ✔️ | ✔️ |
Type | Serialization | Deserialization |
---|---|---|
ImmutableArray<T> | ✔️ | ✔️ |
ImmutableDictionary<string, TValue> ** | ✔️ | ✔️ |
ImmutableHashSet<T> | ✔️ | ✔️ |
IImmutableList<T> | ✔️ | ✔️ |
ImmutableQueue<T> | ✔️ | ✔️ |
ImmutableSortedDictionary<string, TValue> ** | ✔️ | ✔️ |
ImmutableSortedSet<T> | ✔️ | ✔️ |
ImmutableStack<T> * | ✔️ | ✔️ |
IImmutableDictionary<string, TValue> ** | ✔️ | ✔️ |
IImmutableList<T> | ✔️ | ✔️ |
IImmutableQueue<T> | ✔️ | ✔️ |
IImmutableSet<T> | ✔️ | ✔️ |
IImmutableStack<T> * | ✔️ | ✔️ |
* See Support round trip for Stack<T>.
** See Supported key types.
System.Collections.Specialized namespace
Type | Serialization | Deserialization |
---|---|---|
BitVector32 | ✔️ | ❌* |
HybridDictionary | ✔️ | ✔️ |
IOrderedDictionary | ✔️ | ❌ |
ListDictionary | ✔️ | ✔️ |
StringCollection | ✔️ | ❌ |
StringDictionary | ✔️ | ❌ |
NameValueCollection | ✔️ | ❌ |
* When BitVector32 is deserialized, the Data property is skipped because it doesn't have a public setter. No exception is thrown.
System.Collections.Concurrent namespace
Type | Serialization | Deserialization |
---|---|---|
BlockingCollection<T> | ✔️ | ❌ |
ConcurrentBag<T> | ✔️ | ❌ |
ConcurrentDictionary<TKey,TValue> ** | ✔️ | ✔️ |
ConcurrentQueue<T> | ✔️ | ✔️ |
ConcurrentStack<T> * | ✔️ | ✔️ |
Type | Serialization | Deserialization |
---|---|---|
BlockingCollection<T> | ✔️ | ❌ |
ConcurrentBag<T> | ✔️ | ❌ |
ConcurrentDictionary<string, TValue> ** | ✔️ | ✔️ |
ConcurrentQueue<T> | ✔️ | ✔️ |
ConcurrentStack<T> * | ✔️ | ✔️ |
* See Support round trip for Stack<T>.
** See Supported key types.
System.Collections.ObjectModel namespace
Type | Serialization | Deserialization |
---|---|---|
Collection<T> | ✔️ | ✔️ |
KeyedCollection<string, TValue> * | ✔️ | ❌ |
ObservableCollection<T> | ✔️ | ✔️ |
ReadOnlyCollection<T> | ✔️ | ❌ |
ReadOnlyDictionary<TKey,TValue> | ✔️ | ❌ |
ReadOnlyObservableCollection<T> | ✔️ | ❌ |
* Non-string
keys are not supported.
Type | Serialization | Deserialization |
---|---|---|
Collection<T> | ✔️ | ✔️ |
KeyedCollection<string, TValue> * | ✔️ | ❌ |
ObservableCollection<T> | ✔️ | ✔️ |
ReadOnlyCollection<T> | ✔️ | ❌ |
ReadOnlyDictionary<string, TValue> * | ✔️ | ❌ |
ReadOnlyObservableCollection<T> | ✔️ | ❌ |
* See Supported key types.
Custom collections
Any collection type that isn't in one of the preceding namespaces is considered a custom collection. Such types include user-defined types and types defined by ASP.NET Core. For example, Microsoft.Extensions.Primitives is in this group.
All custom collections (everything that derives from IEnumerable
) are supported for serialization, as long as their element types are supported.
Custom collections with deserialization support
A custom collection is supported for deserialization if it:
- Isn't an interface or abstract.
- Has a parameterless constructor.
- Contains element types that are supported by JsonSerializer.
- Implements or inherits one or more of the following interfaces or classes:
- Isn't an interface or abstract.
- Has a parameterless constructor.
- Contains element types that are supported by JsonSerializer.
- Implements or inherits one or more of the following interfaces or classes:
* See Support round trip for Stack<T>.
** See Supported key types.
Custom collections with known issues
There are known issues with the following custom collections:
- ExpandoObject: See dotnet/runtime#29690.
- DynamicObject: See dotnet/runtime#1808.
- DataTable: See dotnet/docs#21366.
- Microsoft.AspNetCore.Http.FormFile: See dotnet/runtime#1559.
- Microsoft.AspNetCore.Http.IFormCollection: See dotnet/runtime#1559.
For more information about known issues, see the open issues in System.Text.Json.
Supported key types
Supported types for the keys of Dictionary
and SortedList
types include the following:
Boolean
Byte
DateTime
DateTimeOffset
Decimal
Double
Enum
Guid
Int16
Int32
Int64
Object
(Only on serialization and if the runtime type is one of the supported types in this list.)SByte
Single
String
UInt16
UInt32
UInt64
** Non-string
keys for Dictionary
and SortedList
types are not supported in .NET Core 3.1.
See also
- System.Text.Json overview
- Instantiate JsonSerializerOptions instances
- Enable case-insensitive matching
- Customize property names and values
- Ignore properties
- Allow invalid JSON
- Handle overflow JSON
- Preserve references
- Immutable types and non-public accessors
- Polymorphic serialization
- Migrate from Newtonsoft.Json to System.Text.Json
- Customize character encoding
- Write custom serializers and deserializers
- Write custom converters for JSON serialization
- DateTime and DateTimeOffset support
- System.Text.Json API reference
- System.Text.Json.Serialization API reference