Registry Entries for Application-Level Add-Ins

Registry Entries for Application-Le...

Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0)

Updated: November 2007

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 Application-level projects Microsoft Office version 2007 Microsoft Office system Microsoft Office 2003 For more information, see Features Available by Application and Project Type.

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

Application-level projects

Microsoft Office version

2007 Microsoft Office system
Microsoft Office 2003

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, a registry entry is used to register the form region with Outlook. This registry entry is located under the following key:

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

For more information, 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 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 when you build or deploy your add-in.

The following table lists the possible values of the LoadBehavior entry.

Value (in decimal)	Meaning of the value	Description
0	Unloaded	The application does not try to load the add-in when the application starts. The user can try to manually load the add-in by using the COM Add-Ins dialog box in the application.
1	Loaded	The application does not try to load the add-in when the application starts. The user can try to manually load the add-in by using the COM Add-Ins dialog box in the application.
2	Load at startup \| Unloaded	The application tries to load the add-in when the application starts. If the application successfully loads the add-in, the LoadBehavior value changes to 3.
3	Load at startup \| Loaded	The application tries to load the add-in when the application starts. 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.
8	Load on demand \| Unloaded	The application tries to load the add-in only when the application requires it, such as when a user clicks a user interface (UI) element that uses functionality in the add-in. If the application successfully loads the add-in, the LoadBehavior value changes to 9.
9	Load on demand \| Loaded	The application tries to load the add-in only when the application requires it, such as when a user clicks a UI element that uses functionality in the add-in. If the application successfully loads the add-in, the LoadBehavior value remains 9. If an error occurs when loading the add-in, the LoadBehavior value changes to 8.
16	Load at first startup	The application loads the add-in when the user runs the application for the first time. The next time the application starts, 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. If the application successfully loads the add-in the next time that the application starts, the LoadBehavior value changes to 9.