imsocomponent integration (#42484)

dotnet · Sep 5, 2024 · 6480b14 · 6480b14
1 parent df5c5c8
commit 6480b14
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 0 deletions.
diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md
@@ -91,6 +91,7 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 | [Changes to nullability annotations](windows-forms/9.0/nullability-changes.md)          | Source incompatible | Preview 1          |
 | [ComponentDesigner.Initialize throws ArgumentNullException](windows-forms/9.0/componentdesigner-initialize.md) | Behavioral change | Preview 1          |
 | [DataGridViewRowAccessibleObject.Name starting row index](windows-forms/9.0/datagridviewrowaccessibleobject-name-row.md) | Behavioral change | Preview 1 |
+| [IMsoComponent support is opt-in](windows-forms/9.0/imsocomponent-support.md)           | Behavioral change   | Preview 2          |
 | [No exception if DataGridView is null](windows-forms/9.0/datagridviewheadercell-nre.md) | Behavioral change   | Preview 1          |
 | [PictureBox raises HttpClient exceptions](windows-forms/9.0/httpclient-exceptions.md)   | Behavioral change   | Preview 6          |
 

diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -82,6 +82,8 @@ items:
         href: windows-forms/9.0/componentdesigner-initialize.md
       - name: DataGridViewRowAccessibleObject.Name starting row index
         href: windows-forms/9.0/datagridviewrowaccessibleobject-name-row.md
+      - name: IMsoComponent support is opt-in
+        href: windows-forms/9.0/imsocomponent-support.md
       - name: No exception if DataGridView is null
         href: windows-forms/9.0/datagridviewheadercell-nre.md
       - name: PictureBox raises HttpClient exceptions
@@ -1904,6 +1906,8 @@ items:
         href: windows-forms/9.0/componentdesigner-initialize.md
       - name: DataGridViewRowAccessibleObject.Name starting row index
         href: windows-forms/9.0/datagridviewrowaccessibleobject-name-row.md
+      - name: IMsoComponent support is opt-in
+        href: windows-forms/9.0/imsocomponent-support.md
       - name: No exception if DataGridView is null
         href: windows-forms/9.0/datagridviewheadercell-nre.md
       - name: PictureBox raises HttpClient exceptions

diff --git a/docs/core/compatibility/windows-forms/9.0/imsocomponent-support.md b/docs/core/compatibility/windows-forms/9.0/imsocomponent-support.md
@@ -0,0 +1,55 @@
+---
+title: "Breaking change: IMsoComponent support is opt-in"
+description: Learn about the breaking change in .NET 9 for Windows Forms where IMsoComponent support is now opt-in.
+ms.date: 09/05/2024
+---
+# IMsoComponent support is opt-in
+
+A change was made to avoid Windows Forms threads always registering with existing [IMsoComponentManager](/previous-versions/office/developer/office-2007/ff518963(v=office.12)) instances. However, you can opt in to register existing `IMsoComponentManager` instances to your Windows Forms threads.
+
+## Version introduced
+
+.NET 9 Preview 2
+
+## Previous behavior
+
+Previously, Windows Forms threads always registered with existing `IMsoComponentManager` instances.
+
+## New behavior
+
+Starting in .NET 9, Windows Forms threads don't automatically integrate with process-registered `IMsoComponentManagers`. To get the previous behavior back, set the switch `Switch.System.Windows.Forms.EnableMsoComponentManager`.
+
+## Change category
+
+This change is a [*behavioral change*](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change was made for performance and efficiency. The previous behavior presented a lot of overhead as it used COM, and not all developers need this behavior.
+
+## Recommended action
+
+If you wish to revert to the previous behavior, you can opt in to `IMsoComponent` support using a switch in the *runtimeconfig.json* file or as a `RuntimeHostConfigurationOption` item in the project file.
+
+*runtimeconfig.json* file:
+
+```json
+{
+  "configProperties": {
+    "Switch.System.Windows.Forms.EnableMsoComponentManager": true
+ }
+}
+```
+
+Project file:
+
+```xml
+<ItemGroup>
+  <RuntimeHostConfigurationOption Include="Switch.System.Windows.Forms.EnableMsoComponentManager" Value="true" />
+</ItemGroup>
+```
+
+## Affected APIs
+
+- [IMsoComponent interface](/previous-versions/office/developer/office-2007/ff518955(v=office.12))
+- [IMsoComponentManager interface](/previous-versions/office/developer/office-2007/ff518963(v=office.12))