Registry Entries for Application-Level Add-Ins
You must create a specific set of registry entries when you deploy add-ins that are created by using Visual Studio 2010. These registry entries provide information that enables the Microsoft Office application to discover and load the add-in.
Applies to: The information in this topic applies to application-level projects for Microsoft Office 2010 and the 2007 Microsoft Office system. 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 add-in. If you use ClickOnce to deploy your add-in, the registry entries are automatically created on the end user computer. If you use Windows Installer to deploy your add-in, you must configure the Setup 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 add-ins, see Architecture of Application-Level Add-Ins.
Note
In this topic, the text add-in ID represents a unique ID for your add-in. By default, the ID is the name of your add-in assembly.
Registering Add-ins for the Current User vs. All Users
When an 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 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 add-in). In this case, the registry entries are created under HKEY_LOCAL_MACHINE.
All add-ins that you create by using Visual Studio 2010 can be registered for the current user. However, 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 add-in was deployed.
Microsoft Office Version
Microsoft Office 2010 applications can load add-ins that are registered under HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER.
By default, applications in the 2007 Microsoft Office system can only load add-ins that are registered under HKEY_CURRENT_USER. To load add-ins that are registered under HKEY_LOCAL_MACHINE, computers that have these applications installed must also have hotfix package 976477 installed. For more information, see https://go.microsoft.com/fwlink/?LinkId=184923.
Deployment Type
If you use ClickOnce to deploy an add-in, the 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 an add-in to all users on a computer, you must use Windows Installer to deploy the add-in. For more information about these deployment types, see Publishing Office Solutions by Using ClickOnce and Publishing an Office Solution by Using Windows Installer.
Registry Entries
The required 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.
Root\Software\Microsoft\Office\application name\Addins\add-in ID
For Visio, the registry entries belong under the following registry key.
Root\Software\Microsoft\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 add-in. This description is displayed when the user selects the 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 add-in that is displayed in the COM Add-Ins dialog box in the Microsoft Office application. The default value is the add-in ID. |
LoadBehavior |
REG_DWORD |
Required. A value that specifies when the application attempts to load the add-in and the current state of the add-in (loaded or unloaded). By default, this entry is set to 3, which specifies that the add-in is loaded at startup. For more information, see LoadBehavior Values. |
Manifest |
REG_SZ |
Required. The full path of the deployment manifest for the 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, 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 Publishing an Office Solution by Using Windows Installer. .gif "Note") Note
If you have Visual Studio 2010 Service Pack 1 (SP1) installed on your development computer, you must add the prefix file:/// to the manifest registry key. If you do not add this prefix and your add-in reads data from the application configuration file, users might receive an error when the add-in loads.
Note
When you build an add-in on the development computer, Visual Studio automatically appends the |vstolocal string and adds the file:/// prefix to this registry key.
|
Warmup |
REG_DWORD |
Optional. A value that indicates that the .NET Framework and Visual Studio Tools for Office runtime load before an add-in loads and reduce the perceived time to load an add-in. Set the Warmup entry to 1 and use this in conjunction with LoadBehavior entry to reduce the load time for Outlook 2010 add-ins that are deployed by using Windows Installer (.msi). This registry key cannot be set by using ClickOnce. |
Registry Entries for Outlook Form Regions
If you create a custom form region in an 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 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 add-in, the registry entries are automatically created on the end user computer. If you use Windows Installer to deploy your add-in, you must configure the Setup 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.
LoadBehavior Values
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 add-in. The lowest order bit (values 0 and 1) indicates whether the add-in is currently unloaded or loaded. Other bits indicate when the application attempts to load the add-in.
Typically, the LoadBehavior entry is intended to be set to 0, 3, or 16 (in decimal) when the add-in is installed on end user computers. By default, Visual Studio sets the LoadBehavior entry of your 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 an add-in manually or programmatically. To load an add-in manually, select the check box next to the add-in in the COM Add-Ins dialog box in the application. To load an add-in programmatically, set the Connect property of the COMAddIn object that represents the add-in to true.
Value (in decimal) |
Add-in status |
Add-in load behavior |
Description |
|---|---|---|---|
0 |
Unloaded |
Do not load automatically |
The application never tries to load the add-in automatically. The user can try to manually load the add-in, or the add-in can be loaded programmatically. If the add-in is successfully loaded, the LoadBehavior value remains 0, but the status of the add-in in the COM Add-ins dialog box is updated to indicate that the add-in is loaded. |
1 |
Loaded |
Do not load automatically |
The application never tries to load the add-in automatically. The user can try to manually load the add-in, or the add-in can be loaded programmatically. Although the COM Add-ins dialog box indicates that the add-in is loaded after the application starts, the add-in isn't actually loaded until it is loaded manually or programmatically. If the application successfully loads the 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 add-in automatically. The user can try to manually load the add-in, or the add-in can be loaded programmatically. If the application successfully loads the 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 add-in when the application starts. This is the default value when you build or publish an add-in in Visual Studio. If the application successfully loads the add-in, the LoadBehavior value remains 3. If an error occurs when loading the 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 add-in automatically. The user can try to manually load the add-in, or the add-in can be loaded programmatically. If the application successfully loads the add-in, the LoadBehavior value changes to 9. |
9 |
Loaded |
Load on demand |
The 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 add-in (for example, a custom button in the Ribbon). If the application successfully loads the add-in, the LoadBehavior value remains 9, but the status of the add-in in the COM Add-ins dialog box is updated to indicate that the add-in is currently loaded. If an error occurs when loading the add-in, the LoadBehavior value changes to 8. |
16 |
Loaded |
Load first time, then load on demand |
Set this value if you want your add-in to be loaded on demand. The application loads the 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 add-in, but the add-in is not loaded until the user clicks a UI element that is associated with the add-in. When the application successfully loads the add-in for the first time, the LoadBehavior value remains 16 while the add-in is loaded. After the application closes, the LoadBehavior value changes to 9. |
See Also
Concepts
Architecture of Application-Level Add-Ins
Office Solution Build Process Overview