Export (0) Print
Expand All

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

  • 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.

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

NoteNote:

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).

NoteNote:

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.

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

NoteNote:

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.

NoteNote:

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>

NoteNote:

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.

NoteNote:

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).

NoteNote:

Do not move the registry keys that are under HKEY_CURRENT_USER\Software\Microsoft in these scenarios.

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.

Community Additions

ADD
Show:
© 2014 Microsoft