Registry Entries for Application-Level Add-Ins
Applies to |
|---|
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type
Microsoft Office version
For more information, see Features Available by Application and Project Type. |
You must create a specific set of registry entries when you deploy add-ins that are created by using Visual Studio Tools for Office. These registry entries provide information that enables the Microsoft Office application to discover and load the add-in. For more information, see Architecture of Application-Level Add-Ins.
When you build your project, Visual Studio Tools for Office creates these registry entries on the development computer so that you can easily debug the add-in. For more information, see Office Solution Build Process Overview.
For information about how to create the registry keys on end user computers when you deploy the add-in, see Deploying Office Solutions (2007 System) and Deploying Application-Level Add-Ins (2003 System).
In this topic, the text add-in ID represents a unique ID for your add-in. By default, the ID is the name of the add-in project.
Registry Entries for the 2007 Microsoft Office System
The required add-in registry entries for the 2007 Microsoft Office system are located under the following registry key for all applications except Microsoft Office Visio:
HKEY_CURRENT_USER\Software\Microsoft\Office\application name\Addins\add-in ID
For Visio, the registry entries belong under the following registry key:
HKEY_CURRENT_USER\Software\Microsoft\Visio\Addins\add-in ID
Note
Applications in the 2007 Microsoft Office system only recognize Visual Studio Tools for Office add-ins that are registered under HKEY_CURRENT_USER. This means that you cannot deploy a Visual Studio Tools for Office add-in for the 2007 Microsoft Office system to all users on a computer by registering the add-in under HKEY_LOCAL_MACHINE.
The following table lists the entries that are required under this registry key.
Entry |
Type |
Value |
|---|---|---|
Description |
REG_SZ |
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 |
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 |
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 |
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). Note When you build an add-in on the development computer, Visual Studio Tools for Office appends the string |vstolocal (that is, the pipe character | followed by vstolocal) to this registry entry. This helps Visual Studio Tools for Office to load the add-in when you run it from Visual Studio on the development computer. |
Registry Entries for Outlook Form Regions
If you create a custom form region in an add-in for Microsoft Office Outlook 2007, 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:
HKEY_CURRENT_USER\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 Setup program generated by the publish process also creates the 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.
Registry Entries for Microsoft Office 2003
The required add-in registry entries for Microsoft Office 2003 are located under the following registry keys:
HKEY_CURRENT_USER\Software\Microsoft\Office\application name\Addins\add-in ID
HKEY_CURRENT_USER\Software\Classes\add-in ID\CLSID
HKEY_CURRENT_USER\Software\Classes\CLSID\{add-in CLSID}
HKEY_CURRENT_USER\Software\Classes\CLSID\{add-in CLSID}\InprocServer32
HKEY_CURRENT_USER\Software\Classes\CLSID\{add-in CLSID}\ProgID
HKEY_CURRENT_USER\Software\Classes\CLSID\{add-in CLSID}\Programmable
HKEY_CURRENT_USER\Software\Classes\CLSID\{add-in CLSID}\VersionIndependentProgID
Note
You can make a Visual Studio Tools for Office add-in for Microsoft Office 2003 available to all users on a computer by creating the registry keys under HKEY_LOCAL_MACHINE instead of HKEY_CURRENT_USER.
The following sections list the entries that are required under each registry key. The text add-in CLSID represents the globally unique class identifier (CLSID) of your add-in. To obtain the CLSID of your add-in, you can refer to one of the following locations:
The default value of the HKEY_CURRENT_USER\Software\Classes\add-in ID\CLSID registry entry created on your development computer when you build the add-in.
The ProjectGuid element in the .csproj (for C#) or .vbproj (for Visual Basic) project files.
Note
You must create some of the registry entries in the following list in a different subtree if you are deploying a Microsoft Office 2003 add-in to Windows Vista. For more information, see Registry Entries for Microsoft Office 2003 Add-ins on Windows Vista.
HKEY_CURRENT_USER\Software\Microsoft\Office\<application name>\Addins\<add-in ID>
Note
For Visio add-ins, use the following key: HKEY_CURRENT_USER\Software\Microsoft\Visio\Addins\add-in ID
Entry |
Type |
Value |
|---|---|---|
Description |
REG_SZ |
A brief description of the add-in. |
FriendlyName |
REG_SZ |
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 |
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 |
The full path of the application manifest for the add-in. This must be a local folder on the client computer. |
HKEY_CURRENT_USER\Software\Classes\add-in ID
Entry |
Type |
Value |
|---|---|---|
(Default) |
REG_SZ |
The description of the add-in. |
HKEY_CURRENT_USER\Software\Classes\add-in ID\CLSID
Entry |
Type |
Value |
|---|---|---|
(Default) |
REG_SZ |
The globally unique class identifier (CLSID) of the add-in. |
HKEY_CURRENT_USER\Software\Classes\CLSID\{<add-in CLSID>}
Entry |
Type |
Value |
|---|---|---|
(Default) |
REG_SZ |
The description of the add-in. |
HKEY_CURRENT_USER\Software\Classes\CLSID\{<add-in CLSID>}\InprocServer32
Entry |
Type |
Value |
|---|---|---|
(Default) |
REG_SZ - or - REG_EXPAND_SZ |
The full path of the Visual Studio Tools for Office loader on the computer that is running the add-in. This entry should always be set to %CommonProgramFiles%\Microsoft Shared\VSTO\8.0\AddinLoader.dll. For more information about the Visual Studio Tools for Office loader, see Visual Studio Tools for Office Runtime Overview. Note If you use an environment variable in the path, use the REG_EXPAND_SZ type for this entry. Otherwise, use the REG_SZ type. |
ManifestLocation |
REG_SZ |
The path of the application manifest for the add-in. This must be a local folder on the client computer. |
ManifestName |
REG_SZ |
The name of the application manifest for the add-in. |
ThreadingModel |
REG_SZ |
The threading model. This entry must be set to Both. |
HKEY_CURRENT_USER\Software\Classes\CLSID\{<add-in CLSID>}\ProgID
Entry |
Type |
Value |
|---|---|---|
(Default) |
REG_SZ |
The unique ID of the add-in. |
HKEY_CURRENT_USER\Software\Classes\CLSID\{<add-in CLSID>}\Programmable
Entry |
Type |
Value |
|---|---|---|
(Default) |
REG_SZ |
Do not set a value for this entry. |
HKEY_CURRENT_USER\Software\Classes\CLSID\{<add-in CLSID>}\VersionIndependentProgID
Entry |
Type |
Value |
|---|---|---|
(Default) |
REG_SZ |
The version-independent unique ID of the add-in. |
Registry Entries for Microsoft Office 2003 Add-ins on Windows Vista
If you are deploying a Microsoft Office 2003 add-in to a computer that is running Windows Vista, you must create several of the registry keys in a different registry subtree in the following scenarios:
The user is running the Microsoft Office 2003 application with a full administrator access token.
- or -
The user has turned off User Account Control (UAC).
In these scenarios, you must create the COM registration keys (that is, all of the keys that are defined under HKEY_CURRENT_USER\Software\Classes) under HKEY_LOCAL_MACHINE\Software\Classes instead.
You must use the Machine subtree because Windows Vista looks for COM registration keys only under HKEY_LOCAL_MACHINE in these scenarios. For information about how to change the registry keys in the default Setup project, see Setup Projects for Application-Level Add-ins (2003 System).
Note
Do not move the registry keys that are under HKEY_CURRENT_USER\Software\Microsoft in these scenarios.
LoadBehavior Values
The LoadBehavior entry under the HKEY_CURRENT_USER\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, 9, 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 |
Set this value if you want your add-in to be loaded on demand. That is, 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 |
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
Deploying Office Solutions (2007 System)
Deploying Application-Level Add-Ins (2003 System)