enumconverter breaking change

dotnet · Oct 4, 2024 · 3b4ccd8 · 3b4ccd8
1 parent a512438
commit 3b4ccd8
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 0 deletions.
diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md
@@ -61,6 +61,12 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 |-----------------------------------------------------------------------------------|---------------------|--------------------|
 | [Deprecated desktop Windows/macOS/Linux MonoVM runtime packages](deployment/9.0/monovm-packages.md) | Source incompatible | Preview 7          |
 
+## Extensions
+
+| Title                                                                                  | Type of change      | Introduced version |
+|----------------------------------------------------------------------------------------|---------------------|--------------------|
+| [EnumConverter validates registered types to be enum](networking/9.0/enumconverter.md) | Binary incompatible | Preview 7          |
+
 ## JIT compiler
 
 | Title                                                                            | Type of change      | Introduced version |

diff --git a/docs/core/compatibility/networking/9.0/enumconverter.md b/docs/core/compatibility/networking/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 in networking 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
+
+<xref:System.ComponentModel.EnumConverter> 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, <xref:System.ComponentModel.EnumConverter> throws an <xref:System.ArgumentException> if the type to be converted is not an `enum` type. Any derived classes of <xref:System.ComponentModel.EnumConverter> should also respect this requirement.
+
+## Version introduced
+
+.NET 9 Preview 7
+
+## Type of breaking change
+
+This change can affect [binary compatibility](../../categories.md#binary-compatibility) and is also a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+It is logical to enforce the requirement that <xref:System.ComponentModel.EnumConverter> 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 <xref:System.ComponentModel.EnumConverter> for `enum` types required <xref:System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembersAttribute> 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 <xref:System.ComponentModel.EnumConverter> is used to convert to and from a non-`enum` type.
+
+## Affected APIs
+
+- <xref:System.ComponentModel.EnumConverter.%23ctor(System.Type)> constructor
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -58,6 +58,10 @@ items:
             items:
               - name: Deprecated desktop Windows/macOS/Linux MonoVM runtime packages
                 href: deployment/9.0/monovm-packages.md
+          - name: Extensions
+            items:
+              - name: EnumConverter validates registered types to be enum
+                href: networking/9.0/enumconverter.md
           - name: JIT compiler
             items:
               - name: Floating point to integer conversions are saturating
@@ -1546,6 +1550,10 @@ items:
             href: /ef/core/what-is-new/ef-core-3.x/breaking-changes?toc=/dotnet/core/compatibility/toc.json&bc=/dotnet/breadcrumb/toc.json
       - name: Extensions
         items:
+          - name: .NET 9
+            items:
+              - name: EnumConverter validates registered types to be enum
+                href: networking/9.0/enumconverter.md
           - name: .NET 8
             items:
               - name: ActivatorUtilities.CreateInstance behaves consistently