Edit

Share via

Make your Office Add-in compatible with an existing COM add-in

  • Article

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.

Important

COM and VSTO add-ins aren't supported in the new Outlook on Windows that's currently in preview. These add-ins are still supported in the classic Outlook on Windows desktop client. To learn more, see Develop Outlook add-ins for new Outlook on Windows.

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.

Important

The equivalent add-in feature is supported by the following platform and applications. COM add-ins can't be installed on any other platform, so on those platforms the manifest element that is discussed later in this article, EquivalentAddins, is ignored.

  • Excel, Word, and PowerPoint on Windows (Version 1904 or later)
  • Classic Outlook on Windows (Version 2102 or later) against a supported Exchange server version
    • Exchange Online
    • Exchange 2019 Cumulative Update 10 or later (KB5003612)
    • Exchange 2016 Cumulative Update 21 or later (KB5003611)

Specify an equivalent COM add-in

Obtain the ProgId of a COM add-in

Before you can specify an equivalent COM add-in, you must first identify its ProgId. To obtain the ProgId of a COM add-in:

  1. Open Windows Registry Editor on the computer where the COM add-in is installed.
  2. 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.
  3. Copy the name of the registry key associated with the COM add-in you need. Note that the names are case-sensitive.

Configure the manifest

Important

Applies to Excel, Outlook, PowerPoint, and Word.

To enable compatibility between your Office Add-in and COM add-in, identify the equivalent COM add-in in the manifest 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 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 element must be positioned immediately before the closing VersionOverrides tag.

<VersionOverrides>
  ...
  <EquivalentAddins>
    <EquivalentAddin>
      <ProgId>ContosoCOMAddin</ProgId>
      <Type>COM</Type>
    </EquivalentAddin>
  </EquivalentAddins>
</VersionOverrides>

Tip

For information about COM add-in and XLL UDF compatibility, see Make your custom functions compatible with XLL user-defined functions. Not applicable for Outlook.

Configure the Group Policy setting

Important

Applies to Outlook only.

To declare compatibility between your Outlook web add-in and COM add-in, 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. This 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.

  1. Download the latest Administrative Templates tool, paying attention to the tool's Install Instructions.

  2. Open the Local Group Policy Editor (gpedit.msc).

  3. Navigate to User Configuration > Administrative Templates > Microsoft Outlook 2016 > Miscellaneous.

  4. Select the setting Deactivate Outlook web add-ins whose equivalent COM or VSTO add-in is installed.

  5. Open the link to edit the policy setting.

  6. In the dialog Outlook web add-ins to deactivate:

    1. Set Value name to the Id found in the web add-in's manifest. Important: Do not add curly braces {} around the entry.
    2. Set Value to the ProgId of the equivalent COM add-in.
    3. Select OK to put the update into effect.

    The "Outlook web add-ins to deactivate" dialog.

Equivalent behavior for users

When an equivalent COM add-in is specified, 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.

  • Under My add-ins.
  • As an entry on the ribbon manager (Excel, Word, and PowerPoint only).

Note

Specifying an equivalent COM add-in in the manifest has no effect on other platforms, like Office on the web or on Mac.

The following scenarios describe what happens depending on how the user acquires the Office Add-in.

AppSource acquisition of an Office Add-in

If a user acquires the Office Add-in from AppSource and the equivalent COM add-in is already installed, then Office will:

  1. Install the Office Add-in.
  2. Hide the Office Add-in UI on the ribbon.
  3. Display a call-out for the user that points out the COM add-in ribbon button.

Centralized deployment of Office Add-in

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:

  1. Install the Office Add-in.
  2. Hide the Office Add-in UI on the ribbon.
  3. Display a call-out for the user that points out the COM add-in ribbon button.

Document shared with embedded Office Add-in

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:

  1. Prompt the user to trust the Office Add-in.
  2. If trusted, the Office Add-in will install.
  3. Hide the Office Add-in UI on the ribbon.

Other COM add-in behavior

Excel, PowerPoint, Word

If a user uninstalls the equivalent COM add-in, then Office on Windows restores the Office Add-in UI.

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.

Outlook

The COM add-in must be connected when Outlook is started in order for the corresponding web add-in to be disabled.

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.

See also