You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[All Hosts] (publish) Clarify VSTO COM equivalents feature (#5271)
* [All Hosts] (publish) Clarify VSTO COM equivalents feature
* add include and other fixes
* correction
* Apply suggestions from code review
Co-authored-by: Sam Ramon <[email protected]>
---------
Co-authored-by: Sam Ramon <[email protected]>
Copy file name to clipboardExpand all lines: docs/develop/make-office-add-in-compatible-with-existing-com-add-in.md
+46-37Lines changed: 46 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,40 +1,46 @@
1
1
---
2
-
title: Make your Office Add-in compatible with an existing COM add-in
3
-
description: Enable compatibility between your Office Add-in and equivalent COM add-in.
4
-
ms.date: 02/12/2025
2
+
title: Make your Office Add-in compatible with an existing COM or VSTO add-in
3
+
description: Enable compatibility between your Office Add-in and equivalent COM or VSTO add-in.
4
+
ms.date: 07/12/2025
5
5
ms.localizationpriority: medium
6
6
---
7
7
8
-
# Make your Office Add-in compatible with an existing COM add-in
8
+
# Make your Office Add-in compatible with an existing COM or VSTO add-in
9
9
10
-
If you have an existing COM add-in, you can build equivalent functionality in your Office Add-in, thereby enabling your solution to run on other platforms such as Office on the web or Mac. In some cases, your Office Add-in may not be able to provide all of the functionality that's available in the corresponding COM add-in. In these situations, your COM add-in may provide a better user experience on Windows than the corresponding Office Add-in can provide.
10
+
If you have an existing COM add-in or VSTO add-in, you can build equivalent functionality in your Office Add-in, thereby enabling your solution to run on other platforms such as Office on the web or Mac. In some cases, your Office Add-in may not be able to provide all of the functionality that's available in the corresponding COM or VSTO add-in. In these situations, your COM or VSTO add-in may provide a better user experience on Windows than the corresponding Office Add-in can provide.
11
+
12
+
> [!NOTE]
13
+
> Because COM and VSTO add-ins can only be installed on Windows, this article refers to COM and VSTO add-ins collectively as "Windows-only" add-ins.
You can configure your Office Add-in so that when the equivalent COM add-in is already installed on a user's computer, Office on Windows runs the COM add-in instead of the Office Add-in. The COM add-in is called "equivalent" because Office will seamlessly transition between the COM add-in and the Office Add-in according to which one is installed on a user's computer.
17
+
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.
15
18
16
19
[!INCLUDE [Support note for equivalent add-ins feature](../includes/equivalent-add-in-support-note.md)]
17
20
18
-
## Specify an equivalent COM add-in
21
+
## Specify an equivalent Windows-only add-in
19
22
20
-
### Obtain the ProgId of a COM add-in
23
+
### Obtain the ID of the Windows-only add-in
21
24
22
-
Before you can specify an equivalent COM add-in, you must first identify its `ProgId`. To obtain the `ProgId` of a COM add-in:
25
+
Before you can specify an equivalent Windows-only add-in, you must first identify its name with these steps:
23
26
24
-
1. Open Windows Registry Editor on the computer where the COM add-in is installed.
27
+
1. Open Windows Registry Editor on any computer where the Windows-only add-in is installed.
25
28
1. Go to **HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\\*<Office application\>*\Addins** or **HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\\*<Office application\>*\Addins**, where *\<Office application\>* is Excel, Outlook, PowerPoint, or Word. For example, **HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\Excel\Addins**.
26
-
1. Copy the name of the registry key associated with the COM add-in you need. Note that the names are case-sensitive.
29
+
1. Copy the name of the registry key associated with the Windows-only add-in you need. Note that the names are case-sensitive.
27
30
28
31
### Configure the manifest
29
32
30
33
> [!IMPORTANT]
31
34
> Applies to Excel, Outlook, PowerPoint, and Word.
32
35
33
-
To enable compatibility between your Office Add-in and COM add-in, identify the equivalent COM add-in in the [manifest](add-in-manifests.md) of your Office Add-in. Then, Office on Windows will use the COM add-in instead of the Office Add-in, if they're both installed. The configuration depends on the type of manifest that is being used.
36
+
To enable compatibility between your Office Add-in and the Windows-only add-in, identify the equivalent Windows-only add-in in the [manifest](add-in-manifests.md) of your Office Add-in using the name that you obtained in the section [Obtain the ID of the Windows-only add-in](#obtain-the-id-of-the-windows-only-add-in). Then, Office on Windows will use the Windows-only add-in instead of the Office Add-in, if they're both installed. The configuration depends on the type of manifest that is being used.
34
37
35
38
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
36
39
37
-
The following example shows the portion of the manifest that specifies a COM add-in as an equivalent add-in. The value of the [`"alternates.prefer.comAddin.progId"`](/microsoft-365/extensibility/schema/extension-alternate-versions-array-prefer-com-addin#progid) property identifies the COM add-in.
40
+
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 [`"alternates.prefer.comAddin.progId"`](/microsoft-365/extensibility/schema/extension-alternate-versions-array-prefer-com-addin#progid) property identifies the Windows-only add-in.
41
+
42
+
> [!NOTE]
43
+
> Although the property is called "comAddin", it actually refers to any Windows-only add-in, regardless of whether the add-in is COM or VSTO. Similarly, the term "progId" is usually associated with only COM add-ins, but in the manifest it refers to the name of the Windows-only add-in.
38
44
39
45
```json
40
46
"extensions" [
@@ -43,7 +49,7 @@ The following example shows the portion of the manifest that specifies a COM add
43
49
{
44
50
"prefer": {
45
51
"comAddin": {
46
-
"progId": "ContosoCOMAddin"
52
+
"progId": "ContosoAddin"
47
53
}
48
54
}
49
55
}
@@ -53,14 +59,20 @@ The following example shows the portion of the manifest that specifies a COM add
53
59
54
60
# [Add-in only manifest](#tab/xmlmanifest)
55
61
56
-
The following example shows the portion of the manifest that specifies a COM add-in as an equivalent add-in. The value of the `ProgId` element identifies the COM add-in and the [EquivalentAddins](/javascript/api/manifest/equivalentaddins) element must be positioned immediately before the closing `VersionOverrides` tag.
62
+
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.
63
+
64
+
> [!NOTE]
65
+
> Although the term "ProgId" is usually associated with only COM add-ins, in the manifest it refers to the name of the Windows-only add-in, regardless of whether the add-in is COM or VSTO.
66
+
67
+
> [!IMPORTANT]
68
+
> Use "COM" as the value of the `<Type>` element for both COM and VSTO add-ins.
57
69
58
70
```xml
59
71
<VersionOverrides>
60
72
...
61
73
<EquivalentAddins>
62
74
<EquivalentAddin>
63
-
<ProgId>ContosoCOMAddin</ProgId>
75
+
<ProgId>ContosoAddin</ProgId>
64
76
<Type>COM</Type>
65
77
</EquivalentAddin>
66
78
</EquivalentAddins>
@@ -71,77 +83,74 @@ The following example shows the portion of the manifest that specifies a COM add
71
83
72
84
> [!TIP]
73
85
>
74
-
> - 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.
75
-
> -If you're unable to specify the **\<EquivalentAddins\>** element 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).
86
+
> - For information about XLL UDF compatibility with an Excel add-in that contains custom functions, see [Make your custom functions compatible with XLL user-defined functions](../excel/make-custom-functions-compatible-with-xll-udf.md).
87
+
> -For Outlook only, an admin of a computer can specify an equivalent Windows-only add-in by using a Group Policy. For guidance, see [Configure the Group Policy setting for Outlook add-ins](#configure-the-group-policy-setting-for-outlook-add-ins).
76
88
77
-
###Configure the Group Policy setting for Outlook add-ins
89
+
## Configure the Group Policy setting for Outlook add-ins
78
90
79
-
For Outlook web add-ins, if you're unable to update the add-in's manifest to specify the **\<EquivalentAddins\>** element, you must identify the equivalent COM add-in in the **Deactivate Outlook web add-ins whose equivalent COM or VSTO add-in is installed** Group Policy setting instead. This setting must be configured on the user's machine. Then, classic Outlook on Windows will use the COM add-in instead of the web add-in if they're both installed.
80
-
81
-
> [!NOTE]
82
-
> Configuring the Group Policy setting isn't necessary if the add-in's manifest already contains an **\<EquivalentAddins\>** section.
91
+
A user with administrator powers on their computer can configure a Windows-only add-in to be the equivalent of an *Outlook* add-in by using the **Deactivate Outlook web add-ins whose equivalent COM or VSTO add-in is installed** Group Policy setting on the computer. This can be achieved even when the manifest of the Outlook add-in doesn't have the equivalent add-in markup. Then, classic Outlook on Windows uses the Windows-only add-in instead of the Outlook add-in if they're both installed. The following are the steps to configure the policy.
83
92
84
93
1. Download the latest [Administrative Templates tool](https://www.microsoft.com/download/details.aspx?id=49030), paying attention to the tool's **Install Instructions**.
85
94
1. Open the Local Group Policy Editor (**gpedit.msc**).
86
95
1. Navigate to **User Configuration** > **Administrative Templates** > **Microsoft Outlook 2016** > **Miscellaneous**.
87
96
1. Select the setting **Deactivate Outlook web add-ins whose equivalent COM or VSTO add-in is installed**.
88
97
1. Open the link to edit the policy setting.
89
98
1. In the dialog **Outlook web add-ins to deactivate**:
90
-
1. Set **Value name** to the `Id` found in the web add-in's manifest. **Important**: Do *not* add curly braces `{}` around the entry.
91
-
1. Set **Value** to the `ProgId` of the equivalent COM add-in.
99
+
1. Set **Value name** to the ID of the Outlook add-in's manifest. In the add-in only manifest, use the value of the `<ID>` element. In the unified manifest, use the value of the `id` property in the root of the manifest. Do *not* add curly braces `{}` around the entry.
100
+
1. Set **Value** to the name of the equivalent Windows-only add-in. See the section [Obtain the ID of the Windows-only add-in](#obtain-the-id-of-the-windows-only-add-in).
92
101
1. Select **OK** to put the update into effect.
93
102
94
103
95
104
96
105
## Equivalent behavior for users
97
106
98
-
When an [equivalent COM add-in is specified](#specify-an-equivalent-com-add-in), Office on Windows will not display your Office Add-in's user interface (UI) if the equivalent COM add-in is installed. Office only hides the ribbon buttons of the Office Add-in and doesn't prevent installation. Therefore, your Office Add-in will still appear in the following locations within the UI.
107
+
When an equivalent Windows-only add-in is specified, Office on Windows won't display your Office Add-in's user interface (UI) if the equivalent Windows-only add-in is installed. But Office only hides the ribbon buttons of the Office Add-in and doesn't prevent installation. Therefore, your Office Add-in will still appear in the following locations within the UI.
99
108
100
109
- Under **My add-ins**.
101
110
- As an entry on the ribbon manager (Excel, Word, and PowerPoint only).
102
111
103
112
> [!NOTE]
104
-
> Specifying an equivalent COM add-in in the manifest has no effect on other platforms, like Office on the web or on Mac.
113
+
> Specifying an equivalent Windows-only add-in in the manifest has no effect on other platforms, like Office on the web or on Mac.
105
114
106
115
The following scenarios describe what happens depending on how the user acquires the Office Add-in.
107
116
108
117
### AppSource acquisition of an Office Add-in
109
118
110
-
If a user acquires the Office Add-in from AppSource and the equivalent COM add-in is already installed, then Office will:
119
+
If a user acquires the Office Add-in from AppSource and the equivalent Windows-only add-in is already installed, then Office will:
111
120
112
121
1. Install the Office Add-in.
113
122
2. Hide the Office Add-in UI on the ribbon.
114
-
3. Display a call-out for the user that points out the COM add-in ribbon button.
123
+
3. Display a call-out for the user that points out the Windows-only add-in ribbon button.
115
124
116
125
### Centralized deployment of Office Add-in
117
126
118
-
If an admin deploys the Office Add-in to their tenant using centralized deployment, and the equivalent COM add-in is already installed, the user must restart Office before they'll see any changes. After Office restarts, it will:
127
+
If an admin deploys the Office Add-in to their tenant using centralized deployment, and the equivalent Windows-only add-in is already installed, the user must restart Office before they'll see any changes. After Office restarts, it will:
119
128
120
129
1. Install the Office Add-in.
121
130
2. Hide the Office Add-in UI on the ribbon.
122
-
3. Display a call-out for the user that points out the COM add-in ribbon button.
131
+
3. Display a call-out for the user that points out the Windows-only add-in ribbon button.
123
132
124
133
### Document shared with embedded Office Add-in
125
134
126
-
If a user has the COM add-in installed, and then gets a shared document with the embedded Office Add-in, then when they open the document, Office will:
135
+
If a user has the Windows-only add-in installed, and then gets a shared document with the embedded Office Add-in, then when they open the document, Office will:
127
136
128
137
1. Prompt the user to trust the Office Add-in.
129
138
2. If trusted, the Office Add-in will install.
130
139
3. Hide the Office Add-in UI on the ribbon.
131
140
132
-
## Other COM add-in behavior
141
+
## Other Windows-only add-in behavior
133
142
134
143
### Excel, PowerPoint, Word
135
144
136
-
If a user uninstalls the equivalent COM add-in, then Office on Windows restores the Office Add-in UI.
145
+
If a user uninstalls the equivalent Windows-only add-in, then Office on Windows restores the Office Add-in UI.
137
146
138
-
After you specify an equivalent COM add-in for your Office Add-in, Office stops processing updates for your Office Add-in. To acquire the latest updates for the Office Add-in, the user must first uninstall the COM add-in.
147
+
After you specify an equivalent Windows-only add-in for your Office Add-in, Office stops processing updates for your Office Add-in. To acquire the latest updates for the Office Add-in, the user must first uninstall the Windows-only add-in.
139
148
140
149
### Outlook
141
150
142
-
The COM add-in must be connected when Outlook is started in order for the corresponding web add-in to be disabled.
151
+
The Windows-only add-in must be connected when Outlook is started in order for the corresponding Outlook add-in to be disabled.
143
152
144
-
If the COM add-in is then disconnected during a subsequent Outlook session, the web add-in will likely remain disabled until Outlook is restarted.
153
+
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.
Copy file name to clipboardExpand all lines: docs/excel/make-custom-functions-compatible-with-xll-udf.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,7 @@ The manifest configuration depends on what type of manifest the add-in uses.
24
24
25
25
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
26
26
27
-
The following example shows how to specify both a COM add-in and an XLL add-in as equivalents in a unified manifest. Often you specify both. For completeness, this example shows both equivalents in context. They're identified by their [`"alternates.prefer.comAddin.progId"`](/microsoft-365/extensibility/schema/extension-alternate-versions-array-prefer-com-addin#progid) and `"alternates.prefer.xllCustomFunctions.filename"` respectively. For more information on COM add-in compatibility, see [Make your Office Add-in compatible with an existing COM add-in](../develop/make-office-add-in-compatible-with-existing-com-add-in.md).
27
+
The following example shows how to specify both a COM add-in and an XLL add-in as equivalents in a unified manifest. Often you specify both. For completeness, this example shows both equivalents in context. They're identified by their [`"alternates.prefer.comAddin.progId"`](/microsoft-365/extensibility/schema/extension-alternate-versions-array-prefer-com-addin#progid) and `"alternates.prefer.xllCustomFunctions.filename"` respectively. For more information on COM add-in compatibility, see [Make your Office Add-in compatible with an existing COM or VSTO add-in](../develop/make-office-add-in-compatible-with-existing-com-add-in.md).
28
28
29
29
```json
30
30
"extensions" [
@@ -46,7 +46,7 @@ The following example shows how to specify both a COM add-in and an XLL add-in a
46
46
47
47
# [Add-in only manifest](#tab/xmlmanifest)
48
48
49
-
The following example shows how to specify both a COM add-in and an XLL add-in as equivalents in an Excel JavaScript API add-in only manifest file. Often you specify both. For completeness, this example shows both equivalents in context. They're identified by their `ProgId` and `FileName` respectively. The `EquivalentAddins` element must be positioned immediately before the closing `VersionOverrides` tag. For more information on COM add-in compatibility, see [Make your Office Add-in compatible with an existing COM add-in](../develop/make-office-add-in-compatible-with-existing-com-add-in.md).
49
+
The following example shows how to specify both a COM add-in and an XLL add-in as equivalents in an Excel JavaScript API add-in only manifest file. Often you specify both. For completeness, this example shows both equivalents in context. They're identified by their `ProgId` and `FileName` respectively. The `EquivalentAddins` element must be positioned immediately before the closing `VersionOverrides` tag. For more information on COM add-in compatibility, see [Make your Office Add-in compatible with an existing COM or VSTO add-in](../develop/make-office-add-in-compatible-with-existing-com-add-in.md).
50
50
51
51
```xml
52
52
<VersionOverrides>
@@ -90,5 +90,5 @@ The following table compares features across XLL user-defined functions, XLL com
90
90
91
91
## See also
92
92
93
-
-[Make your Office Add-in compatible with an existing COM add-in](../develop/make-office-add-in-compatible-with-existing-com-add-in.md)
93
+
-[Make your Office Add-in compatible with an existing COM or VSTO add-in](../develop/make-office-add-in-compatible-with-existing-com-add-in.md)
0 commit comments