Export (0) Print
Expand All

Deploying Application-Level Add-ins

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.

NoteNote

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" in this topic.

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

NoteNote

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" in this topic.

NoteNote

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:

  • The deployment manifest (OutlookAddin1.application).

    C:\DeployFolder\OutlookAddin1_1.0.0.0

    This folder contains:

    • The assemblies.

    • The application manifest (OutlookAddin1.dll.manifest).

    • A copy of the deployment manifest.

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:

    • The original assemblies.

    • The original application manifest.

    • The original deployment manifest.

    C:\DeployFolder\OutlookAddin1_1.0.0.1

    This folder contains:

    • The updated assemblies.

    • The updated application manifest.

    • A copy of the updated deployment manifest.

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.

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.

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

    NoteNote
    The ManifestLocation value is applicable only to Office 2003 add-ins.

    ManifestName

    REG_SZ

    The name of the application manifest for the add-in.

    NoteNote
    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

    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

    Manifest

    REG_SZ

    The full path of the application manifest for the add-in. This must be a local path on the client computer.

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

    NoteNote
    The ManifestLocation value is applicable only to Office 2003 add-ins.

    ManifestName

    REG_SZ

    The name of the application manifest for the add-in.

    NoteNote
    The ManifestName value is applicable only to Office 2003 add-ins.

    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.

See Also

Community Additions

ADD
Show:
© 2014 Microsoft