diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 9977a1a4ccefa..3cfad10872eb9 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -1649,6 +1649,8 @@ items: href: ../standard/serialization/system-text-json-polymorphism.md - name: How to migrate from Newtonsoft.Json href: ../standard/serialization/system-text-json-migrate-from-newtonsoft-how-to.md + - name: Supported collection types + href: ../standard/serialization/system-text-json-supported-collection-types.md - name: Advanced items: - name: Customize character encoding diff --git a/docs/standard/serialization/system-text-json-how-to.md b/docs/standard/serialization/system-text-json-how-to.md index 6318fd884bd29..434ae995c58d7 100644 --- a/docs/standard/serialization/system-text-json-how-to.md +++ b/docs/standard/serialization/system-text-json-how-to.md @@ -304,5 +304,6 @@ Extension methods on `HttpClient` and `HttpContent` are not available in System. * [Write custom serializers and deserializers](write-custom-serializer-deserializer.md) * [Write custom converters for JSON serialization](system-text-json-converters-how-to.md) * [DateTime and DateTimeOffset support](../datetime/system-text-json-support.md) +* [Supported collection types in System.Text.Json](system-text-json-supported-collection-types.md) * [System.Text.Json API reference](xref:System.Text.Json) * [System.Text.Json.Serialization API reference](xref:System.Text.Json.Serialization) diff --git a/docs/standard/serialization/system-text-json-overview.md b/docs/standard/serialization/system-text-json-overview.md index 53f2cc7aab5e6..1980eeb4dc45b 100644 --- a/docs/standard/serialization/system-text-json-overview.md +++ b/docs/standard/serialization/system-text-json-overview.md @@ -44,5 +44,6 @@ The library also provides classes for working with an in-memory document object * [Write custom serializers and deserializers](write-custom-serializer-deserializer.md) * [Write custom converters for JSON serialization](system-text-json-converters-how-to.md) * [DateTime and DateTimeOffset support](../datetime/system-text-json-support.md) +* [Supported collection types in System.Text.Json](system-text-json-supported-collection-types.md) * [System.Text.Json API reference](xref:System.Text.Json) * [System.Text.Json.Serialization API reference](xref:System.Text.Json.Serialization) diff --git a/docs/standard/serialization/system-text-json-supported-collection-types.md b/docs/standard/serialization/system-text-json-supported-collection-types.md new file mode 100644 index 0000000000000..509a785716cb4 --- /dev/null +++ b/docs/standard/serialization/system-text-json-supported-collection-types.md @@ -0,0 +1,341 @@ +--- +title: "Supported collection types in System.Text.Json" +description: "Learn which collection types are supported for serialization by the APIs in the System.Text.Json namespace." +ms.date: 01/06/2021 +no-loc: [System.Text.Json] +ms.topic: reference +zone_pivot_groups: dotnet-version +helpviewer_keywords: + - "JSON serialization" + - "serializing objects" + - "serialization" + - "objects, serializing" +--- + +# Supported collection types in System.Text.Json + +This article gives an overview of which collections are supported for serialization and deserialization. supports a collection type for serialization if it: + +* Derives from . +* Contains elements that are serializable. + +The serializer calls the 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.Collections namespace + +| Type | Serialization | Deserialization | +|-------------------------------------------|---------------|-----------------| +| | ✔️ | ✔️ | +| | ✔️ | ❌ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | + +## System.Collections.Generic namespace + +::: zone pivot="dotnet-5-0" + +| Type | Serialization | Deserialization | +|-----------------------------------------------------------|---------------|-----------------| +| \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ❌ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ❌ | ❌ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | + +::: zone-end + +::: zone pivot="dotnet-core-3-1" + +| Type | Serialization | Deserialization | +|-------------------------------------------------------------------------------------------------|---------------|-----------------| +| [Dictionary\](xref:System.Collections.Generic.Dictionary%602) \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ❌ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| [SortedDictionary\](xref:System.Collections.Generic.SortedDictionary%602) \* | ✔️ | ✔️ | +| [SortedList\](xref:System.Collections.Generic.SortedList%602) \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ❌ | ❌ | +| | ✔️ | ✔️ | +| [IDictionary\](xref:System.Collections.Generic.IDictionary%602) \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| [IReadOnlyDictionary\](xref:System.Collections.Generic.IReadOnlyDictionary%602) \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | + +::: zone-end + +\* See [Supported key types](#supported-key-types). + +## System.Collections.Immutable namespace + +::: zone pivot="dotnet-5-0" + +| Type | Serialization | Deserialization | +|-------------------------------------------------------------------|---------------|-----------------| +| | ✔️ | ✔️ | +| \*\* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \*\* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| \*\* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | + +::: zone-end + +::: zone pivot="dotnet-core-3-1" + +| Type | Serialization | Deserialization | +|---------------------------------------------------------------------------------------------------------------|---------------|-----------------| +| | ✔️ | ✔️ | +| [ImmutableDictionary\](xref:System.Collections.Immutable.ImmutableDictionary%602) \*\* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| [ImmutableSortedDictionary\](xref:System.Collections.Immutable.ImmutableSortedDictionary%602) \*\*| ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| [IImmutableDictionary\](xref:System.Collections.Immutable.IImmutableDictionary%602) \*\* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | + +::: zone-end + +\* See [Support round trip for Stack\](system-text-json-converters-how-to.md#support-round-trip-for-stackt). + +\*\* See [Supported key types](#supported-key-types). + +## System.Collections.Specialized namespace + +| Type | Serialization | Deserialization | +|-----------------------------------------------------------|---------------|-----------------| +| | ✔️ | ❌\* | +| | ✔️ | ✔️ | +| | ✔️ | ❌ | +| | ✔️ | ✔️ | +| | ✔️ | ❌ | +| | ✔️ | ❌ | +| | ✔️ | ❌ | + +\* When is deserialized, the property is skipped because it doesn't have a public setter. No exception is thrown. + +## System.Collections.Concurrent namespace + +::: zone pivot="dotnet-5-0" + +| Type | Serialization | Deserialization | +|---------------------------------------------------------------|---------------|-----------------| +| | ✔️ | ❌ | +| | ✔️ | ❌ | +| \*\* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | + +::: zone-end + +::: zone pivot="dotnet-core-3-1" + +| Type | Serialization | Deserialization | +|-------------------------------------------------------------|---------------|-----------------| +| | ✔️ | ❌ | +| | ✔️ | ❌ | +| [ConcurrentDictionary\](xref:System.Collections.Concurrent.ConcurrentDictionary%602) \*\* |✔️|✔️| +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | + +::: zone-end + +\* See [Support round trip for Stack\](system-text-json-converters-how-to.md#support-round-trip-for-stackt). + +\*\* See [Supported key types](#supported-key-types). + +## System.Collections.ObjectModel namespace + +::: zone pivot="dotnet-5-0" + +| Type | Serialization | Deserialization | +|----------------------------------------------------------------|---------------|-----------------| +| | ✔️ | ✔️ | +| [KeyedCollection\](xref:System.Collections.ObjectModel.KeyedCollection%602) \* |✔️|❌| +| | ✔️ | ✔️ | +| | ✔️ | ❌ | +| | ✔️ | ❌ | +| | ✔️ | ❌ | + +\* Non-`string` keys are not supported. + +::: zone-end + +::: zone pivot="dotnet-core-3-1" + +| Type | Serialization | Deserialization | +|----------------------------------------------------------------|---------------|-----------------| +| | ✔️ | ✔️ | +| [KeyedCollection\](xref:System.Collections.ObjectModel.KeyedCollection%602) \* |✔️|❌| +| | ✔️ | ✔️ | +| | ✔️ | ❌ | +| [ReadOnlyDictionary\](xref:System.Collections.ObjectModel.ReadOnlyDictionary%602) \* |✔️|❌| +| | ✔️ | ❌ | + +\* See [Supported key types](#supported-key-types). + +::: zone-end + +## 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, 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: + +::: zone pivot="dotnet-5-0" + +* Isn't an interface or abstract. +* Has a parameterless constructor. +* Contains element types that are supported by . +* Implements or inherits one or more of the following interfaces or classes: + * + * \* + * + * + * \*\* + * + * + * + * + * \* + * \* + +::: zone-end + +::: zone pivot="dotnet-core-3-1" + +* Isn't an interface or abstract. +* Has a parameterless constructor. +* Contains element types that are supported by . +* Implements or inherits one or more of the following interfaces or classes: + * + * \* + * + * + * [IDictionary\](xref:System.Collections.Generic.IDictionary%602) \*\* + * + * + * + * + * \* + * \* + +::: zone-end + + \* See [Support round trip for Stack\](system-text-json-converters-how-to.md#support-round-trip-for-stackt). + + \*\* See [Supported key types](#supported-key-types). + +### Custom collections with known issues + +There are known issues with the following custom collections: + +- : See [dotnet/runtime#29690](https://github.com/dotnet/runtime/issues/29690). +- : See [dotnet/runtime#1808](https://github.com/dotnet/runtime/issues/1808). +- : See [dotnet/docs#21366](https://github.com/dotnet/docs/issues/21366). +- : See [dotnet/runtime#1559](https://github.com/dotnet/runtime/issues/1559). +- : See [dotnet/runtime#1559](https://github.com/dotnet/runtime/issues/1559). + +For more information about known issues, see the [open issues in System.Text.Json](https://github.com/dotnet/runtime/issues?q=is%3Aopen+is%3Aissue+label%3Aarea-System.Text.Json). + +## Supported key types + +::: zone pivot="dotnet-5-0" + +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` + +::: zone-end + +::: zone pivot="dotnet-core-3-1" + +\*\* Non-`string` keys for `Dictionary` and `SortedList` types are not supported in .NET Core 3.1. + +::: zone-end + +## See also + +* [System.Text.Json overview](system-text-json-overview.md) +* [Instantiate JsonSerializerOptions instances](system-text-json-configure-options.md) +* [Enable case-insensitive matching](system-text-json-character-casing.md) +* [Customize property names and values](system-text-json-customize-properties.md) +* [Ignore properties](system-text-json-ignore-properties.md) +* [Allow invalid JSON](system-text-json-invalid-json.md) +* [Handle overflow JSON](system-text-json-handle-overflow.md) +* [Preserve references](system-text-json-preserve-references.md) +* [Immutable types and non-public accessors](system-text-json-immutability.md) +* [Polymorphic serialization](system-text-json-polymorphism.md) +* [Migrate from Newtonsoft.Json to System.Text.Json](system-text-json-migrate-from-newtonsoft-how-to.md) +* [Customize character encoding](system-text-json-character-encoding.md) +* [Write custom serializers and deserializers](write-custom-serializer-deserializer.md) +* [Write custom converters for JSON serialization](system-text-json-converters-how-to.md) +* [DateTime and DateTimeOffset support](../datetime/system-text-json-support.md) +* [System.Text.Json API reference](xref:System.Text.Json) +* [System.Text.Json.Serialization API reference](xref:System.Text.Json.Serialization)