diff --git a/docs/core/compatibility/6.0.md b/docs/core/compatibility/6.0.md index 1fc65ecc5c091..2cea9d2590977 100644 --- a/docs/core/compatibility/6.0.md +++ b/docs/core/compatibility/6.0.md @@ -131,6 +131,7 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff | [IAsyncEnumerable serialization](serialization/6.0/iasyncenumerable-serialization.md) | ✔️ | ❌ | Preview 4 | | [JSON source-generation API refactoring](serialization/6.0/json-source-gen-api-refactor.md) | ❌ | ✔️ | RC 2 | | [JsonNode no longer supports C# `dynamic` type](serialization/6.0/jsonnode-dynamic-type.md) | ❌ | ✔️ | Preview 7 | +| [JsonNumberHandlingAttribute on collection properties](serialization/6.0/jsonnumberhandlingattribute-behavior.md) | ❌ | ✔️ | RC 1 | | [New JsonSerializer source generator overloads](serialization/6.0/jsonserializer-source-generator-overloads.md) | ❌ | ✔️ | Preview 6 | ## Windows Forms diff --git a/docs/core/compatibility/serialization/6.0/jsonnumberhandlingattribute-behavior.md b/docs/core/compatibility/serialization/6.0/jsonnumberhandlingattribute-behavior.md new file mode 100644 index 0000000000000..9b0fd23ebe25e --- /dev/null +++ b/docs/core/compatibility/serialization/6.0/jsonnumberhandlingattribute-behavior.md @@ -0,0 +1,46 @@ +--- +title: "Breaking change: JsonNumberHandlingAttribute on non-number collection properties" +description: Learn about the .NET 6 breaking change where JsonNumberHandlingAttribute can now only be applied to properties that are collections of numbers. +ms.date: 11/05/2021 +--- +# JsonNumberHandlingAttribute on collection properties + +A minor breaking change was introduced in .NET 6 with regard to the attribute. If you apply the attribute to a property that's a collection of non-number values and attempt to serialize or deserialize the property, an is thrown. The attribute is only valid for properties that are collections of number types, for example: + +```csharp +[JsonNumberHandling(JsonNumberHandling.AllowReadingFromString | JsonNumberHandling.WriteAsString)] +public List MyList { get; set; } +``` + +## Previous behavior + +Although it was ignored during serialization, could be applied to properties that were collections of non-number types. For example: + +```csharp +[JsonNumberHandling(JsonNumberHandling.AllowReadingFromString | JsonNumberHandling.WriteAsString)] +public List MyList { get; set; } +``` + +## New behavior + +Starting in .NET 6, if you apply to a property that's a collection of non-number values and attempt to serialize or deserialize the property, an is thrown. + +## Version introduced + +6.0 Preview 1 + +## Type of breaking change + +This change can affect [binary compatibility](../../categories.md#binary-compatibility). + +## Reason for change + +This change was a side effect of a performance optimization for the number handling feature. + +## Recommended action + +Remove the attribute from incompatible collection properties. + +## Affected APIs + +All of the serialization and deserialization methods. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 31473d2ee800a..6687cba3b3c6a 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -177,6 +177,8 @@ items: href: serialization/6.0/json-source-gen-api-refactor.md - name: JsonNode no longer supports C# `dynamic` href: serialization/6.0/jsonnode-dynamic-type.md + - name: JsonNumberHandlingAttribute on collection properties + href: serialization/6.0/jsonnumberhandlingattribute-behavior.md - name: New JsonSerializer source generator overloads href: serialization/6.0/jsonserializer-source-generator-overloads.md - name: Windows Forms @@ -883,6 +885,8 @@ items: href: serialization/6.0/json-source-gen-api-refactor.md - name: JsonNode no longer supports C# `dynamic` href: serialization/6.0/jsonnode-dynamic-type.md + - name: JsonNumberHandlingAttribute on collection properties + href: serialization/6.0/jsonnumberhandlingattribute-behavior.md - name: New JsonSerializer source generator overloads href: serialization/6.0/jsonserializer-source-generator-overloads.md - name: .NET 5