From 3b4ccd883cd01cca2930705d487cb4758df6ac51 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Fri, 4 Oct 2024 14:12:33 -0700
Subject: [PATCH] enumconverter breaking change

---
 docs/core/compatibility/9.0.md                |  6 +++
 .../networking/9.0/enumconverter.md           | 38 +++++++++++++++++++
 docs/core/compatibility/toc.yml               |  8 ++++
 3 files changed, 52 insertions(+)
 create mode 100644 docs/core/compatibility/networking/9.0/enumconverter.md

diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md
index 0fc07844d35df..97a1bce1234c8 100644
--- 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
new file mode 100644
index 0000000000000..b47b1503e5357
--- /dev/null
+++ 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
index 35162f3203b32..1ad6502bbdcf3 100644
--- 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