Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add supported types article to System.Text.Json documentation #15807

Closed
tdykstra opened this issue Nov 11, 2019 · 1 comment · Fixed by #22217
Closed

Add supported types article to System.Text.Json documentation #15807

tdykstra opened this issue Nov 11, 2019 · 1 comment · Fixed by #22217
Assignees
Labels
doc-idea Indicates issues that are suggestions for new topics [org][type][category] dotnet/svc Pri2

Comments

@tdykstra
Copy link
Contributor

tdykstra commented Nov 11, 2019

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.

@dotnet-bot dotnet-bot added the ⌚ Not Triaged Not triaged label Nov 11, 2019
@tdykstra tdykstra added 📚 Area - .NET Guide doc-idea Indicates issues that are suggestions for new topics [org][type][category] and removed ⌚ Not Triaged Not triaged labels Nov 11, 2019
@tdykstra tdykstra self-assigned this Nov 20, 2019
@tdykstra
Copy link
Contributor Author

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:

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc-idea Indicates issues that are suggestions for new topics [org][type][category] dotnet/svc Pri2
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants