Registry Entries for VSTO Add-ins

 

You must create a specific set of registry entries when you deploy VSTO Add-ins that are created by using Visual Studio. These registry entries provide information that enables the Microsoft Office application to discover and load the VSTO Add-in.

Applies to: The information in this topic applies to VSTO add-in projects. For more information, see Features Available by Office Application and Project Type.

When you build your project, Visual Studio creates these registry entries on the development computer so that you can easily run and debug the VSTO Add-in. If you use ClickOnce to deploy your VSTO Add-in, the registry entries are automatically created on the end user computer. If you use Windows Installer to deploy your VSTO Add-in, you must configure the InstallShield Limited Edition project to create the registry entries on the end user computer.

For more information about how the registry entries are used during the load process for VSTO Add-ins, see Architecture of VSTO Add-ins.

System_CAPS_noteNote

In this topic, the text add-in ID represents a unique ID for your VSTO Add-in. By default, the ID is the name of your VSTO Add-in assembly.

When a VSTO Add-in is installed, it can be registered in two ways:

  • For the current user only (that is, it is available only to the user that is logged onto the computer when the VSTO Add-in is installed). In this case, the registry entries are created under the HKEY_CURRENT_USER.

  • For all users (that is, any user that logs onto the computer can use the VSTO Add-in). In this case, the registry entries are created under HKEY_LOCAL_MACHINE.

All VSTO Add-ins that you create by using Visual Studio can be registered for the current user. However, VSTO Add-ins can be registered for all users only in certain scenarios. These scenarios depend on the version of Microsoft Office on the computer and how the VSTO Add-in was deployed.

Office applications can load VSTO Add-ins that are registered under HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER.

To load VSTO Add-ins that are registered under HKEY_LOCAL_MACHINE, computers must have update package 976477 installed. For more information, see http://go.microsoft.com/fwlink/?LinkId=184923.

If you use ClickOnce to deploy a VSTO Add-in, the VSTO Add-in can be registered only for the current user. This is because ClickOnce only supports creating keys under HKEY_CURRENT_USER. If you want to register a VSTO Add-in to all users on a computer, you must use Windows Installer to deploy the VSTO Add-in. For more information about these deployment types, see Deploying an Office Solution by Using ClickOnce and Deploying an Office Solution by Using Windows Installer.

The required VSTO Add-in registry entries are located under the following registry key for all applications except Visio, where Root is HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE.

All applications except for Visio

Office version

Configuration Path

32-bit

Root\Software\Microsoft\Office\application name\Addins\add-in ID

64-bit

Root\Software\Wow6432Node\Microsoft\Office\application name\Addins\add-in ID

Visio

Office version

Configuration Path

32-bit

Root\Software\Microsoft\Visio\Addins\add-in ID

64-bit

Root\Software\Wow6432Node\Visio\Addins\add-in ID

The following table lists the entries under this registry key.

Entry

Type

Value

Description

REG_SZ

Required. A brief description of the VSTO Add-in.

This description is displayed when the user selects the VSTO Add-in in the Add-Ins pane of the Options dialog box in the Microsoft Office application.

FriendlyName

REG_SZ

Required. A descriptive name of the VSTO Add-in that is displayed in the COM Add-Ins dialog box in the Microsoft Office application. The default value is the VSTO Add-in ID.

LoadBehavior

REG_DWORD

Required. A value that specifies when the application attempts to load the VSTO Add-in and the current state of the VSTO Add-in (loaded or unloaded).

By default, this entry is set to 3, which specifies that the VSTO Add-in is loaded at startup. For more information, see LoadBehavior Values.

System_CAPS_noteNote

If a user disables the VSTO Add-in, that action modifies LoadBehavior value in the HKEY_CURRENT_USER registry hive. For each user, the value of the LoadBehavior value in the HKEY_CURRENT_USER hive overrides the default LoadBehavior defined in the HKEY_LOCAL_MACHINE hive.

Manifest

REG_SZ

Required. The full path of the deployment manifest for the VSTO Add-in. The path can be a location on the local computer, a network share (UNC), or a Web server (HTTP).

If you use Windows Installer to deploy the solution, you must add the prefix file:/// to the manifest path. You must also append the string |vstolocal (that is, the pipe character | followed by vstolocal) to the end of this path. This ensures that your solution is loaded from the installation folder, rather than the ClickOnce cache. For more information, see Deploying an Office Solution by Using Windows Installer.

System_CAPS_noteNote

When you build a VSTO Add-in on the development computer, Visual Studio automatically appends the |vstolocal string to this registry entry.

If you create a custom form region in a VSTO Add-in for Outlook, additional registry entries are used to register the form region with Outlook. These entries are created under a different registry key for each message class that the form region supports. These registry keys are in the following location, where Root is HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE.

Root\Software\Microsoft\Office\Outlook\FormRegions\message class

Like the other registry entries shared by all VSTO Add-ins, Visual Studio creates the form region registry entries on the development computer when you build your project. If you use ClickOnce to deploy your VSTO Add-in, the registry entries are automatically created on the end user computer. If you use Windows Installer to deploy your VSTO Add-in, you must configure the InstallShield Limited Edition project to create the registry entries on the end user computer.

For more information about the form region registry entries, see Specifying Form Regions in the Windows Registry. For more information about Outlook form regions, see Creating Outlook Form Regions.

The LoadBehavior entry under the Root\Software\Microsoft\Office\application name\Addins\add-in ID key contains a bitwise combination of values that specify the run time behavior of the VSTO Add-in. The lowest order bit (values 0 and 1) indicates whether the VSTO Add-in is currently unloaded or loaded. Other bits indicate when the application attempts to load the VSTO Add-in.

Typically, the LoadBehavior entry is intended to be set to 0, 3, or 16 (in decimal) when the VSTO Add-in is installed on end user computers. By default, Visual Studio sets the LoadBehavior entry of your VSTO Add-in to 3 when you build or publish it.

The following table lists all the possible values of the LoadBehavior entry. Some descriptions in this table refer to loading a VSTO Add-in manually or programmatically. To load a VSTO Add-in manually, select the check box next to the VSTO Add-in in the COM Add-Ins dialog box in the application. To load a VSTO Add-in programmatically, set the P:Microsoft.Office.Core.COMAddIn.Connect property of the T:Microsoft.Office.Core.COMAddIn object that represents the VSTO Add-in to true.

Value (in decimal)

VSTO Add-in status

VSTO Add-in load behavior

Description

0

Unloaded

Do not load automatically

The application never tries to load the VSTO Add-in automatically. The user can try to manually load the VSTO Add-in, or the VSTO Add-in can be loaded programmatically.

If the VSTO Add-in is successfully loaded, the LoadBehavior value remains 0, but the status of the VSTO Add-in in the COM Add-ins dialog box is updated to indicate that the VSTO Add-in is loaded.

1

Loaded

Do not load automatically

The application never tries to load the VSTO Add-in automatically. The user can try to manually load the VSTO Add-in, or the VSTO Add-in can be loaded programmatically.

Although the COM Add-ins dialog box indicates that the VSTO Add-in is loaded after the application starts, the VSTO Add-in isn't actually loaded until it is loaded manually or programmatically.

If the application successfully loads the VSTO Add-in, the LoadBehavior value changes to 0, and remains at 0 after the application closes.

2

Unloaded

Load at startup

The application does not try to load the VSTO Add-in automatically. The user can try to manually load the VSTO Add-in, or the VSTO Add-in can be loaded programmatically.

If the application successfully loads the VSTO Add-in, the LoadBehavior value changes to 3, and remains at 3 after the application closes.

3

Loaded

Load at startup

The application tries to load the VSTO Add-in when the application starts. This is the default value when you build or publish a VSTO Add-in in Visual Studio.

If the application successfully loads the VSTO Add-in, the LoadBehavior value remains 3. If an error occurs when loading the VSTO Add-in, the LoadBehavior value changes to 2, and remains at 2 after the application closes.

8

Unloaded

Load on demand

The application does not try to load the VSTO Add-in automatically. The user can try to manually load the VSTO Add-in, or the VSTO Add-in can be loaded programmatically.

If the application successfully loads the VSTO Add-in, the LoadBehavior value changes to 9.

9

Loaded

Load on demand

The VSTO Add-in will be loaded only when the application requires it, such as when a user clicks a UI element that uses functionality in the VSTO Add-in (for example, a custom button in the Ribbon).

If the application successfully loads the VSTO Add-in, the LoadBehavior value remains 9, but the status of the VSTO Add-in in the COM Add-ins dialog box is updated to indicate that the VSTO Add-in is currently loaded. If an error occurs when loading the VSTO Add-in, the LoadBehavior value changes to 8.

16

Loaded

Load first time, then load on demand

Set this value if you want your VSTO Add-in to be loaded on demand. The application loads the VSTO Add-in when the user runs the application for the first time. The next time the user runs the application, the application loads any UI elements that are defined by the VSTO Add-in, but the VSTO Add-in is not loaded until the user clicks a UI element that is associated with the VSTO Add-in.

When the application successfully loads the VSTO Add-in for the first time, the LoadBehavior value remains 16 while the VSTO Add-in is loaded. After the application closes, the LoadBehavior value changes to 9.

Show: