Deploying Application-Level Add-Ins (2003 System)

  • Article

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

  • Microsoft Office 2003

For more information, see Features Available by Application and Project Type.

Deploying a Microsoft Office 2003 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).

When you deploy your solution, consider the following basic guidelines:

To deploy the add-in, perform these steps:

  • Copy the application manifest that is generated by the build process and the required registry entries to each client computer.

  • Copy the add-in assemblies (and optionally the deployment 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 (2003 System) and How to: Deploy Office Solutions (2003 System).

Note

There is no deployment option that enables end users to use the COM Add-Ins dialog box in Microsoft Office 2003 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 Windows Installer (.msi) file. The installer copies the solution files to the client computer and creates the registry entries that are required to run the add-in. For more information about the Setup project, see Setup Projects for Application-Level Add-ins (2003 System). For more information about the required registry entries, see Registry Entries for Application-Level Add-Ins.

Limitations of the Setup Project

The default Setup project has several limitations:

  • By default, the Setup project does not set the security policy. The add-in assembly and any referenced assemblies must be granted full trust for the add-in to run. You can add a step to the Setup project to configure the security policy, or an administrator can set the appropriate security policy. For more information, see Security Requirements to Run Office Solutions (2003 System).

  • By default, the Setup project does not check for, or install, the Visual Studio Tools for Office runtime and the primary interop assembly (PIA) for the Microsoft Office application. If these components are not installed on the end user computer, the add-in will not run. For more information about the prerequisites, see How to: Prepare End User Computers to Run Office Solutions (2003 System).

Using the Publish Wizard

If you want to enable automatic assembly updates, you can use the Publish Wizard. The Publish Wizard creates a deployment manifest for the solution and copies all the required files to the deployment location.

The Publish command on the project's shortcut menu in Solution Explorer starts the Publish Wizard. You identify 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 option Automatically increment revision with each release is selected in the Publish pane of the Project Designer, a new subfolder is created every time that you publish the solution. Older versions remain available. The application and deployment manifests ensure 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 (2003 System), and Publish Page, Project Designer (2007 System).

Limitations of the Publish Wizard

The Publish Wizard has several limitations:

  • The Publish Wizard does not create the registry entries that are 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 required registry entries, see Registry Entries for Application-Level Add-Ins.

  • The Publish Wizard does not grant full trust to the add-in assembly in the security policy of the end user. The add-in assembly and any referenced assemblies must be granted full trust for the add-in to run. For more information, see Security Requirements to Run Office Solutions (2003 System).

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 following file and subfolder:

  • The deployment manifest (OutlookAddin1.application).

    C:\DeployFolder\OutlookAddin1_1.0.0.0

    This folder contains the following files:

    • 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 following file and subfolders:

  • 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 following files:

    • The original assemblies.

    • The original application manifest.

    • The original deployment manifest.

    C:\DeployFolder\OutlookAddin1_1.0.0.1

    This folder contains the following files:

    • The updated assemblies.

    • The updated application manifest.

    • A copy of the updated deployment manifest.

This structure will be repeated every time that you update the add-in assembly.

Using MSBuild from the Command Line

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

    - or -

  • The user runs the Microsoft Office application with administrator permissions.

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 that 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 permissions cannot overwrite files in certain folders, including %ProgramFiles%. Therefore, if the application manifest is installed to a folder that requires administrator permissions, 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 permissions if the application manifest is installed to a folder that does not require administrator permissions, such as %UserProfile%.

Note

By default, the Setup project that is created with add-in projects installs the application manifest to %CommonProgramFiles%.

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:

See Also

Concepts

Deploying Office Solutions (2003 System)

Setup Projects for Application-Level Add-ins (2003 System)

Setup and Deployment Projects

Reference

Registry Entries for Application-Level Add-Ins