Deploying Office Solutions

Article
02/04/2013

You can deploy Office solutions using ClickOnce or Windows Installer (MSI) deployment technologies. Office solutions use ClickOnce as implemented in the Visual Studio Tools for Office runtime and .NET Framework 3.5. This differs slightly from the functionality available in Windows Forms applications, which only uses functionality in the .NET Framework. ClickOnce is designed to simplify solution deployment and maintenance because ClickOnce solutions install with user privileges.

Applies to: The information in this topic applies to document-level projects and application-level projects for Microsoft Office 2010 and the 2007 Microsoft Office system. For more information, see Features Available by Office Application and Project Type.

If you use Windows Installer to distribute your files, you must still fulfill Visual Studio Tools for Office runtime and ClickOnce security requirements before users can run your Microsoft Office solutions. For more information about the security model for Office solutions, see Securing Office Solutions.

The main advantage to using Windows Installer is deploying the Office solutions to All Users, rather than the current user only. For more information about deploying Office solutions with Windows Installer, see Publishing an Office Solution by Using Windows Installer.

For general information about ClickOnce, see ClickOnce Security and Deployment.

The deployment process involves the following considerations:

Office solution requirements.
Deploying an Office solution.
Installing an Office solution.
Updating an Office solution.
Deployment During Development.
ClickOnce cache.

Office Solution Requirements

Before your Microsoft Office solutions can run, a few components need to be installed on the computer, such as the .NET Framework 3.5 and the Visual Studio Tools for Office runtime. You can often deploy these components along with your solution. For a list of required components, see Office Solution Prerequisites for Deployment and How to: Install Prerequisites on End User Computers to Run Office Solutions.

In addition, you need to consider how to trust solutions. For information about security, see Securing Office Solutions.

Deploying an Office Solution

When you deploy an Office solution, you can use the Publish Wizard or the Publish property page to configure the following deployment settings:

Version number.
Prerequisites.
Update intervals.

After you configure these deployment settings, Visual Studio publishes the solution files to the publish location.

If you are deploying by using a CD or removable drive, leave the Install Location blank and set Updates to Never. For more information, see How to: Publish an Office Solution by Using ClickOnce and Publishing Office Solutions by Using ClickOnce.

Installing an Office Solution

After the solution is copied to the installation location, end users can download and install it. You can install solutions in several different ways: by running the Setup program, by opening the deployment manifest (.vsto file), or by opening the document. For more information, see How to: Install a ClickOnce Office Solution and How to: Uninstall a ClickOnce Office Solution.

If your users will install the solution by opening the deployment manifest, you might have to configure the IIS server to recognize the .vsto MIME type. For more information, see How to: Prepare IIS for Deployment of Office Solutions.

Advanced Deployment

If you want to create a custom Setup program for your Office solution, you can run the Office solution installer (VSTOInstaller.exe) directly. For more information, see Customizing Office Solution Installation.

Alternatively, you can deploy your document-level and application-level projects in a single package, and the combined solutions can be installed and uninstalled as a group. For example, if your Contoso Software Company develops an Outlook add-in and an Excel worksheet, you can install and uninstall these together as Contoso Office Solutions through the Add/Remove Programs in Windows XP or Programs and Features in Windows Vista. For more information, see Walkthrough: Deploying Multiple Office Solutions in a Single ClickOnce Installer for the .NET Framework 4.

If you need to perform additional actions after the installation, you can customize your installation in a process called a post-deployment action. For example, you can copy documents or workbooks to the end-user computer, create extra registry keys, or modify a configuration file. For more information, see Walkthrough: Copying a Document to the End User Computer after a ClickOnce Installation.

Updating an Office Solution

You can configure a solution to check for updates at specified intervals, and install updates automatically. The default setting for automatic updates is every seven days. After this interval is set and the solution is installed, the interval cannot be changed without installing an update. If your users want to force an update outside of the regular update intervals, the Office solution can be updated manually.

You can deploy updates by using the Publish Wizard. The Publish Wizard generates a new application manifest and copies the solution files to the same publish location as the earlier version. Updates are optional and users can cancel any solution update during the download stage and still run the add-in.

The publish action also updates the deployment manifest to point to the location of the new version of the solution. When the end user's installed solution checks for updates at the specified interval, it will download and install the most recently deployed version. You can update versions of a solution by updating the manifests and solution files at the deployment location. For more information, see How to: Update Deployed Office Solutions.

To roll back to a previous version of a Office solution, see How to: Roll Back a ClickOnce Office Solution to an Earlier Version.

For situations where the publish location has changed, the path can be changed in the Setup program without going back to Visual Studio to use the Publish Wizard or Publish page of the Project Designer. For more information, see How to: Change the Installation Path of an Office Solution.

You can manually edit application and deployment manifests in Office solutions. Application and deployment manifests must be re-signed after they are edited by using the Manifest Generation and Editing Tool (mage.exe). For more information, see How to: Change Deployment Properties.

Deployment During Development

If you test your application-level add-in by publishing and installing the solution on your development computer, uninstall the solution before re-publishing or making more code changes and re-testing by pressing F5. When you install a published solution, the assembly for the add-in is installed into the ClickOnce cache. The Setup program also creates registry keys so the Office application can find and load the assembly. Because rebuilding the solution updates the registry keys, it is necessary to uninstall the first version before publishing or running the second version.

In order to test your deployment on your development computer, create another user account to install and test the application-level add-in.

If you develop multiple Office solutions, all of the Office add-ins run because a build is considered an installation. We recommend that you run the Clean Solution command on the Build menu before closing a solution.

ClickOnce Cache

ClickOnce Office solutions are installed into the ClickOnce application cache or the global assembly cache (GAC). The ClickOnce cache is a family of hidden directories that holds all of the solution's files, including the assemblies, configuration files, application and user settings, and data directories. ClickOnce Office solutions use the same cache as Windows Forms ClickOnce applications. Links to other Internet or network locations can be opened while working from the ClickOnce cache, and the cached solution can also function in an offline mode. For document-level customizations, the document is not installed into the ClickOnce cache, and can be located on a user's computer or a network file share. For more information about the ClickOnce cache, see ClickOnce Cache Overview.

You can also store assemblies in the GAC. If your Office solutions have a post-deployment action (PDA) to perform after each installation, you can store the PDA in the GAC. For example, post-deployment actions that must be run after each Visio template is installed can be stored in the GAC.

Data Migration When Updating Solutions

Office solutions migrate local cached data from one version to the next during an update.

If you are running an instance of a previous version of a solution during an update, any changes you make to cached data in the instance that is running during the update will not be migrated forward. To ensure that the data is migrated correctly, close all instances of a solution before updating it.

Data Files

Files with .xml, .mdb, and .mdf extensions are automatically copied to the application data directory. You cannot configure these data files by using the Application Files dialog box. To locate the data directory, use the DataDirectory property. For more information, see Accessing Local and Remote Data in ClickOnce Applications.

To locate your files in a different directory through reflection, call the GetExecutingAssembly method, and then use the CodeBase or EscapedCodeBase properties to get the directory path. Then, you can use the fully qualified path to locate your files.