Deploying Visual Studio 2005 Tools for Office Solutions Using Windows Installer (Part 1 of 2)

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Darryn Lavery, Microsoft Corporation

Lubo Birov, Microsoft Corporation

McLean Schofield, Microsoft Corporation

December 2005

Applies to: Microsoft Visual Studio 2005, Microsoft Visual Studio 2005 Tools for the Microsoft Office System, Microsoft Office Excel 2003, Microsoft Office Outlook 2003, Microsoft Office Word 2003

Summary: Learn how to deploy a Microsoft Visual Studio 2005 Tools for the Microsoft Office System solution using a Visual Studio 2005 Setup project to create a Windows Installer package. (26 printed pages)

Download OfficeVSTOWindowsInstaller.msi.

Contents

  • Scenario Overview

  • Deploying Visual Studio 2005 Tools for Office Solutions

  • Deployment Methods for Visual Studio Tools for Office

  • Using Windows Installer to Deploy a Visual Studio 2005 Tools for Office Solution

  • Known Issues Deploying Visual Studio 2005 Tools for Office Solutions

  • Product Codes and Component IDs

  • Office 2003 Primary Interop Assemblies Component IDs

  • Customizing the Primary Interop Assemblies Bootstrapper

  • Conclusion

  • Additional Resources

Scenario Overview

This article targets developers who want to deploy a Microsoft Visual Studio 2005 Tools for the Microsoft Office System solution using a Microsoft Visual Studio 2005 Setup project to create a Windows Installer package.

The article provides the following discussions of Visual Studio 2005 Tools for Office deployment:

  • An overview of the main steps required to deploy a Visual Studio 2005 Tools for Office solution.

An overview of how to deploy a Visual Studio 2005 Tools for Office solution using the Visual Studio Setup project including how you can add the Visual Studio 2005 Tools for Office Runtime and the Microsoft Office 2003 primary interop assemblies prerequisites to your setup packages. This is a somewhat more challenging task that is often necessary. In addition, the steps for granting security trust to a solution receive special attention. The Windows Installer that accompanies this article contains the sample files used throughout the article.

  • A list of known issues when deploying a Visual Studio Tools for Office solution with Windows Installer.

Although this article is focused on deploying Visual Studio 2005 Tools for Office solutions using Windows Installer, this section provides some general background information on how to deploy a Visual Studio 2005 Tools for Office solution, before describing how to deploy using Windows Installer. The article also explains the advantages of that method.

A second article, Deploying Visual Studio 2005 Tools for Office Solutions Using Windows Installer: Walkthroughs (Part 2 of 2), provides two walkthroughs. The first walkthrough provides end-to-end steps to create a Windows Installer package for a Microsoft Office Excel 2003 or Microsoft Office Word 2003 solution. The second shows you how to enhance a Microsoft Office Outlook 2003 add-in to include installing the prerequisites and granting trust to the customization assembly.

Deploying Visual Studio 2005 Tools for Office Solutions

You can deploy Visual Studio 2005 Tools for Office solutions in a number of ways. For example, you can use the Publish Wizard and a Windows Installer package. In each case, you must follow the same general process:

  • Decide on a deployment model.

  • Install the prerequisites on each user's computer.

  • Prepare the solution to deploy.

  • Copy the files to the deployment location.

  • Create required registry entries (Outlook add-ins only).

  • Grant trust to the solution's assemblies.

For more information on deploying solutions, see Deploying Office Solutions in Visual Studio 2005 Tools for the Microsoft Office System online Help.

Decide on a Deployment Model

For Excel and Word solutions, you can choose whether to deploy the solution to the local hard disk, a Web server, a network file share, or even use a hybrid approach. The hybrid approach allows you to deploy the document onto a desktop computer and place the customization assembly in a network accessible location. For an Outlook solution, you can decide whether to store the customization assembly on the local hard disk or in a network accessible location.

Each deployment model provides different advantages for specific scenarios. For example, if offline availability and ease of updating the customization assembly are high priorities, there is a deployment model that best suits this scenario. For more information, see Deployment Models.

Install the Prerequisites on Each User's Computer

To run Visual Studio 2005 Tools for Office solutions, you must install the following software on the each user's computer:

  • The Microsoft .NET Framework version 2.0.

  • A version of Word 2003, Excel 2003, or Outlook 2003 that supports Visual Studio 2005 Tools for Office.

    Which product you install depends on the solution you want to create.

  • Microsoft Office 2003 primary interop assemblies.

    The primary interop assemblies must be installed or marked as Install on first use during installation.

    Microsoft Office only installs the primary interop assemblies if the .NET Framework 1.1 or later is installed. A typical installation of Microsoft Office Editions or a stand-alone product such as Word, installs the primary interop assemblies on first use of the product. A full installation installs the primary interop assemblies during the installation process. After you install the product, you can manually install the primary interop assemblies by using Add or Remove Programs in Control Panel. However, this might require access to the Office installation media.

    If you do not know whether the primary interop assemblies are installed on a specified computer, install the primary interop assemblies anew. Microsoft Office provides a downloadable, redistributable package of the primary interop assemblies that does not require access to the Microsoft Office installation media.

  • Visual Studio 2005 Tools for Office Runtime

  • Microsoft Visual Studio 2005 Tools for the Microsoft Office System (VSTO2005) Language Package (optional)

    Install the language pack if any users run your solution with non–English settings for Microsoft Windows. If you do not install the language pack, your solution runs, but Visual Studio 2005 Tools for Office Runtime error and warning messages appear in English.

Important

Users require administrative rights to install these prerequisites. If they do not have those rights, you must find another method of deployment, for example, group policy or system management software (SMS).

For more information, see How to: Prepare End User Computers to Run Office Solutions.

For more information about these prerequisites, see Additional Resources.

Prepare the Solution to Deploy

Visual Studio 2005 Tools for Office document solutions for Excel and Word require slightly different preparation than for Outlook add-ins. Visual Studio 2005 Tools for Office Excel and Word documents contain an embedded application manifest. This manifest contains a reference to the customization assembly. To make solution updates easier, the embedded application manifest can additionally refer to a deployment manifest file that in turn refers to an external application manifest. Each time the document loads, the Visual Studio 2005 Tools for Office Runtime checks the manifest file to determine whether the customization assembly is current by comparing the version numbers of the manifests. If the version changed, Visual Studio 2005 Tools for Office replaces the embedded application manifest with the newer external application manifest. This updates the solution to use the latest customization assembly. The Publish Wizard automatically creates these files for you and supports these update scenarios.

In certain scenarios, you might have to edit the embedded application manifest manually or programmatically as well as the deployment manifest and external application manifest files for the final deployment location. For more information, see How to: Change the Location of Word and Excel Solutions.

Although an Outlook add-in has an application manifest, its location is stored in the registry. This application manifest also refers to the customization assembly, and to an optional deployment manifest that you can use to support update scenarios. For more information, see How to: Change the Location of Outlook Solutions.

Copy the Files to the Deployment Location

You can copy the files manually or as part of a process, such in as the Publish Wizard or the Visual Studio Setup project.

Create the Required Registry Entries (Outlook Add-ins Only)

Outlook add-ins created with Visual Studio 2005 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. The registry entries are necessary or all Outlook add-ins whether the architecture that guided their creation was Microsoft Visual Basic for Applications (VBA), unmanaged Visual C++, or managed code and the .NET Framework. Outlook looks in the registry at startup to know which add-ins are available. The registry entries contain other information that Outlook needs to load the add-ins properly.

For more information, see Deploying Outlook Solutions.

Grant Trust to the Solution's Assemblies

Finally, you must grant trust to the assemblies for the solution so that the .NET Framework allows them to execute. You must grant the customization assembly FullTrust permissions. In addition, you must trust any referenced or satellite assemblies with the appropriate level of permissions. Evidence for the trust can consist of an assembly's location, a strong name, a certificate, or a combination of these types of evidence.

If an Excel or Word Visual Studio 2005 Tools for Office document is opened in a location other than on the local hard disk, for example, on a Web server, you must also grant the document FullTrust permissions to execute. Use the location of the document for the evidence.

Note

When you use the Visual Studio 2005 Tools for Office to build your solution, Visual Studio grants appropriate trust to the customization assembly and to any other referenced assemblies using the build location as the evidence. However, if you copy the solution to another location on the hard disk or publish the solution, you must explicitly grant security permissions to the copied or published assemblies.

For more information, see Security in Office Solutions.

Deployment Methods for Visual Studio Tools for Office

Visual Studio provides two methods for deploying a Visual Studio 2005 Tools for Office solution:

  • The Publish Wizard

    The Publish Wizard enables you to deploy Word, Excel, and Outlook solutions to a Web site, network file share, or your local computer. It automatically creates an application manifest and a deployment manifest for the solution during the first deployment, and updates existing manifests on subsequent deployments.

    The Publish Wizard assumes that these prerequisites are installed on each user's computer: the .NET Framework 2.0, Visual Studio 2005 Tools for Office Runtime, and the Office 2003 primary interop assemblies.

    After you deploy the solution, you must grant trust so that each user can run the solution. For more information, see Security Requirements to Run Office Solutions.

    For Outlook solutions, 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 manually create these registry entries yourself, for example, by using a registry (.reg) file.

    For more information see Deploying Outlook Solutions.

  • The Visual Studio Setup project

    The Visual Studio Setup project allows you to create a Windows Installer package (.msi file) to deploy the Visual Studio 2005 Tools for Office solution. In addition, it creates a Setup.exe file that detects and installs the prerequisites, for example, the .NET Framework 2.0. You can use the Setup project as a complement to the Publish Wizard. You can publish the Visual Studio 2005 Tools for Office solution to a Web share, and you can use a Setup project to install the prerequisites and grant security trust to the solution.

    By default, when you create an Outlook add-in, Visual Studio 2005 Tools for Office automatically creates a Setup project for your solution.

    For more information, see Windows Installer Deployment.

Visual Studio Setup projects are ideal when you want to provide customers who are not familiar with Visual Studio 2005 Tools for Office an easy way to install your Visual Studio 2005 Tools for Office solution on their desktop computers.

However, there are some specific requirements for Visual Studio 2005 Tools for Office that are not currently supported by the Visual Studio Setup project. The most important requirements in this category are those that pertain to installing prerequisites, such as the Visual Studio 2005 Tools for Office Runtime, and granting security trust to the solution. This article addresses these areas.

Using Windows Installer to Deploy a Visual Studio 2005 Tools for Office Solution

This section presents an overview of how to create a Windows Installer package for a Visual Studio 2005 Tools for Office solution using a Visual Studio Setup project. Particular attention is made to those specific requirements for Visual Studio 2005 Tools for Office that are not natively addressed by the Visual Studio Setup project.

A second article, Deploying Visual Studio 2005 Tools for Office Solutions Using Windows Installer: Walkthroughs (Part 2 of 2), provides two walkthroughs. The first walkthrough provides end-to-end steps to create a Windows Installer package for a Microsoft Office Excel 2003 or Microsoft Office Word 2003 solution. The second shows you how to enhance a Microsoft Office Outlook 2003 add-in to include installing the prerequisites and granting trust to the customization assembly.

This section requires the sample files contained in the download that accompanies this article. If you have not already installed those files please do so now. By default, this directory is:

C:\Program Files\Microsoft Visual Studio 2005 Tools for Office Resources\VSTO2005 Windows Installer Sample

For the purposes of this article, this directory is referred to as {SamplesDir}.

Assumptions

The following assumptions are made about the project that you will deploy:

  • There is only one customization assembly; there are no other referenced or satellite assemblies deployed with the solution.

  • Deployment is to a local file folder and not to some other location, such as a Web server or network file share.

  • Your solution requires only the Excel, Outlook, Word and Smart Tag primary interop assemblies.

  • Your solution does not use the optional deployment manifest.

These assumptions help focus the explanations that follow, but we give occasional guidance to address some scenarios that fall outside this narrower focus.

Creating a Windows Installer Package

At a high level, the procedures are as follows:

  1. Create the Visual Studio 2005 Tools for Office solution to deploy.

  2. Add a Visual Studio Setup project to the solution.

  3. Add the Visual Studio 2005 Tools for Office solution files to the Setup project.

  4. Indicate the prerequisites that must be checked and installed by Setup.exe.

    The most notable prerequisites are the .NET Framework and the Visual Studio 2005 Tools for Office Runtime.

  5. Add a custom action to grant trust to the customization assembly.

  6. Set the location of the customization assembly inside the application manifest so that the Excel or Word document can load the customization or so that Outlook can locate and load the add-in customization.

  7. Add launch conditions to the Windows Installer package to check if the prerequisites are installed.

    In addition to executing the Windows Installer by double-clicking Setup.exe, the user may choose to install the solution by double-clicking the .msi file. In this mode, the prerequisites are not installed. However, you can add launch conditions to the .msi file to warn your users to use Setup.exe instead.

    Important

    You must secure the location where the solution is installed using the Setup to prevent tampering with the custom action assemblies, their associated saved install state, and any other related setup files.

Adding a Setup Project and Adding the Files

Adding a Setup project to an existing Visual Studio 2005 Tools for Office solution is a matter of right-clicking your solution in Solution Explorer and adding a new project. After the Add New Project dialog box appears, select Other Project Types, and then select Setup and Deployment (Figure 1).

Figure 1. Creating a Setup project

After you add the Setup project to your solution, you can add your Visual Studio 2005 Tools for Office solution files by using the File System Editor (Figure 2).

Figure 2. Adding the installation files

Detecting and Installing Prerequisites

When the user runs Setup by double-clicking the Setup.exe file produced by the Visual Studio Setup project, the Windows Installer examines the list of prerequisites required by the application and installs the software, if necessary. This process is often called "bootstrapping" and this article often uses the term bootstrapper instead of Setup.exe. After the prerequisites are installed, the Windows Installer package is processed, which performs the actual installation of the application.

As the Setup author, you can determine the prerequisites. You can also determine whether they are downloaded from the Web, included with the Windows Installer, or downloaded from a pre-determined location, such as a network file share (Figure 3). These controls are available in the Prerequisites dialog box, which is available in the Project Properties dialog box for the Setup project

Figure 3. Choosing which prerequisites to install

As noted earlier, a Visual Studio 2005 Tools for Office solution requires the .NET Framework 2.0, the Visual Studio 2005 Tools for Office Runtime, and Office 2003 primary interop assemblies. By default, you can add only the .NET Framework 2.0 package as a prerequisite. However, the Prerequisites dialog box is extensible and can include user-provided prerequisite packages. The dialog box is populated by processing a special directory listing the available prerequisite packages. Each package has its own folder in that directory. For more information, see Use the Visual Studio 2005 Bootstrapper to Kick-Start Your Installation.

By default, in Visual Studio 2005 Tools for Office, the directory describing the prerequisite packages is the following:

C:\Program Files\Microsoft.NET\SDK\v2.0\BootStrapper\Packages

In Microsoft Visual Studio 2005 Team System, the directory is the following:

C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\BootStrapper\Packages

Tip

If in doubt, you can determine the location by appending \bootstrapper\packages to the value of this registry key: \HKLM\SOFTWARE\Microsoft.NETFramework\sdkInstallRootv2.0

Each package folder consists of a number of files, including the redistributable package itself, configuration files that describe the package, and an optional executable file to check for the package at installation time.

There are configuration files that describe the installation behavior of the package. The first configuration file, product.xml, describes:

  • How to detect whether that package was already installed. This is normally achieved by searching for a registry setting or a product code, or, in some cases, by using a custom executable. A product code is a GUID that uniquely identifies a particular product.

  • How to install that package.

  • Any other packages that this particular package depends upon; for example, the Visual Studio 2005 Tools for Office Runtime, requires that you install the .NET Framework. If that package is not installed, Setup.exe installs it on behalf of the user.

The second configuration file, package.xml, contains language-specific information about the package, for example, error messages to display when a package cannot install. For each supported language, there is a subfolder, such as EN, that contains the language-specific version of package.xml in addition to other files, such as the end-user license agreement (EULA).

Sample configuration files for the Visual Studio 2005 Tools for Office prerequisites are included with the sample and are listed in Table 1.

Table 1. Summary of bootstrapper packages accompanying the article

Bootstrapper package

Dependent packages

Other conditions

Office 2003 primary interop assemblies redistributable package

.NET Framework 2.0

Fail, if versions of Excel, Outlook and Word that are supported by Visual Studio 2005 Tools for Office are not installed.

Install, if any of the following primary interop assemblies are not installed: Excel 2003, Outlook 2003, Word 2003 or Smart Tag.

Visual Studio 2005 Tools for Office Runtime

The .NET Framework 2.0

Office 2003 primary interop assemblies redistributable package

 

Visual Studio 2005 Tools for Office Language Pack

Visual Studio 2005 Tools for Office Runtime

 

The bootstrapper packages are as follows:

  • Office 2003 primary interop assemblies redistributable package

    The primary interop assemblies' redistributable package is a downloadable Windows Installer file that allows ISVs and IT organizations to install the Office primary interop assemblies without requiring the Office installation media. The Office primary interop assemblies redistributable package only installs if the .NET Framework 1.1 or above and Office 2003 or a stand-alone product are installed. During installation the package installs all of the Office primary interop assemblies for the Office applications that are currently installed.

    Note

    The package does not install the Smart Tag primary interop assemblies if only the Outlook 2003 standalone product is installed.

    For the purposes of this article, .NET Framework 2.0 is identified as a dependency. Thus, when the Office 2003 primary interop assemblies' redistributable package is included, the .NET Framework 2.0 is checked for and installed, if required.

    Two other custom conditions are also added. First, the Office 2003 primary interop assemblies' redistributable package does not install if Office or a stand-alone application is not installed. For this article, the redistributable package is not installed if a version of Excel, Outlook and Word that are compatible with Visual Studio 2005 Tools for Office is not detected.

    You must write the check for an Office application in native code (Visual C++). Each language version of Office 2003 has a different product code. To detect if a supported Office 2003 product is installed, you can use a simple custom executable file. The AppCheck.cpp included in the code accompanying this article demonstrates how to check whether a supported version of Excel, Outlook, or Word is installed on the user's computer. The code enumerates all installed products that include the component containing Excel.exe (for Excel), Outlook.exe (for Outlook), or WinWord.exe (for Word). The product code of each installed Office 2003 product is checked to see whether it is a product supported by Visual Studio 2005 Tools for Office. The product code is checked by ignoring the part of the code that indicates the exact language version. Because you cannot guarantee that the .NET Framework is present during the bootstrapping process, you must write this check in Visual C++.

    Tip

    By default, the bootstrapper checks for the presence of Excel, Outlook and Word. Instructions to limit this check to just one application, such as Word, are supplied in Additional Resources.

    Second, the primary interop assemblies' redistributable package must be run if either of the Excel, Outlook, Word, or Smart Tag primary interop assemblies are not installed. To detect if the required primary interop assemblies are installed, you can use another simple custom executable. The PIACheck.cpp sample included in the code accompanying this article demonstrates how to check whether the required primary interop assemblies are installed on the user's computer.

    Tip

    Instructions to add or remove primary interop assemblies to the check are supplied in Additional Resources.

    Important

    The AppCheck.cpp and primary PIACheck.cpp samples are designed only to detect Office 2003. The samples do not support future versions of Office.

  • Visual Studio 2005 Tools for Office Runtime (vstor.exe)

    The Visual Studio 2005 Tools for Office Runtime is configured to depend upon the .NET Framework 2.0 and the Office primary interop assemblies' redistributable package. The Visual Studio 2005 Tools for Office Runtime does not install until both of these dependencies are installed.

  • Visual Studio 2005 Tools for Office Language Pack

    The Visual Studio 2005 Tools for Office Language Pack depends upon the Visual Studio 2005 Tools for Office Runtime and does not install until the Visual Studio 2005 Tools for Office Runtime is installed. In turn, the Visual Studio 2005 Tools for Office Runtime does not install until .NET Framework 2.0 and the Office primary interop assemblies are installed.

Adding the Visual Studio 2005 Tools for Office Packages to the Bootstrapper

The following instructions describe how to add the packages listed above to the bootstrapper package directory. These changes need only be made once and only on the development computer.

For this task, you must have the files that are available in the Windows Installer that accompanies this article. You must prepare the files before you copy them into the bootstrapper package directory.

Preparing the Office Application and Office Primary Interop Assemblies Checks

You must compile the Office application and primary interop assembly checker program samples.

Important

If you are using Visual Studio 2005 Tools for Office, you must ensure that both the .NET Framework 2.0 software development kit (SDK) and the Windows Platform SDK are installed.

Note

By default, Visual Studio 2005 Tools for Office does not install the .NET Framework 2.0 SDK. You can download it or install it from the installation media, for example, using the Add or Remove Programs command in Visual Studio 2005 Tools for Office. You can download a copy of the Windows Server 2003 SP1 Platform SDK Web Install from the Microsoft Download Center. You can also download a copy of the .NET Framework 2.0 Software Development Kit (SDK) (x86) from the Microsoft Download Center.

Note

These downloads are not required, if you are using Microsoft Visual Studio Team System.

To prepare the Office application and primary interop assemblies checks

  1. To run the Visual Studio 2005 command prompt, click Start, click Programs, click Microsoft Visual Studio 2005, and then click Visual Studio Tools.

  2. In the command prompt, change the directory to {SamplesDir}\projects\Checks

    Tip

    By default, the SamplesDir directory is C:\Program Files\Microsoft Visual Studio 2005 Tools for Office Resources\VSTO2005 Windows Installer Sample.

  3. Compile the application checker by typing the following command, depending on which version of Visual Studio you are using.

    If you are using the Visual Studio Team System, use this command:

    cl.exe /Oxs /MT /GS AppCheck.cpp

    If you are using Visual Studio 2005 Tools for Office, use this command:

    cl.exe -I "C:\Program Files\Microsoft Platform SDK\Include" /Oxs /MT /GS AppCheck.cpp

  4. Compile the primary interop assemblies checker by typing the following command, depending on which version of Visual Studio you are using.

    If you are using the Visual Studio Team System, use this command:

    cl.exe /Oxs /MT /GS PIACheck.cpp advapi32.lib

    If you are using Visual Studio Tools for Office, use this command:

    cl.exe -I "C:\Program Files\Microsoft Platform SDK\Include" /Oxs /MT /GS PIACheck.cpp "C:\Program Files\Microsoft Platform SDK\Lib\advapi32.lib"

  5. Close the command prompt.

  6. Using Windows Explorer, copy the executable file PIACheck.exe into {SamplesDir}\packages\Office2003PIA.

To prepare the Office 2003 primary interop assemblies bootstrapper package

You must include the Office 2003 primary interop assemblies in the corresponding bootstrapper package.

  1. Download the Office 2003 Update: Redistributable Primary Interop Assemblies from the Microsoft Download Center.

  2. Run the primary interop assembly installer.

  3. Accept the EULA that gives you the right to package the primary interop assemblies as part of your installer.

  4. In Windows Explorer, open the folder to which the Office 2003 primary interop assemblies' installer extracted the files.

  5. Copy O2003PIA.msi into the directory {SamplesDir}\packages\Office2003PIA.

    Note

    As the Setup author, you can determine the prerequisites, and can specify whether to download them from the Web, to include them with the Windows Installer, or to download them from a predetermined location such as a network file share. Because you cannot directly download the primary interop assemblies' redistributable package, you must always include it with your Windows Installer. If you set the prerequisite installation location to the Web, you are warned that this particular package must be included when you build the Setup project, as shown here: WARNING: No 'HomeSite' attribute has been provided for 'Microsoft Office 2003 Primary Interop Assemblies', so the package will be published to the same location as the bootstrapper.

To prepare the Visual Studio 2005 Tools for Office Runtime bootstrapper package

  1. Download the Microsoft Visual Studio 2005 Tools for Office 2005 Runtime (VSTO 2005 RTM) from the Microsoft Download Center.

  2. Copy vstor.exe into the directory {SamplesDir}\packages\VSTORuntime.

Preparing the Visual Studio Tools for Office Language Pack Bootstrapper Package

If any users run your solutions with non–English settings for Windows, they must have the Visual Studio 2005 Tools for Office Language Pack to see runtime messages in the same language as Windows.

To prepare the Visual Studio 2005 Tools for Office Language Pack

  1. Download the Microsoft Visual Studio 2005 Tools for the Microsoft Office System (VSTO2005) Language Package from the Microsoft Download Center.

  2. Copy the file vstolp20.exe into the directory {SamplesDir}\packages\VSTOLP.

As noted earlier, the setup author you can determine the prerequisites. You can also determine whether to download them from the Web, include them with the Windows Installer, or download them from a predetermined location, such as a network file share (Figure 3). The bootstrapper package for the Visual Studio 2005 Tools for Office Runtime was preconfigured to support downloading the package from the web. Because the Visual Studio 2005 Tools for Office Language Pack was not available at the time of writing, you must configure its bootstrapper to support downloading from the Web. You must:

  • Edit the product.xml file to add the HomeSite and PublicKey attributes to the PackageFile element.

    You can copy the PublicKey that is used in the Visual studio 2005 Tools for Office Runtime bootstrapper.

  • Edit the package.xml file to indicate the Web location of the executable for the Visual Studio 2005 Tools for Office Language Pack, which is:

    http://go.microsoft.com/fwlink/?LinkId=56603

    For an example, consult the product.xml and package.xml files of the Visual Studio 2005 Tools for Office Runtime bootstrapper.

Copying the Packages into the Bootstrapper Directory

Now that you have prepared the prerequisites, copy them into the bootstrapper package directory.

To copy the packages into the bootstrapper

  1. Determine where your bootstrapper package directory is located.

    In Visual Studio 2005 Tools for Office, the default directory is here:

    C:\Program Files\Microsoft.NET\SDK\v2.0\BootStrapper\Packages\

    In Visual Studio Team System, the default directory is here:

    C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\BootStrapper\Packages

    Tip

    If in doubt, you can determine the location by appending \bootstrapper\packages to the value of this registry key: \HKLM\SOFTWARE\Microsoft.NETFramework\sdkInstallRootv2.0

  2. Copy the contents of the directory {SamplesDir}\packages into the bootstrapper directory.

Granting Trust to the Customization Assembly

The Visual Studio 2005 Tools for Office Runtime requires the customization assembly to have FullTrust permissions to execute. In addition, you must also trust any referenced or satellite assemblies deployed with the application with the appropriate level of permissions. Further, if you deploy the document to a location other than the user's local hard disk, you must grant the document FullTrust permission. For more information, see Security in Office Solutions.

Pay attention to the type of evidence that is used to trust the solution. You should not rely solely on location-based evidence, but should combine it with a strong name, a digital certificate, or both.

In a Visual Studio Setup project, you can grant security by adding a custom action. Custom actions are a Windows Installer feature that allows you to run code at the end of an installation to perform actions that the Windows Installer does not provide. You implement a custom action by creating a class derived from the Installer class and overriding the Install, Uninstall, Commit and Rollback methods as appropriate.

Included with this article is a sample Microsoft Visual C# 2005 custom action (SetSecurity) to grant trust using both the folder location of the installed assembly and its strong name as evidence. The custom action sample assumes that there is only one main customization assembly and that you plan to deploy the entire solution to a local hard disk.

This custom action overrides three of the Windows Installer class methods: Install, Rollback, and Uninstall.

  • On installation, it sets the security policy. On rollback and on uninstall, it removes the security policy changes. A list of the parameters required by the Install method is shown in Table 2.

  • The Uninstall and Rollback methods require only one parameter: the name of the code group (solutionCodeGroupName). On invocation, the methods remove the specified code group. To prevent removing a different code group with the same name, be sure that the code group name is unique.

  • The Commit method requires no parameters and the default implementation provided in the base class is used.

Table 2. Parameters for the Install method of the security custom action

Parameter

Description

assemblyName

The name of your main customization assembly, for example, ExcelApplication.dll.

targetDir

The installation location of your assembly. The installation macro [TARGETDIR]\ defined at installation time from the Windows Installer suffices.

solutionCodeGroupName

This is the security code group name for your Visual Studio 2005 Tools for Office application. This name must be unique. A good format for the name is CompanyName.SolutionName.GUID.

The permissions for this code group are Nothing at the installation folder for your Visual Studio 2005 Tools for Office solution.

solutionCodeGroupDescription

A description of your Solution Code group name.

assemblyCodeGroupName

Code group name for the assembly. Full trust is granted to this code group using the strong name of the assembly as evidence.

assemblyCodeGroupDescription

A description of your assembly code group name.

allUsers

This parameter determines whether the policy is created at the machine level (value = "1") or user level (value = ""). You can use the [ALLUSERS] installation macro defined at install time from the Windows Installer.

To grant trust, the custom action creates two new code groups. It creates the first code group, Solution Code, using the install folder location as evidence and sets the permissions to Nothing. The Solution Code group name must be unique, because if a user removes or rolls back the Solution the sample custom action removes that code group. To ensure uniqueness, you could use a combination of your company name, the solution name, and a GUID.

The second code group, Assembly Code, is a child of the Solution Code group. The custom action grants full trust to this code group using the strong name of the assembly as evidence. Two code groups are implemented to ensure that the customization assembly is trusted by both its location and its strong name.

You can grant security rights at the user level, machine level, or enterprise level. This custom action sample supports a parameter that allows you to choose whether to change policy at the user or machine level. The parameter does not support the Enterprise policy because it requires enterprise administrative rights. In practice, you may pass the [ALLUSERS] installation macro to this parameter. This value determines whether the installed solution is available for just the user who installed the solution or for all users.

If you are installing for all users, you should use the machine policy; otherwise, use the user policy. Note, however, that setting security at the machine level requires that the users installing the solution have administrative access, which is also required if they need to install the prerequisites. When updating the user-level policy, the Solution Code group is added as a child of the All_Code root code group. When updating the machine-level policy, the Solution Code group is added as a child of the My_Computer_Zone code group.

The custom action sample demonstrates updating the security policy when you deploy the solution to a local file folder. For considerations when deploying solutions to shared locations see How to: Grant Permissions to Documents and Workbooks in Shared Locations.

Furthermore, the custom action demonstrates changing security policy for one primary customization assembly. If your solution has other referenced or satellite DLLs, you must create an additional assembly code group with the appropriate level of permissions.

Updating the Location of the Customization Assembly in the Application Manifest

Visual Studio 2005 Tools for Office Word and Excel documents and Outlook add-ins store the location of the customization assembly and optional deployment manifest in the application manifest.

Excel and Word Document Solutions

Excel and Word Visual Studio 2005 Tools for Office solutions have an embedded application manifest that, among other things, stores the location of the document's customization assembly and optionally its deployment manifest location. When you deploy an Excel or Word solution to a user-controlled installation location, you may need to edit the embedded application manifest to update the location of the customization assembly. If you are including the optional deployment manifest and external application manifest, you may need to edit these manifest files to account for the final installation location.

This article assumes that you are not deploying the optional deployment manifest, so only the embedded application manifest requires editing. You can edit the embedded application manifest programmatically using either Visual C# or Microsoft Visual Basic 2005 using the Visual Studio 2005 Tools for Office ServerDocument object. For more information, see How to: Update Application Manifest Assembly Paths Programmatically.

Included in this article is a Visual C# custom action sample that updates the location of the document's customization assembly. For information, see the UpdateManifest project inside the projects folder.

The custom action only overrides the Install method of the Installer class, because removing or rolling back the solution removes the document; thus, editing the application manifest is a wasted activity. Table 3 shows parameters for the Install method of the custom action.

A second article, Deploying Visual Studio 2005 Tools for Office Solutions Using Windows Installer: Walkthroughs (Part 2 of 2), provides detailed instructions how to add and call this custom action from within a Setup project.

Table 3. Parameters for the UpdateManifest custom action

Parameter

Description

targetDir

The installation location of your assembly. The installation macro [TARGETDIR]\ suffices.

documentName

The name of the document being deployed, for example, ExcelApplication.doc.

assemblyName

The name of your assembly, for example, ExcelApplication.dll.

When you build an Excel or Word solution, for example by pressing F5, the build process edits the application manifest embedded in the workbook to point to the relative path of the assembly. Thus, if you added the results of the build process to your Setup project, you might not have to modify the embedded application manifest.

If the workbook or document and the assembly remain in the same folder after installation, then you do not have to modify the embedded application manifest. However, if you want to enable the user to move the workbook to a different folder after installation, then you must edit the application manifest to point to the full path of the assembly. This is especially important for Excel or Word template projects, because the workbook or document created from a template typically resides in a location that is different from the location of the template.

Outlook Add-ins

Although the application manifest is inside the Excel or Word document, for Outlook projects the application manifest is installed on disk. For the Visual Studio 2005 Tools for Office Runtime to discover the manifest location, you must specify it in the registry. When you create the Outlook add-in Setup project, the registry entries required to run the add-in are added to the Setup project on your behalf.

Adding Launch Conditions to the Windows Installer File

Instead of installing the solution by double-clicking Setup.exe, the user may choose to install the solution by double-clicking the .msi file. In this mode, the bootstrapper is not executed and thus the dependencies are not detected and installed where appropriate.

However, you can add launch conditions to the .msi file to prevent installation if certain prerequisites are not present. You can base launch conditions upon Windows Installer component ID checks or registry values. For more information, see Launch Condition Management in Deployment. For example, you can add a component ID check for the Visual Studio 2005 Tools for Office Runtime (see below) and display a message if the Runtime does not install. Because components can be shared by many products, try to find a component ID that is unique to that particular product.

Figure 4. A launch condition to search for the Visual Studio 2005 Tools for Office Runtime

For a list of component IDs for the Visual Studio 2005 Tools for Office Runtime, the Visual Studio 2005 Tools for Office Language Pack, and Office primary interop assemblies that you can use as launch conditions, see Additional Resources.

This article does not discuss how to perform a launch condition for your required Office application. Each language version has its own unique product code, so searching for any supported version would require a search for all product codes. Searching for a single component does not work because components are part of different products, and some of them are not supported by Visual Studio Tools for Office (for example, Microsoft Office Standard Edition). An easier way might be to create a custom action to check whether a supported Office version is installed. The AppCheck.cpp file contains sample code for this type of check.

You then must include the custom action in your Windows Installer package by manually editing the package using a database table editor, such as Orca. Orca allows you to create and edit Windows Installer packages and merge modules. It provides a graphical interface for validation, highlighting the particular entries where validation errors or warnings occur. Orca is available from Windows Server 2003 SP1 Platform SDK Web Install. It is important to remember that checking for the presence of the primary interop assemblies is not sufficient because the primary interop assemblies in the Microsoft Office Standard Edition 2003 and the Microsoft Office Professional Edition 2003 have the same component codes.

Known Issues Deploying Visual Studio 2005 Tools for Office Solutions

  • The AppCheck.cpp and PIACheck.cpp samples only detect Office 2003.

    The samples do not support future versions of Office.

  • Currently, Visual Studio setup does not provide bootstrapper support for the 64-bit version of the .NET Framework.

    When you build a Setup project that includes the .NET Framework as a prerequisite, the 32-bit version is used. If you run the Setup package on a 64-bit computer, it fails because the 32-bit version cannot run under Windows on Windows. To workaround this issue, you must install the 64-bit version of the .NET Framework manually before running Setup. Bootstrapper support for the 64-bit version of the .NET Framework is planned to be released in early 2006.

  • The Bootstrapper Package samples do not check whether the Office Toolkit Loader (OtkLoader) requires updating.

    Visual Studio 2005 Tools for Office requires an updated version of the OtkLoader. OtkLoader is included with Office and stand-alone products. As part of the installation process, the Visual Studio 2005 Tools for Office Runtime updates the OtkLoader if Office or an Office stand-alone product is installed. However, it is possible for you to install the Visual Studio 2005 Tools for Office Runtime before Office and thus the required OtkLoader update is not present.

  • The Security Custom Action sample does not support granting trust to a solution installed on a file share.

    The custom action sample demonstrates updating the security policy when the solution is deployed to a local file folder. For considerations when deploying solutions to shared locations, see How to: Grant Permissions to Documents and Workbooks in Shared Locations.

  • The Office primary interop assemblies' redistributable package can only be included with Setup.

    As the Setup author, you can determine the prerequisites. You can also determine whether to download them from the Web, include them with the Windows Installer, or to download them from a pre-set location such as a network file share.

    To obtain the primary interop assemblies redistributable package you must download an installer, accept a EULA, and then copy the redistributable package from the installation folder. There is no way to download directly the primary interop assemblies' redistributable package; it must always be included with your Setup.

    If you set the prerequisite installation location to the Web, you are warned that the primary interop assemblies' redistributable package must be included when you build the Setup project.

    WARNING: No 'HomeSite' attribute has been provided for 'Microsoft Office 2003 Primary Interop Assemblies', 
so the package will be published to the same location as the bootstrapper.

  • The Visual Studio 2005 Tools for Office Language Pack can only be included with Setup.

    Recall that as the setup author, you can determine the prerequisites. You can also determine whether to download them from the Web, include them with the Windows Installer, or download them from a predetermined location such as a network file share (Figure 3). The bootstrapper package for the Visual Studio 2005 Tools for Office Runtime is preconfigured to support downloading the package from the Web. Because the Visual Studio 2005 Tools for Office Language Pack was not available at the time of writing, you must configure its bootstrapper to support downloading from the Web. You must take the following steps:

    • Edit the product.xml file to add the HomeSite and PublicKey attributes to the PackageFile element. You can copy the PublicKey that was used in the Visual Studio 2005 Tools for Office Runtime bootstrapper.

    • Edit the package.xml file to indicate the Web location of the executable for the Visual Studio 2005 Tools for Office Language Pack, which is:

      http://go.microsoft.com/fwlink/?LinkId=56603

    Please consult the product.xml and package.xml files of the Visual Studio 2005 Tools for Office Runtime bootstrapper for an example.

  • Compile errors occur when installing the AppCheck.cpp and PIACheck.cpp source files.

Note

If you are using Visual Studio 2005 Tools for Office, you must ensure that both the .NET Framework 2.0 Software Development Kit (SDK) (x86) and the Windows Server 2003 SP1 Platform SDK Web Install are installed. By default, Visual Studio 2005 Tools for Office does not install the .NET Framework 2.0 SDK. You can download it or install it from the installation media, for example, using the Add or Remove Programs command in Visual Studio 2005 Tools for Office. These downloads are not required if you are using Visual Studio Team System

Product Codes and Component IDs

The product code is a unique identifier for the particular product release, represented as a string GUID, for example "{12345678-1234-1234-1234-123456789012}". This ID varies for different versions and languages. You can use the product codes to test for the presence of a particular product or package in the bootstrapper.

A product consists of many components that may be shared across multiple products. A component ID also takes the form of a GUID. Because product codes are not supported for Windows Installer file launch conditions, you must use another check such as a component ID or registry entry. However, if you are using a component ID to test for the presence of a particular product, try to find a component ID that is unique to that particular product.

Table 4. Product codes and component IDs for the bootstrapped packages

Package

Product Code

Component ID

Visual Studio 2005 Tools for Office Runtime

{388E4B09-3E71-4649-8921-F44A3A2954A7}

{D2AC2FF1-6F93-40D1-8C0F-0E135956A2DA}

Visual Studio 2005 Tools for Office Language Pack

{5DB161C0-7C9C-41D7-8DA1-CB112F60946B}

{2E3A394E-C9BD-40C3-9990-BA7AF7C8B4AF}

Office 2003 primary interop assemblies

{91490409-6000-11D3-8CFE-0150048383C9}

Use component IDs for specific primary interop assemblies listed below.

Office 2003 Primary Interop Assemblies Component IDs

The follow table lists the component IDs for the Office 2003 primary interop assemblies. These values are the same whether the primary interop assemblies are installed as part of Microsoft Office or by the Office primary interop assemblies' redistributable package.

You can use the component IDs if you want to extend the product.xml bootstrapper file for the Office primary interop assemblies, and for launch conditions in the Windows Installer file.

Table 5. Components for the Office 2003 primary interop assemblies

Primary interop assembly

Component ID

Word 2003

{1C8772BD-6E6F-4C9D-8FF8-B5EA072F86EF}

Outlook 2003

{14D3E42A-A318-4D77-9895-A7EE585EFC3B}

Excel 2003

{A1FE0698-609D-400F-BF10-F52238DD6475}

Smart Tag

{53C65973-D89D-4EA0-8567-8788C14E0A02}

Microsoft Graph

{A58B51D1-89BF-4D88-939D-B6D0DB2EEB53}

Microsoft Forms 2.0

{835AC3CE-E36B-4D65-B50F-2863A682ABEE}

Customizing the Primary Interop Assemblies Bootstrapper

This section describes how the primary interop assemblies' bootstrapper works and how it may be customized for your deployment scenarios.

Default Behavior

For the purposes of this article, the bootstrapper for the primary interop assemblies' redistributable package is configured to prevent installation if it cannot find versions of the following applications that are supported by Visual Studio Tools for Office:

  • Excel 2003

  • Outlook 2003

  • Word 2003

Furthermore, the primary interop assemblies' redistributable package is installed if any of the primary interop assemblies are not installed:

  • Excel 2003 primary interop assemblies

  • Outlook 2003 primary interop assemblies

  • Word 2003 primary interop assemblies

  • Smart Tag primary interop assemblies

Product.xml

In the sample product.xml file for the primary interop assemblies bootstrapper package, there are two areas of interest.

The first section enumerates a set of checks that the bootstrapper executes. The result of each check is stored in a property that is later used to determine if the bootstrapped package is installed or not.

By default, separate checks are made for Excel, Word, and Outlook by executing the AppCheck sample file. A single check is made for the primary interop assemblies by executing the PIACheck sample file passing as arguments the component ID keys of the required primary interop assemblies as arguments.

<InstallChecks> 
   <_- External check for Microsoft Office Excel. --> 
   <ExternalCheck 
      Property="SupportedExcelVersionInstalled"
      PackageFile="AppCheck.exe" 
      Arguments="/excel"/>

   <-- External check for Microsoft Office Word. -->
   <ExternalCheck 
      Property="SupportedWordVersionInstalled"
      PackageFile="AppCheck.exe" 
      Arguments="/word"/>

   <_- External check for Microsoft Office Outlook. --> 
   <ExternalCheck 
      Property="SupportedOutlookVersionInstalled"
      PackageFile="AppCheck.exe" 
      Arguments="/outlook"/> 

   <_- External check for primary interop assemblies (PIAs).  -->
   <ExternalCheck 
      Property="PIAsRegistered" 
      PackageFile="PIACheck.exe" 
      Arguments="{A1FE0698-609D-400F-BF10-F52238DD6475} 
  {1C8772BD-6E6F-4C9D-8FF8-B5EA072F86EF} 
  {14D3E42A-A318-4D77-9895-A7EE585EFC3B} 
  {53C65973-D89D-4EA0-8567-8788C14E0A02}"/> 
</InstallChecks>

The InstallConditions element is the second area of interest. Once the install checks have been processed, a number of installation conditions are evaluated to determine if the bootstrapped package requires installation. The sample product.xml tests the following conditions:

  • Fail to install the package if the user is not an administrator. If the package fails to install, the setup does not proceed.

  • Fail to install the package if Excel, Outlook, and Word are not installed.

  • Bypass the installation if the primary interop assemblies are already installed by examining the PIAsRegistered property set during the installation checks.

  • If none of these conditions applies the primary interop assemblies redistributable package is installed.

Display strings for the various conditions are stored in the language-specific package.xml file.

<InstallConditions>
   <FailIf 
      Property="SupportedExcelVersionInstalled"
      Compare="ValueNotEqualTo"
      Value="0"
      String="ExcelRequired"/>
   <FailIf 
      Property="SupportedWordVersionInstalled"
      Compare="ValueNotEqualTo"
      Value="0"
      String="WordRequired"/>
   <FailIf
      Property="SupportedOutlookVersionInstalled"
      Compare="ValueNotEqualTo"
      Value="0"
      String="OutlookRequired"/>
   <BypassIf
      Property="PIAsRegistered"
      Compare="ValueEqualTo"
      Value="0"/>
   <FailIf
      Property="AdminUser"
      Compare="ValueEqualTo"
      Value="false"
      String="AdminRequired"/>
</InstallConditions>

Customizing the Checks

To customize the checks for the Microsoft Office application and Primary Interop Assemblies please following these instructions:

To remove a check for a particular Office application such as Word

  1. Locate the InstallChecks element, and then remove the appropriate ExternalCheck sub-element.

  2. Locate the InstallConditions element, and then remove the appropriate FailIf sub-element.

To change which primary interop assemblies are required

  1. Locate the InstallConditions element, and then locate the InstallChecks sub-element for the primary interop assemblies.

  2. Edit the Arguments attribute to pass only the component IDs of the required primary interop assemblies.

    You can find component IDs for the Office primary interop assemblies in Table 5.

Conclusion

This article provides an overview of deploying a Visual Studio 2005 Tools for Office solution using a Visual Studio Setup project to create a Windows Installer package. Samples have been provided indicating how you may install the required prerequisites (the .NET Framework 2.0, Visual Studio 2005 Tools for Office Runtime, and the Office 2003 primary interop assembiles), grant trust to a customization assembly and update the location of a document's customization assembly. It discusses common deployment methods and then describes the general process of using Windows Installer to deploy a Visual Studio Tools for Office solution. It also provides a list of known issues you may encounter during the process.

For two walkthrough examples of a Windows Installer deployment, see Deploying Visual Studio 2005 Tools for Office Solutions Using Windows Installer: Walkthroughs (Part 2 of 2).

Additional Resources

Code Security

Redistributable Packages