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

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.

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. 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" property of the unified manifest or the 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.

Specify an equivalent Windows-only add-in

Obtain the ID of the Windows-only add-in

Before you can specify an equivalent Windows-only add-in, you must first identify its name with these steps:

1. Open Windows Registry Editor on any computer where the Windows-only 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 Windows-only add-in you need. Note that the names are case-sensitive.

Configure the manifest

To enable compatibility between your Office Add-in and the Windows-only add-in, identify the equivalent Windows-only add-in in the manifest of your Office Add-in using the name that you obtained in the section 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.

"extensions" [
  ...
  "alternates" [
    {
      "prefer": {
        "comAddin": {
          "progId": "ContosoAddin"
        }
      }
    }
  ]
]

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

Configure the Group Policy setting for Outlook add-ins

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.

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 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.
   2. Set Value to the name of the equivalent Windows-only add-in. See the section Obtain the ID of the Windows-only add-in.
   3. Select OK to put the update into effect.

   

Equivalent behavior for users

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.

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

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 Windows-only 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 Windows-only 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 Windows-only 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 Windows-only add-in ribbon button.

Document shared with embedded Office Add-in

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:

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 Windows-only add-in behavior

Excel, PowerPoint, Word

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

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.

Outlook

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

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)

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.

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.

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.

The details to configure this feature depend on which type of manifest is being used by the Office Add-in.

"extensions" [
  {   
    ...
    "alternates": [
      {
        "hide": {
          "windowsExtensions": {
            "effect": "userOptionToDisable",
            "comAddin": {
              "progIds": [
                "ContosoAddin"
              ]
            }
          }
        }
      }
    ]
  }
]

<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