Add supported types article to System.Text.Json documentation

[tdykstra]

Create supported types doc similar to what we have here per suggestion from @ahsonkhan:

I saw there was a somewhat exhaustive list for the other serializer (https://docs.microsoft.com/en-us/dotnet/standard/serialization/binary-serialization#serializable-types), but that isn't necessary here. At least not atm. Maybe in the future, we do this in a separate, linked page when the types supported grows.

Related to #12207

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 6b74d77c-33e1-d44c-18c6-bd0b612f74de
• Version Independent ID: 9c6a7135-eb75-21a9-1d27-0880459523ca
• Content: Migrate from Newtonsoft.Json to System.Text.Json - .NET
• Content Source: docs/standard/serialization/system-text-json-migrate-from-newtonsoft-how-to.md
• Product: dotnet
• GitHub Login: @tdykstra
• Microsoft Alias: tdykstra

[tdykstra]

JsonSerializer collection support in 3.1.x

All collections (any type that derives from IEnumerable)
are supported for serialization with JsonSerializer;
we simply call the .GetEnumerator()
method of the collection, and write the elements if they are supported. Deserialization is more complicated and is not supported for all collections.

This document gives a quick overview of which collections are supported.

Built-in types

System.Collections

Type	Serialization	Deserialization
ArrayList	Supported	Supported
BitArray	Supported	Not supported
Hashtable	Supported	Supported
Queue	Supported	Supported
SortedList	Supported	Supported
Stack*	Supported	Supported
DictionaryEntry	Supported	Supported
ICollection	Supported	Supported
IDictionary	Supported	Supported
IEnumerable	Supported	Supported
IList	Supported	Supported

System.Collections.Generic

Type	Serialization	Deserialization
Dictionary<string, TValue>	Supported	Supported
HashSet<T>	Supported	Supported
LinkedList<T>	Supported	Supported
LinkedListNode<T>	Supported	Not supported
List<T>	Supported	Supported
Queue<T>	Supported	Supported
SortedDictionary<string, TValue>	Supported	Supported
SortedList<string, TValue>	Supported	Supported
SortedSet<T>	Supported	Supported
Stack<T>*	Supported	Supported
KeyValuePair<TKey, TValue>	Supported	Supported
IAsyncEnumerable<T>	Not supported	Not supported
ICollection<T>	Supported	Supported
IDictionary<string, TValue>	Supported	Supported
IEnumerable<T>	Supported	Supported
IList<T>	Supported	Supported
IReadOnlyCollection<T>	Supported	Supported
IReadOnlyDictionary<string, TValue>	Supported	Supported
IReadOnlyList<T>	Supported	Supported
ISet<T>	Supported	Supported

System.Collections.Immutable

Type	Serialization	Deserialization
ImmutableArray<T>	Supported	Supported
ImmutableDictionary<string, TValue>	Supported	Supported
ImmutableHashSet<T>	Supported	Supported
IImmutableList<T>	Supported	Supported
ImmutableQueue<T>	Supported	Supported
ImmutableSortedDictionary<string, TValue>	Supported	Supported
ImmutableSortedSet<T>	Supported	Supported
ImmutableStack<T>*	Supported	Supported
IImmutableDictionary<string, TValue>	Supported	Supported
IImmutableList<T>	Supported	Supported
IImmutableQueue<T>	Supported	Supported
IImmutableSet<T>	Supported	Supported
IImmutableStack<T>*	Supported	Supported

System.Collections.Specialized

Type	Serialization	Deserialization
BitVector32**	Supported	Not supported
HybridDictionary	Supported	Supported
IOrderedDictionary	Supported	Not supported
ListDictionary	Supported	Supported
StringCollection	Supported	Not supported
StringDictionary	Supported	Not supported
NameValueCollection	Supported	Not supported

System.Collections.Concurrent

Type	Serialization	Deserialization
BlockingCollection<T>	Supported	Not supported
ConcurrentBag<T>	Supported	NotSupported
ConcurrentDictionary<string, TValue>	Supported	Supported
ConcurrentQueue<T>	Supported	Supported
ConcurrentStack<T>*	Supported	Supported

System.Collections.ObjectModel

Type	Serialization	Deserialization
Collection<T>	Supported	Supported
ObservableCollection<T>	Supported	Supported
KeyedCollection<string, TValue>	Supported	Not supported
ReadOnlyCollection<T>	Supported	Not supported
ReadOnlyObservableCollection<T>	Supported	Not supported
ReadOnlyDictionary<string, TValue>	Supported	Not supported

Custom collections

For the purpose of serialization and deserialization in System.Text.Json, any
collection not in the BCL, (i.e. outside System.Collections[.[.\*]]), is considered
a custom collection. This includes user-defined types and ASP.NET defined types,
e.g. those in
Microsoft.Extensions.Primitives.

A custom collection is supported for deserialization if it fulfils the following:

1. Is not an interface or abstract
2. Has a parameter-less constructor
3. Implements one or more of
   IList,
   IList<T>,
   ICollection<T>,
   IDictionary,
   IDictionary<string, TValue>,
   Stack<T>*,
   Queue<T>,
   ConcurrentStack<T>*,
   ConcurrentQueue<T>,
   Stack*,
   and Queue
4. The element type is supported by JsonSerializer

All custom collections (everything that derives from IEnumerable)
are supported for serialization, as long as their element types are supported.

There are known issues with some custom collections where we don't offer round-trippable support.
These include:

• Support for ExpandoObject: https://github.com/dotnet/corefx/issues/38007
• Support for DynamicObject: https://github.com/dotnet/corefx/issues/41105
• Support for DataTable: https://github.com/dotnet/corefx/issues/38712
• Support for FormFile: https://github.com/dotnet/corefx/issues/41401
• Support for IFormCollection
• Assigning null to value-type collections like ImmutableArray<T>: https://github.com/dotnet/corefx/issues/42399

For more information, see the open issues in System.Text.Json.

---

* Stack,
Stack<T>,
ImmutableStack<T>,
IImmutableStack<T>,
and ConcurrentStack<T>
instances; and instances of types that derive from them; are reversed on serialization. Thus, the serializer does not have round-trippable support
for these types. See https://github.com/dotnet/corefx/issues/41887.

** No exception is thrown when deserializing BitVector32,
but the Data
property skipped because it is read-only (doesn't have a public setter).