Deploying an application-level add-in created by using Visual Studio Tools for Office generally means working with the following files:
-
The primary add-in assembly, and any dependent assemblies such as resources, satellites, or helper libraries.
-
The application manifest.
-
The deployment manifest (if applicable).
For more information about application-level add-ins, see Office Solutions Architecture Overview.
Deployment Overview
When you deploy your solution, you must keep the following basic ideas in mind:
To deploy the add-in, perform these steps:
-
Copy the application manifest generated by the build process and the required registry keys to each client computer.
-
Copy the add-in assemblies (and optionally the deployment manifest and an updated application manifest) to the deployment location.
The deployment location can be a local folder on the client computer, or it can be a remote location such as a network share. For more information, see Deployment Models and How to: Deploy Office Solutions.
.gif) Note |
|---|
| There is no deployment option that enables end users to use the COM Add-Ins dialog box in Microsoft Office 2003 or in 2007 Microsoft Office system applications to install an add-in that was created by using Visual Studio Tools for Office. |
Using the Setup Project
When you create an add-in project by using Visual Studio Tools for Office, a Setup project is automatically added to the solution. If you want to deploy your solution directly to the client computer, you can use this Setup project to generate a Microsoft Windows Installer (.msi) file that copies the solution files to the client computer and creates the registry entries required to run the add-in. For more information about the Setup project, see Setup Projects for Application-Level Add-ins. For more information about the registry entries required to run add-ins, see Required Registry Entries.
Using the Publish Wizard
If you want to deploy your add-in using a deployment manifest, you can use the Publish Wizard. The Publish Wizard creates a deployment manifest for the solution and copies all of the required files to the deployment location.
The Publish command on the project's shortcut menu in Solution Explorer starts the Publish Wizard. You enter the location of the folder to which you want to publish the solution, and the wizard copies the deployment manifest into that folder. The wizard also copies the assemblies and an updated application manifest into a subfolder of the main deployment folder. The subfolder name contains a version number. If the Automatically increment revision with each release option is selected in the Publish pane of the Project Designer, a new subfolder is created each time you publish the solution, so that older versions are still available. The application and deployment manifests make sure that the solution always uses the correct assembly. For more information, see Application and Deployment Manifests in Office Solutions, How to: Deploy Solution Files Using the Publish Wizard, and Publish Pane, Project Designer (Visual Studio Tools for Office).
| Note |
|---|
| The Publish Wizard does not create the registry entries required to run the add-in. If you use the Publish Wizard to deploy an add-in, you must create these registry entries yourself—for example, by using a registry (.reg) file. The Publish Wizard also does not overwrite or remove the registry entries that are created on the development computer when you build your project. For more information about building projects, see Office Solution Build Process Overview. For more information about the registry entries required to run add-ins, see Required Registry Entries. |
| Note |
|---|
| The Publish Wizard does not grant full trust to the add-in assembly for the end user. If you use the Publish Wizard to deploy an add-in, you must also deploy the required security policy to each end user. For more information, see Security Requirements to Run Office Solutions. |
Updating Deployed Assemblies (Versioning)
If you deploy a solution named OutlookAddin1 to the folder C:\DeployFolder, the file structure will look like this:
C:\DeployFolder
This folder contains:
If you update the assembly and republish the solution, the directory structure will look like this:
C:\DeployFolder
This folder contains:
-
The deployment manifest (updated to point to the application manifest in C:\DeployFolder\OutlookAddin1_1.0.0.1).
C:\DeployFolder\OutlookAddin1_1.0.0.0
This folder contains:
C:\DeployFolder\OutlookAddin1_1.0.0.1
This folder contains:
This structure will be repeated each time you update the add-in assembly.
Using MSBuild at a Command Prompt
You can also use MSBuild at a command prompt to publish your solution. When you use MSBuild at a command prompt, you can publish your solution files to one location, and simultaneously modify the deployment manifest and the updated application manifest to point to a different location. To run MSBuild at a command prompt to publish your solution, use the following syntax:
msbuild.exe /target:Publish /property:UpdateUrl=<update location> /property:PublishDir=<publish location> <project file>
For example, if you want to publish a C# project named OutlookAddin1 to the shared folder \\PublishServer\PublishFolder, but you expect to move the deployment manifest, updated application manifest, and the add-in assembly to the shared folder \\DeploymentServer\DeploymentFolder in the future, you would run the following command:
msbuild.exe /target:Publish /property:PublishDir=\\PublishServer\PublishFolder\ /property:UpdateUrl=\\DeploymentServer\DeploymentFolder\ C:\OutlookAddin1\OutlookAddin1.csproj
For more information about using MSBuild at a command prompt, see Building ClickOnce Applications from the Command Line.
Deploying Add-ins on Windows Vista
If end users run your solution on Windows Vista, you must take the Windows Vista security restrictions into account when you set up the deployment, or users will not be able to install updates.
If you use the Publish Wizard to publish add-in updates to an HTTP or network location, end users on computers that are running Windows Vista can load assembly updates only under the following conditions:
-
The application manifest is installed to a folder on the end user computer that can be modified by an application with standard privileges.
- or -
-
The user runs the Microsoft Office application with administrator privileges.
When you publish an update to an add-in, the Visual Studio Tools for Office runtime tries to copy the updated application manifest to the end user computer the next time the user opens the application. The runtime then uses the information in the updated manifest to load the updated assembly. On Windows Vista, applications that run with standard privileges cannot overwrite files in certain folders, including %ProgramFiles%. Therefore, if the application manifest is installed to a folder that requires administrator privileges, the application can load the updated assembly only if the user runs the application as an administrator. Alternatively, the user can run the application with standard privileges if the application manifest is installed to a folder that does not require administrator privileges, such as %UserProfile%.
| Note |
|---|
| The Setup project that is created with add-in projects installs the application manifest to %CommonProgramFiles% by default. |
Application and Deployment Manifests
Application and deployment manifests make it possible for an add-in to update itself with the latest assembly. For more information, see Application and Deployment Manifests in Office Solutions.
You might change the application or deployment manifest for a solution several times during the lifetime of the solution. There are two main reasons why you would update the manifests:
Required Registry Entries
Add-ins that are created by using Visual Studio Tools for Office require a set of registry entries on each computer that runs the add-in. These registry entries point to the location of the application manifest and provide additional information about the add-in.
If you use the Setup project that is included with add-in projects to deploy your add-in, the Windows Installer (.msi) file that is generated by the Setup project creates these registry entries for you. If you use the Publish Wizard to deploy your add-in, you must create these registry entries yourself—for example, by using a registry (.reg) file.
The following table lists the required registry keys and the associated entries and values. The text <add-in ID> represents a unique ID for your add-in. Typically, the add-in ID is the name of the add-in assembly. 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.
|
Registry key
|
Entry
|
Type
|
Value
|
| HKEY_CURRENT_USER\Software\Microsoft\Office\<application name>\Addins\<add-in ID> or (for Visio add-ins only) HKEY_CURRENT_USER\Software\Microsoft\Visio\Addins\<add-in ID> | Description | REG_SZ | A brief description of the add-in. In add-ins for the 2007 Microsoft Office system, 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 determines when the add-in is loaded. This value should be set to 3, which specifies that the add-in is loaded at startup. |
| | Manifest | REG_SZ | The full path of the application manifest for the add-in. This must be a local path on the client computer. | Note |
|---|
| The Manifest value is applicable only to add-ins for the 2007 Microsoft Office system. |
|
| | ManifestLocation | REG_SZ | The location of the application manifest for the add-in. This must be a local folder on the client computer. | Note |
|---|
| The ManifestLocation value is applicable only to Office 2003 add-ins. |
|
| | ManifestName | REG_SZ | The name of the application manifest for the add-in. | Note |
|---|
| The ManifestName value is applicable only to Office 2003 add-ins. |
|
| HKEY_CURRENT_USER\Software\Classes\<add-in ID> | (Default) | REG_SZ | The description of the add-in. |
| HKEY_CURRENT_USER\Software\Classes\<add-in ID>\CLSID | (Default) | REG_SZ | The globally unique class identifier (CLSID) of the add-in. |
| HKEY_CURRENT_USER\Software\Classes\CLSID\{<add-in CLSID>} | (Default) | REG_SZ | The description of the add-in. |
| HKEY_CURRENT_USER\Software\Classes\CLSID\{<add-in CLSID>}\InprocServer32 | (Default) | REG_SZ - or - REG_EXPAND_SZ | The full path of AddinLoader.dll on the computer that is running the add-in. On your development computer, if you install Visual Studio Tools for Office to the default location, this entry will be set to %CommonProgramFiles%\Microsoft Shared\VSTO\8.0\AddinLoader.dll. | 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 location 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 | (Default) | REG_SZ | The unique ID of the add-in. |
| HKEY_CURRENT_USER\Software\Classes\CLSID\{<add-in CLSID>}\Programmable | (Default) | REG_SZ | Do not set a value for this entry. |
| HKEY_CURRENT_USER\Software\Classes\CLSID\{<add-in CLSID>}\VersionIndependentProgID | (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:
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. This is 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.
| Note |
|---|
| Do not move the registry keys that are under HKEY_CURRENT_USER\Software\Microsoft in these scenarios. |
See Also