diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md index 00f6eeb3848f3..f27c23d9b0df5 100644 --- a/docs/core/compatibility/9.0.md +++ b/docs/core/compatibility/9.0.md @@ -39,6 +39,7 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff | [BinaryReader.GetString() returns "\uFFFD" on malformed sequences](core-libraries/9.0/binaryreader.md) | Behavioral change | Preview 7 | | [Creating type of array of System.Void not allowed](core-libraries/9.0/type-instance.md) | Behavioral change | Preview 1 | | [Default `Equals()` and `GetHashCode()` throw for types marked with `InlineArrayAttribute`](core-libraries/9.0/inlinearrayattribute.md) | Behavioral change | Preview 6 | +| [EnumConverter validates registered types to be enum](core-libraries/9.0/enumconverter.md) | Behavioral change | Preview 7 | | [FromKeyedServicesAttribute no longer injects non-keyed parameter](core-libraries/9.0/non-keyed-params.md) | Behavioral change | RC 1 | | [IncrementingPollingCounter initial callback is asynchronous](core-libraries/9.0/async-callback.md) | Behavioral change | RC 1 | | [Inline array struct size limit is enforced](core-libraries/9.0/inlinearray-size.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/core-libraries/9.0/enumconverter.md b/docs/core/compatibility/core-libraries/9.0/enumconverter.md new file mode 100644 index 0000000000000..4cabe37af6c53 --- /dev/null +++ b/docs/core/compatibility/core-libraries/9.0/enumconverter.md @@ -0,0 +1,38 @@ +--- +title: "Breaking change: EnumConverter validates registered types to be enum" +description: Learn about the .NET 9 breaking change where EnumConverter now validates that the type to be registered is an enum type. +ms.date: 10/04/2024 +--- +# EnumConverter validates registered types to be enum + + is a type converter that converts to and from an `enum` type. EnumConverter now validates that the type to be registered is of an `enum` type. + +## Previous behavior + +Previously, the type to be registered was not validated to be an `enum` type. + +## New behavior + +Starting in .NET 9, throws an if the type to be converted is not an `enum` type. Any derived classes of should also respect this requirement. + +## Version introduced + +.NET 9 Preview 7 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +It is logical to enforce the requirement that be used to convert to and from `enum` types only. It was likely an oversight that this requirement wasn't added earlier. + +However, the primary driving factor for this change was for trimming purposes. [Trimming](../../../deploying/trimming/prepare-libraries-for-trimming.md) doesn't trim `enum` types, but using for `enum` types required annotation for an `enum` type. This means that using `EnumConverter` generates unnecessary trim warnings. A recent change removed the annotation requirement. Part of the reason for that change was to enforce that `EnumConverter` only be used with `enums`. + +## Recommended action + +There is no easy workaround if an is used to convert to and from a non-`enum` type. + +## Affected APIs + +- constructor diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 6fd30bbce9f7b..46ab742692d9b 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -30,6 +30,8 @@ items: href: core-libraries/9.0/biginteger-limit.md - name: Creating type of array of System.Void not allowed href: core-libraries/9.0/type-instance.md + - name: EnumConverter validates registered types to be enum + href: core-libraries/9.0/enumconverter.md - name: "`Equals`/`GetHashCode` throw for `InlineArrayAttribute` types" href: core-libraries/9.0/inlinearrayattribute.md - name: FromKeyedServicesAttribute no longer injects non-keyed parameter @@ -1260,6 +1262,8 @@ items: href: core-libraries/9.0/binaryreader.md - name: Creating type of array of System.Void not allowed href: core-libraries/9.0/type-instance.md + - name: EnumConverter validates registered types to be enum + href: core-libraries/9.0/enumconverter.md - name: "`Equals`/`GetHashCode` throw for `InlineArrayAttribute` types" href: core-libraries/9.0/inlinearrayattribute.md - name: FromKeyedServicesAttribute no longer injects non-keyed parameter