Deploying Document-Level Customizations
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

Deploying Document-Level Customizations

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005


    Visual Studio Team System

  • Microsoft Office 2003

Deploying a document-level customization for Microsoft Office Word 2003 or Microsoft Office Excel 2003 generally means working with four files:

  • The Word or Excel file (template, document, or workbook) that the end user works in.

  • The assembly that contains your compiled custom code and any dependent assemblies such as resources, satellites, or helper libraries.

  • The deployment manifest (if applicable).

  • The application manifest (if applicable).

When you deploy your solution, you must keep the following basic ideas in mind:

To deploy the solution, you copy the document and assembly, and optionally the application and deployment manifest, to the deployment location. For more information about the types of deployment, see Deployment Models.

Visual Studio Tools for Office includes the Publish Wizard, which creates the application and deployment manifests and copies all of the files to the deployment location for you. However, you can also do these steps manually. For more information, see How to: Deploy Office Solutions and How to: Deploy Solution Files Using the Publish Wizard.

For more information about document-level customizations, see Office Solutions Architecture Overview.

Publish Wizard

The Publish command on the project's shortcut menu in Solution Explorer starts the Publish Wizard. You enter the location of the folder that you want to publish the solution to, and the wizard copies the document and the deployment manifest into that folder. For more information, see How to: Deploy Solution Files Using the Publish Wizard.

The wizard also copies the assemblies and an updated application manifest into a subfolder of the main deployment folder. The subfolder 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 current 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).

Updating Deployed Assemblies (Versioning)

If you deploy a solution named ExcelWorkbook1 to the folder C:\DeployFolder, the file structure will look like this:


This folder contains:

  • The workbook (ExcelWorkbook1.xls).

  • The deployment manifest (ExcelWorkbook1.application).


    This folder contains:

    • The assemblies.

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

    • A copy of the workbook.

    • A copy of the deployment manifest.

If you update the assembly and republish the solution, the directory structure will look like this:


This folder contains:

  • The workbook (with an updated embedded application manifest).

  • The deployment manifest (updated to point to the application manifest in C:\DeployFolder\ExcelWorkbook1_1.0.0.1).


    This folder contains:

    • The original assemblies.

    • The original application manifest.

    • The original workbook.

    • The original deployment manifest.


    This folder contains:

    • The updated assemblies.

    • The updated application manifest.

    • A copy of the updated workbook.

    • A copy of the updated deployment manifest.

This structure will be repeated each time you update the assembly. If you update the document or workbook so that it is no longer compatible with the existing assembly, you should deploy the solution to a new deployment folder.

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 application manifest embedded in the workbook or document to point to a deployment manifest at 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 ExcelWorkbook1 to the shared folder \\PublishServer\PublishFolder, but you expect to move the deployment manifest, external application manifest, and the 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:\ExcelWorkbook1\ExcelWorkbook1.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 are used to make it possible for a document to update itself with the latest assembly. For more information, see Application and Deployment Manifests in Office Solutions.

Updating Deployment Manifests

You might change the deployment manifest for a solution several times during the lifetime of the solution. There are two main reasons why you would update the deployment manifest:

Updating Application Manifests

You might not ever have to directly update an existing application manifest that is in use in a solution. Usually, you create a new application manifest and use the deployment manifest to load the new application manifest into the solution. However, there are two main reasons why you might want to update an application manifest in a document directly:

  • The deployment manifest and the assemblies have been moved to a new server because the original server is being taken out of service. In this case, you must change the paths to those items in the application manifest. For more information, see How to: Change the Location of Document-Level Customizations.

  • You want to remove the application manifest from the document. For example, you might want to archive the document and you do not want it to run code and possibly change, or you might want to send the completed document out of your workgroup without any reference to the code. For more information, see How to: Remove Managed Code Extensions from Documents.

Deploying Localized Microsoft Office Solutions

Most aspects of deploying localized versions of Visual Studio Tools for Office solutions are the same as you encounter when you deploy other kinds of solutions using Visual Studio. However, there are some additional considerations regarding creating and distributing localized versions of Visual Studio Tools for Office solutions. For more information, see Globalization and Localization of Office Solutions, How to: Localize Excel Solutions, and Deployment and Localization.

See Also

© 2016 Microsoft