[All Hosts] (installation) Preview control of choice for COM or Office add-in

docs/develop/make-office-add-in-compatible-with-existing-com-add-in.md

@@ -1,7 +1,7 @@
 ---
-title: Make your Office Add-in compatible with an existing COM or VSTO add-in
-description: Enable compatibility between your Office Add-in and equivalent COM or VSTO add-in.
-ms.date: 07/12/2025
+title: Make your Office Add-in compatible with an existing COM add-in
+description: Enable compatibility between your Office Add-in and equivalent COM add-in.
+ms.date: 07/21/2025
 ms.localizationpriority: medium
 ---
 
@@ -14,10 +14,19 @@ If you have an existing COM add-in or VSTO add-in, you can build equivalent func
 
 [!INCLUDE [new-outlook-vsto-com-support](../includes/new-outlook-vsto-com-support.md)]
 
-You can configure your Office Add-in so that when the equivalent Windows-only add-in is already installed on a user's computer, Office on Windows runs the Windows-only add-in instead of the Office Add-in. The Windows-only add-in is called "equivalent" because Office will seamlessly transition between the Windows-only add-in and the Office Add-in according to which one is installed on a user's computer.
+You can configure your Office Add-in so that when the equivalent Windows-only add-in is already installed on a user's computer, Office on Windows runs the Windows-only add-in instead of the Office Add-in. The Windows-only add-in is called "equivalent" because Office will seamlessly transition between the Windows-only add-in and the Office Add-in according to which one is installed on a user's computer. For more information, see [Equivalent behavior for users](#equivalent-behavior-for-users). As a general rule, add-ins should be treated as equivalent only when the following conditions are met, but there may be exceptional scenarios where add-ins are that don't meet these conditions can be treated as equivalent.
+
+- They're both created by the same developer, typically the entity specified in the [`"developer"`](/microsoft-365/extensibility/schema/root-developer) property of the unified manifest or the [ProviderName](/javascript/api/manifest/providername) element in the add-in only manifest.
+- They both are designed to be installed on the same Office application or applications, and they address the same workload with mainly overlapping functionality.
+- They have identical, or highly similar, public names, and user interfaces including control names and icons.
+
+If the Windows-only add-in is ever uninstalled, Office will automatically activate the Office Add-in the next time the host Office application is started.
 
 [!INCLUDE [Support note for equivalent add-ins feature](../includes/equivalent-add-in-support-note.md)]
 
+> [!TIP]
+> Currently, the Windows-only add-in is always given preference to the Office Add-in. But there's an enhancement to this feature in preview that provides you with a way to reverse this preference or to give the user a choice between the Windows-only add-in and Office Add-in. For more information, see [Option to disable the Windows-only add-in instead (preview)](#option-to-disable-the-windows-only-add-in-instead-preview).
+
 ## Specify an equivalent Windows-only add-in
 
 ### Obtain the ID of the Windows-only add-in
@@ -57,6 +66,11 @@ The following example shows the portion of the manifest that specifies a Windows
 ]
 ```
 
+> [!TIP]
+>
+> - For information about COM add-in and XLL UDF compatibility, see [Make your custom functions compatible with XLL user-defined functions](../excel/make-custom-functions-compatible-with-xll-udf.md). Not applicable for Outlook.
+> - If you're unable to specify the `alternates.prefer` property in the manifest of your Outlook web add-in, you must configure Group Policy instead. This only applies to Outlook. For guidance, see [Configure the Group Policy setting for Outlook add-ins](#configure-the-group-policy-setting-for-outlook-add-ins).
+
 # [Add-in only manifest](#tab/xmlmanifest)
 
 The following example shows the portion of the manifest that specifies a Windows-only add-in as an equivalent add-in. The value of the `ProgId` element identifies the Windows-only add-in and the [EquivalentAddins](/javascript/api/manifest/equivalentaddins) element must be positioned immediately before the closing `VersionOverrides` tag.
@@ -152,6 +166,94 @@ The Windows-only add-in must be connected when Outlook is started in order for t
 
 If the Windows-only add-in is then disconnected during a subsequent Outlook session, the Outlook add-in will likely remain disabled until Outlook is restarted.
 
+## Option to disable the Windows-only add-in instead (preview)
+
+> [!NOTE]
+> The feature described in this section is in preview and shouldn't be used in a production add-in. It has the following limitations.
+>
+> - It's supported only for Excel, PowerPoint, and Word.
+> - The minimum Office version that supports the feature is ubscription Office on Windows Version 2506 (Build 19029.20004)
+
+Use manifest markup to specify whether the Windows-only add-in or the Office Add-in should be disabled and hidden on a Windows computer when they conflict, or give the user that is installing the Office Add-in the choice of which to use.
+
+If you configure the manifest to give the user the choice, then the user sees a dialog similar to the following when they install the Office Add-in. The **Learn more** link in the dialog points to the following help page that provides information to help the user make the decision: [Resolve version conflicts for Office Add-ins](https://support.microsoft.com/office/1632ec51-82ed-4f8e-90b4-a246cbccccde).
+
+:::image type="content" source="../images/com-preference-prompt.png" alt-text="A dialog titled 'Contoso JS Add-in Installer'. The first paragraph says 'Contoso JS Add-in has identified the following older versions of the add-in that may cause conflicts:'. Below this paragraph is a single bulleted paragraph that says 'COM Add-in name: Contoso'. Below this is a paragraph that says 'Do you want to disable the older add-in versions? (If you choose No, you will still get the new version if you open Office on Mac or Office on the web.)'. Below this is a link labelled 'Learn more'. Below this are two buttons labelled Yes and No.":::
+
+If the user chooses **Yes** and Office successfully disables and hides the Windows-only add-in, then a dialog similar to the following opens that advises the user to restart the Office application.
+
+:::image type="content" source="../images/com-preference-disable-success.png" alt-text="A dialog titled 'The Older Version Add-in Disabled'. The first paragraph says 'The older version of the add-in has been successfully disabled.' Below this a paragraph says 'To ensure the changes take effect, we recommend restarting this Office application. You can continue without restarting, but some updates may not be applied until the next launch.' Below this is an OK button.":::
+
+If the user chooses **Yes** but Office can't disable the Windows-only add-in for any reason, then a dialog similar to the following opens that advises the user to manually disable the Windows-only add-in.
+
+:::image type="content" source="../images/com-preference-disable-failure.png" alt-text="A dialog titled 'Please Disable Add-in Manually'. The first paragraph says 'The older version of the add-in could not be fully disabled. To complete the process, please manually disable the COM add-in in the Office application where it was installed.' Below this are instructions labelled 'Here's how'. The instructions read as follows '1. Go to File, Options, Add-ins. 2. In the Manage dropdown at the bottom, choose the add-in type and click Go. 3. In the dialog, uncheck the add-in to disable it. 4. Restart the app to apply changes (optional but recommended). Below this is an OK button.":::
+
+The details to configure this feature depend on which type of manifest is being used by the Office Add-in.
+
+# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
+
+To disable the Windows-only add-in instead of the Office Add-in (or to give the user the choice), use the `alternates.hide.windowsExtensions` and `alternates.hide.windowsExtensions.effect` properties. The two possible values of the `effect` property and their effects are as follows:
+
+- **disableWithNotification**: All of the Windows-only add-ins specified in the child `comAddin.progIds` array of the `windowsExtensions` property are disabled and hidden. A popup dialog notifies the user that this is happening.
+- **userOptionToDisable**: The user is prompted to choose whether to disable and hide the Windows-only add-ins specified in the child `comAddin.progIds` array of the `windowsExtensions` property or to disable and hide the Office Add-in.
+
+> [!NOTE]
+> The string "com" is in the name `comAddin` for historical reasons. In the manifest, the property refers to either COM or VSTO add-ins. Similarly, the term "progIds" is usually associated with only COM add-ins, but names of VSTO add-ins can also be included in the `progIds` array.
+
+> [!TIP]
+> To force the Windows-only add-in to be enabled and the Office Add-in to be disabled and hidden on the Windows computer, use the `alternates.prefer` property as described in [Configure the manifest](?tabs=jsonmanifest#configure-the-manifest).
+
+In the following example, the user will be prompted whether to disable the Windows-only add-in "ContosoAddin" or to disable the Office Add-in.
+
+```json
+"extensions" [
+  {   
+    ...
+    "alternates": [
+      {
+        "hide": {
+          "windowsExtensions": {
+            "effect": "userOptionToDisable",
+            "comAddin": {
+              "progIds": [
+                "ContosoAddin"
+              ]
+            }
+          }
+        }
+      }
+    ]
+  }
+]
+```
+
+# [Add-in only manifest](#tab/xmlmanifest)
+
+To configure which add-in is used (or give the user the choice), there is an optional **\<Effect\>** child of the **\<EquivalentAddins\>** element that has one of the following effects when the Office Add-in is installed, depending on which of two possible values it's set to.
+
+- **DisableWithNotification**: All of the Windows-only add-ins specified in the child **\<EquivalentAddin\>** elements will be disabled and hidden. A popup dialog notifies the user that this happening.
+- **UserOptionToDisable**: The user is prompted to choose whether to disable and hide the Windows-only add-ins specified in the child **\<EquivalentAddin\>** elements or to disable and hide the Office Add-in.
+
+> [!NOTE]
+> If the **\<Effect\>** element isn't present, the Windows-only add-in is enabled and the Office Add-in is disabled and hidden on the Windows computer.
+
+The following is an example. The **\<Effect\>** element must be after all the **\<EquivalentAddin\>** elements.
+
+```xml
+<VersionOverrides>
+  ...
+  <EquivalentAddins>
+    <EquivalentAddin>
+      <ProgId>ContosoAddin</ProgId>
+      <Type>COM</Type>
+    </EquivalentAddin>
+    <Effect>UserOptionToDisable</Effect>
+  </EquivalentAddins>
+</VersionOverrides>
+```
+
+---
+
 ## See also
 
 - [Make your Custom Functions compatible with XLL User Defined Functions](../excel/make-custom-functions-compatible-with-xll-udf.md)

docs/develop/manifest-element-ordering.md

@@ -1,7 +1,7 @@
 ---
 title: How to find the proper order of manifest elements
 description: Learn how to find the correct order in which to place child elements in a parent element.
-ms.date: 06/02/2025
+ms.date: 06/13/2025
 ms.localizationpriority: medium
 ---
 
@@ -287,6 +287,7 @@ The following sections show the manifest elements in the order in which they mus
                 <DisplayName>
                 <FileName>
                 <Type>
+            <Effect>
 ```
 
 ## Mail add-in element ordering within VersionOverrides Ver. 1.0