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

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

Darryn Lavery, Microsoft Corporation

Lubo Birov, Microsoft Corporation

McLean Schofield, Microsoft Corporation

Brian A. Randell, MCW Technologies, LLC

Published March 2007

Updated December 2007

Applies to: Microsoft Visual Studio 2008, 2007 Microsoft Office System, Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System, Microsoft Visual Studio 2005, Microsoft Visual Studio 2005 Tools for the Microsoft Office System, Microsoft Office 2003

Download Visual Studio 2005 Tools for Office Second Edition Sample: Deploying Office Solutions Using Windows Installer Version 3

Contents

  • About This Article

  • Deployment Overview for Visual Studio Tools for Office Solutions

  • Deployment Methods for Visual Studio Tools for Office

  • Using Windows Installer to Deploy a Solution

  • Adapting the Setup Project for Windows Vista

  • Known Issues Deploying Visual Studio Tools for Office Solutions

  • Product Codes and Component IDs

  • Conclusion

  • Additional Resources

About This Article

The steps are quite similar for deploying solutions that you create by using any of these editions of Microsoft Visual Studio Tools for the Microsoft Office System:

  • Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0), which is part of Microsoft Visual Studio 2008 Professional and Team System editions. These steps apply only to the Microsoft Office 2003 projects in this edition; projects for the 2007 Microsoft Office system use ClickOnce technology instead.

  • Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (Visual Studio 2005 Tools for Office Second Edition, or VSTO 2005 SE)

  • Microsoft Visual Studio 2005 Tools for the Microsoft Office System (VSTO 2005)

This article uses the initials to refer to each specific edition when necessary, and uses the name "Visual Studio Tools for Office" to include both editions.

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

  • An overview of the main steps required to deploy a Visual Studio Tools for Office solution, including Excel 2003 and Word 2003 document-based solutions and add-ins for the 2003 and 2007 releases of Office.

  • An overview of how to deploy a Visual Studio Tools for Office solution using the Visual Studio Setup project, including how you can add the prerequisites to your setup packages. This is a somewhat challenging task that is often necessary. In addition, the steps for granting security trust to a solution receive special attention.

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

The Windows Installer download that accompanies this article contains the sample files used throughout the article.

A second article, Deploying Visual Studio 2005 Tools for the Office System SE 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 document-based solution. The second shows you how to enhance a Microsoft Office Outlook 2003 or 2007 add-in to include installing the prerequisites and granting trust to the customization assembly.

Deployment Overview for Visual Studio Tools for Office Solutions

You can deploy Visual Studio 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 (add-in solutions only).

  • Grant trust to the solution's assemblies.

For more information about deploying solutions, see Deploying Office Solutions in Visual Studio Tools for Office online Help.

Decide on a Deployment Model

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.

  • For Excel and Word document solutions, you can choose whether to deploy the solution to the local hard disk, a Web server, a network file share, or to use a hybrid approach. The hybrid approach allows you to deploy the document onto a desktop computer and place the customization assembly (that is, the assembly containing your code) in a network-accessible location.

  • For add-in solutions, you can decide whether to store the customization assembly on the local hard disk or in a network-accessible location.

Install the Prerequisites on Each User's Computer

To run Visual Studio Tools for Office solutions, each user's computer must have the following software:

  • The Microsoft .NET Framework version 2.0

  • The appropriate Microsoft Office applications for your solution:

    • Microsoft Office 2003 applications that support VSTO 2005 document-based solutions

    • Microsoft Office 2003 applications that support VSTO 2005 SE add-ins

    • 2007 Microsoft Office applications that support VSTO 2005 SE add-ins

  • Primary interop assemblies for the version of Office you are using

    You must install the primary interop assemblies or mark them as Install on first use during installation.

    Microsoft Office applications install the primary interop assemblies only if the destination computer has the .NET Framework 1.1 or later installed.

    A typical installation of Microsoft Office 2003 or a stand-alone product such as Word sets the applications to install the primary interop assemblies on first use of the product. A full installation installs the primary interop assemblies during the installation process.

    For the 2007 Microsoft Office system, the installer installs the interop assemblies by default if the computer has the .NET Framework installed.

    After you install the Office applications, if you find you do not have the interop assemblies installed, 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 a specific computer has the primary interop assemblies installed, you should install the primary interop assemblies as part of your solution. Microsoft Office provides a downloadable, redistributable package of the primary interop assemblies that does not require access to the Microsoft Office installation media.

  • VSTO 2005 SE runtime

    The VSTO 2005 SE version of the runtime provides new feature support introduced in VSTO 2005 SE and also some software updates. It supports both VSTO 2005 solutions and VSTO 2005 SE solutions.

  • Visual Studio Tools for Office Language Pack (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 will run, but Visual Studio Tools for Office runtime error and warning messages appear in English.

NoteNote

VSTO 2005 SE uses the same language pack as VSTO 2005.

Important noteImportant

Users require administrative rights to install these prerequisites. If they do not have those rights, you must find another method of deployment such as 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 the prerequisites, see Additional Resources.

Prepare the Solution for Deployment

To prepare your solutions for deployment, update the manifest files with the correct deployment locations. The manifest files are handled differently by document-based solutions and add-in solutions.

Word and Excel Document-Based Solutions

VSTO 2005 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 VSTO 2005 SE 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 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, in addition to editing the deployment manifest and external application manifest files for the final deployment location. For more information, see How to: Change the Location of Document-Level Customizations.

Add-in Solutions

Although Outlook 2003 and VSTO 2005 SE add-ins have application manifests, the 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 Application-Level Add-ins.

Copy the Files to the Deployment Location

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

Create the Required Registry Entries (Add-ins Only)

Add-ins created by using VSTO 2005 SE require a set of registry entries on each computer. These registry entries point to the location of the application manifest and provide additional information about the add-in. The registry entries are necessary for all 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. Office applications that support add-ins check the registry at startup to know which add-ins are available. The registry entries contain other information that the Office host needs to load the add-ins properly.

For more information, see Deploying Application-Level Add-ins.

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.

Word and Excel Document-Based Solutions

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

NoteNote

When you use VSTO 2005 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 solution:

  • The Publish Wizard

    The Publish Wizard enables you to deploy Visual Studio Tools for Office solutions to a Web site, a 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 the users have the following prerequisites:

    • The .NET Framework 2.0

    • The VSTO 2005 SE runtime

    • The primary interop assemblies for the correct version of the Office application

    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 add-in 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 Application-Level Add-ins.

  • The Visual Studio Setup project

    The Visual Studio Setup project helps you create a Windows Installer package (.msi file) to deploy the solution. In addition, it creates a Setup.exe file that detects and installs the prerequisites, such as the .NET Framework 2.0. You can use the Setup project as a complement to the Publish Wizard. You can publish a Visual Studio 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 a VSTO 2005 or VSTO 2005 SE add-in, Visual Studio Tools for Office automatically creates a Setup project for your solution. However, the Setup project needs to be adjusted (discussed later) to check for and, if necessary, install prerequisites.

    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 Tools for Office an easy way to install your Visual Studio Tools for Office solution on their computers.

However, there are some specific requirements that Visual Studio Setup projects do not currently support. The most important requirements in this category are those that pertain to installing prerequisites, such as the VSTO 2005 SE runtime, and granting security trust to the solution. This article addresses these areas.

Using Windows Installer to Deploy a Solution

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, the files are installed in the following directory:

C:\Program Files\Microsoft Visual Studio 2005 Tools for Office SE Resources\VSTO2005SE Windows Installer Sample Version 3\

This article refers to this directory as {SamplesDir}.

A second article, Deploying Visual Studio 2005 Tools for the Office System SE 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 document-based solution. The second shows you how to enhance a Microsoft Office Outlook 2003 or 2007 add-in to include installing the prerequisites and granting trust to the customization assembly.

Assumptions

This article makes the following assumptions 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 does not use the optional deployment manifest.

Creating a Windows Installer Package

At a high level, the procedures are as follows:

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

    Add-in projects automatically include a Setup project in the solution.

    If the project is for an Excel or Word document solution:

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

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

  2. Indicate which prerequisites Setup.exe must check for and install.

    The most notable prerequisites are the .NET Framework 2.0 and the VSTO 2005 SE runtime. Setup projects created by VSTO 2005 SE project templates automatically check for the .NET Framework 2.0 but not for the VSTO 2005 SE runtime.

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

  4. Specify the location of the customization assembly in the application manifest so that the Excel or Word document can load the customization, or so that add-in hosts can locate and load the add-in customization.

  5. Add launch conditions to the Windows Installer package so that it checks for the prerequisites.

    Users can run the Windows Installer by double-clicking Setup.exe. It is also possible to install the solution by double-clicking the .msi file. When the setup routine is operating in this mode, it does not install the prerequisites. However, you can add launch conditions to the .msi file to warn your users to use Setup.exe instead.

    Important noteImportant

    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 to Document-Based Solutions

Adding a Setup project to an existing VSTO 2005 document 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

Creating a Setup project

After you add the Setup project to your solution, you can add your VSTO 2005 document project files by using the File System Editor (Figure 2).

Figure 2. Adding the installation files

Adding installation files

Detecting and Installing Prerequisites

When you run 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. Developers often refer to this process as "bootstrapping." This article will often use 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.

Prerequisites

As the setup author, you can determine the prerequisites. You can also determine whether the user of your setup downloads the prerequisites from the Web, has them included with the Windows Installer, or downloads them 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

Choosing which prerequisites to install

Prerequisites Packages

As noted earlier, a Visual Studio Tools for Office solution requires the .NET Framework 2.0, the VSTO 2005 SE runtime, and the primary interop assemblies for the correct version of Office. 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. Visual Studio populates the dialog box by processing a special directory that lists 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 Professional, Team Suite, or any of the role-based Team Editions, 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 for Visual Studio 2005 by appending \bootstrapper\packages to the value of this registry key: \HKLM\SOFTWARE\Microsoft\.NETFramework\sdkInstallRootv2.0

In Microsoft Visual Studio 2008, the directory is the following:

C:\Program Files\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages\

Tip

If in doubt, you can determine the location for Visual Studio 2008 by appending Packages to the value of this registry key: \HKLM\SOFTWARE\Software\Microsoft\GenericBoostrapper\3.5\Path

Bootstrapper package

Dependent packages

Other conditions

VSTO 2005 SE runtime

The .NET Framework 2.0

 

Visual Studio Tools for Office Language Pack

VSTO 2005 SE runtime

 

Primary interop assemblies redistributable package for the 2003 release of Office

.NET Framework 2.0

Installs all primary interop assemblies if Office 2003 is installed.

Primary interop assemblies redistributable package for the 2007 release of Office

.NET Framework 2.0

Installs all primary interop assemblies if the 2007 release of Office is installed.

Bootstrapper Package Details

The bootstrapper includes the following packages:

  • VSTO 2005 SE runtime (vstor.exe)

    The product.xml file for the VSTO 2005 SE runtime contains a dependency check for the .NET Framework 2.0. The runtime is installed only after the .NET Framework 2.0.

  • Visual Studio Tools for Office Language Pack

    The Visual Studio Tools for Office Language Pack depends on the VSTO 2005 or VSTO 2005 SE runtime and is not installed until the user installs one of the runtimes on the target computer.

  • Primary interop assemblies redistributable packages for the 2003 and 2007 releases of Office

    These redistributable packages are downloadable Windows Installer files that enable you to install the Office primary interop assemblies without requiring the Office installation media. The package is installed only if the .NET Framework 1.1 (or later) and Microsoft Office are installed. During installation, the package installs all of the primary interop assemblies for that version of Office.

    NoteNote

    The package does not install the smart tag primary interop assemblies if the computer has only the Outlook 2003 stand-alone product installed.

    For the purposes of this article, the .NET Framework 2.0 is identified as a dependency. Thus, when either of the primary interop assemblies’ redistributable packages are included, Setup.exe checks for the .NET Framework 2.0 and installs it, if required.

    The product.xml file contains a single prerequisite check. It checks to see whether that computer has the correct version of Office installed for the primary interop assemblies. If the bootstrapper installation check does not find a valid version of Office, it skips installing the primary interop assemblies. This check for Office requires an Office component check (ComponentCheck.cpp), which you can find in the sample that accompanies this article.

    TipTip

    If you are deploying an Office 2003 solution to be installed on computers that have either the 2003 or the 2007 release of Office, you can include both redistributable packages.

Adding the Visual Studio 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 be made only once and only on your development computer.

This task shows how to use the files that are available in the Windows Installer download that accompanies this article. To use them, prepare the files before you copy them into the bootstrapper package directory.

Preparing the Runtime

To prepare the VSTO 2005 SE runtime bootstrapper package

  1. Download Microsoft Visual Studio 2005 Tools for Office Second Edition runtime from the Microsoft Download Center.

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

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 Tools for Office Language Pack to see runtime messages in the same language as Windows.

To prepare the Visual Studio 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.

Preparing the Office Component Check

Compile the Office component checker sample for the primary interop assemblies redistributable packages.

Important noteImportant

If you are using VSTO 2005 SE in conjunction with VSTO 2005, ensure that you have installed both the .NET Framework 2.0 software development kit (SDK) and the Windows SDK.

NoteNote

By default, Visual Studio Tools for Office does not install the .NET Framework 2.0 SDK. You can download it or install it from the installation media by using the Add or Remove Programs command in Visual Studio Tools for Office. In addition, you need to download a copy of the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components 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.

NoteNote

These downloads are not required if you are using a version of Visual Studio with Visual C++ installed.

To prepare the Office component check

  1. Open the Command Prompt window needed to compile the check.

    If you are using Visual Studio 2005 Professional, Team Suite, or one of the role-based Team editions, open the Visual Studio 2005 Command Prompt window by clicking Start, and then pointing to Programs, pointing to Microsoft Visual Studio 2005, pointing to Visual Studio Tools, and then clicking Visual Studio 2005 Command Prompt.

    If you are using Visual Studio 2005 Tools for Office, run CMD Shell by clicking Start, pointing to Programs, pointing to Microsoft Windows SDK, and then clicking CMD Shell.

    If you are using Visual Studio 2008, open the Visual Studio 2008 Command Prompt by clicking Start, and then pointing to Programs, pointing to Microsoft Visual Studio 2008, pointing to Visual Studio Tools, and then clicking Visual Studio 2008 Command Prompt.

  2. At 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 SE Resources\VSTO2005SE Windows Installer Sample Version 3\.

  3. Compile the component checker by typing the following command.

    cl.exe /Oxs /MT /GS ComponentCheck.cpp advapi32.lib
    
  4. Close the Command Prompt window.

  5. Using Windows Explorer, copy the executable file ComponentCheck.exe into {SamplesDir}\packages\Office2003PIA and {SamplesDir}\packages\Office2007PIA.

Preparing for the 2003 Release of Office

You must include the primary interop assemblies for Office 2003 in the corresponding bootstrapper package if your solution is a VSTO 2005 Excel or Word document solution, or an add-in solution for an Office 2003 application.

To prepare the primary interop assemblies bootstrapper package

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

  2. Run the primary interop assembly installer.

  3. Accept the Microsoft Software License Terms, which 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 installer extracted the files.

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

    NoteNote

    Because you cannot directly download the 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.

Preparing for the 2007 Release of Office

You must include the primary interop assemblies for 2007 in the corresponding bootstrapper package if your solution will run in the 2007 release of Office, including VSTO 2005 Excel and Word document solutions.

To prepare the primary interop assemblies bootstrapper package

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

  2. Run the primary interop assembly installer.

  3. Accept the Microsoft Software License Terms, which 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 installer extracted the files.

  5. Copy O2007PIA.msi into the directory {SamplesDir}\packages\Office2007PIA.

    NoteNote

    Because you cannot directly download the 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 '2007 Microsoft Office Primary Interop Assemblies', so the package will be published to the same location as the 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 2005 Professional, Team Suite, or one of the role-based Team editions, 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

    In Visual Studio 2008, the directory is the following:

    C:\Program Files\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages

    Tip

    If in doubt, you can determine the location for Visual Studio 2008 by appending Packages to the value of this registry key: \HKLM\SOFTWARE\Software\Microsoft\GenericBoostrapper\3.5\Path

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

Granting Trust to the Customization Assembly

The Visual Studio 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.

When you consider the type of evidence that you want to use to trust the solution, avoid relying solely on location-based evidence. Instead, think about combining location-based evidence 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 enables 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 in managed code 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# 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.

  • During installation, it sets the security policy. During rollback and uninstall, it removes the security policy changes. Table 2 provides the list of the parameters required by the Install method.

  • 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

The name of the security code group for your Visual Studio 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 Tools for Office solution.

solutionCodeGroupDescription

A description for your solution code group name.

assemblyCodeGroupName

The code group name for the assembly. The custom action grants full trust to this code group using the strong name of the assembly as evidence.

assemblyCodeGroupDescription

The description of your assembly code group name.

allUsers

A value that specifies 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 installation 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. The custom action sets up two code groups to ensure that the common language runtime trusts the customization assembly by both its location and its strong name.

TipTip

Trust is granted to that particular version of the strong name. To trust any version, add the –noversion flag to the arguments parameter string used for creating the assembly code group.

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 that level requires enterprise administrative rights. In practice, you can 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 custom action adds the Solution Code group as a child of the All_Code root code group. When updating the machine-level policy, the custom action adds the Solution Code group as a child of the My_Computer_Zone code group.

During the uninstalling process, an exception is thrown if the code group cannot be found.

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

There are different procedures for updating the application manifest, depending on whether you are deploying an Excel or Word document-based solution or an add-in solution.

Excel and Word Document Solutions

Excel and Word VSTO 2005 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.

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.

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 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 overrides only the Install method of the Installer class, because removing or rolling back the solution removes the document; there is no need to edit the application manifest. Table 3 shows parameters for the Install method of the custom action.

A second article, Deploying Visual Studio 2005 Tools for the Office System SE Solutions Using Windows Installer: Walkthroughs (Part 2 of 2), provides detailed instructions for including the custom action and calling it 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 you are deploying—for example, ExcelApplication.doc.

assemblyName

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

Add-in Solutions

The application manifests for add-in projects are installed on disk, not embedded in documents. For the VSTO 2005 SE runtime to discover the manifest location, you must specify it in the registry. When you create the add-in Setup project, the template adds the registry entries required to run the add-in 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 user does not execute the bootstrapper, and thus setup cannot detect the dependencies and does not install the prerequisites 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 on Windows Installer component ID checks or registry values. For more information, see Launch Condition Management in Deployment. For example, you can add a registry key check for the VSTO 2005 SE runtime and display a message if the runtime is not installed.

Figure 4. A launch condition to search for the VSTO 2005 SE runtime

A launch condition to search for the runtime

For a list of component IDs for the VSTO 2005 SE runtime, the Visual Studio Tools for Office Language Pack, and Office primary interop assemblies that you can use as launch conditions, see Product Codes and Component IDs.

Adapting the Setup Project for Windows Vista

For detailed information about how to make your solution compliant with Windows Vista User Access Control (UAC), download the document Windows Vista Application Development Requirements for User Account Control Compatibility from the Microsoft Download Center

There are some considerations that are specific to Visual Studio Tools for Office.

Setup.exe and Bootstrapper Packages

Applications designed for Windows Vista UAC require an application manifest that describes the required execution level, for example "run as administrator." If the application does not have either an embedded or an external manifest, Windows Vista uses various heuristics to determine the execution level; for example, if the file name contains words such as “install” or “setup”, it requires administrator rights to run.

Both Setup.exe and the associated bootstrapper packages require application manifests:

  • Setup.exe

    The bootstrapper (Setup.exe) generated by the Setup project in Visual Studio 2008 automatically has an embedded manifest that indicates that the application is run “asInvoker”, which means that it is to be run with the standard user token. All prerequisite packages invoked by Setup.exe will require separate elevation.

    The bootstrapper package generated by the Visual Studio 2005 Setup project has no embedded application manifest, and thus one must be added. In contrast to the Visual Studio 2008 Setup.exe, the Visual Studio 2005 requested execution level (“requestedExecutionLevel”) must be administrator (“requireAdministrator”).

    The Visual Studio 2008 bootstrapper assumes that any Windows Vista user could be an administrator as a result of the credentials prompt, whereas the Visual Studio 2005 bootstrapper does not and thus must be run as administrator. However, if a standard user on Windows Vista runs a Visual Studio 2005 setup and is prompted to enter Administrative credentials, the chained Windows Installer package (MSI) is also installed with these elevated credentials. If the MSI is a single-user installation (for example, a Visual Studio Tools for Office add-in) the add-in is installed for the administrator rather than the standard user. This situation does not occur in Visual Studio 2008, where Setup.exe itself is not elevated.

  • VSTO 2005 SE runtime and language pack bootstrapper packages

    External application manifests are included in the sample that accompanies this article.

  • Office component checker

    This check requires a manifest. The requested execution level should be "runAsInvoker".

Windows Installer Package (MSI)

The MSI contains the Visual Studio Tools for Office solution. The solution can be installed either by invoking the MSI or by running Setup.exe, which will detect and install the prerequisites before finally invoking the MSI.

The MSI requires modification for Windows Vista. These procedures require the latest version of the Microsoft Windows Software Development Kit (SDK) for Windows Server 2008 and .NET Framework 3.5.

Single-User Installations

By default, the Setup project created for add-in projects installs the solution for the current user. The solution is installed in the Program Files directory, which the user might not have permission to install into. Alternatively, the solution could be installed into the user’s application data folder and the control to set the installation folder removed. Next, the MSI must be marked as UAC compliant, or standard users will be prompted for credentials. The Windows SDK contains an MSI file editor named Orca that you use to mark MSI files as compliant.

To set the installation folder to the user’s application data folder

  1. In Solution Explorer, right-click the Setup project.

  2. Point to View, and then click File System.

  3. In the File System Editor, click the Application Folder node.

  4. In the Properties window, set the DefaultLocation property to [AppDataFolder]\[ProductName].

To remove the installation folder control

  1. In Solution Explorer, right-click the Setup project.

  2. Point to View, and then click User Interface.

  3. In the User Interface Editor, right-click the Installation Folder node, and then click Delete.

To make the MSI UAC compliant

  1. Build the Setup project.

  2. Exit Visual Studio.

  3. Start Orca and open the MSI from the build folder.

  4. On the View menu, click Summary Information.

  5. Click UAC Compliant.

  6. Click OK.

  7. On the File menu, click Save.

TipTip

Use the Orca tool to mark the MSI as UAC compliant every time you build the Setup project.

Mixed Mode Installs

By default, Setup projects support installation for all users or the current user. The option to install for all users is only available if the user is an administrator. For backward compatibility, the control is shown for all users unless the MSIUSEREALADMINDETECTION is property is set. In the Orca tool, add a new property called MSIUSEREALADMINDETECTION with a value of 1.

Known Issues Deploying Visual Studio Tools for Office Solutions

  • 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. The Setup package does not run on a 64-bit computer because the 32-bit version cannot run under the Windows on Windows (WOW64) subsystem. To work around this issue, you must install the 64-bit version of the .NET Framework manually before running Setup.

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

    Visual Studio Tools for Office requires an updated version of OtkLoader. OtkLoader is included with Office and stand-alone products. As part of the installation process, the Visual Studio Tools for Office runtime updates OtkLoader if Office or an Office stand-alone product is installed. However, it is possible for you to install the VSTO 2005 SE runtime before Office, in which case 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 must be included in 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 the Microsoft Software License Terms, and then copy the redistributable package from the installation folder. There is no way to download the redistributable package directly; it must always be included with your Setup.

    If you set the prerequisite installation location to the Web, you are warned that the redistributable 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.

  • Compile errors occur when you compile the ComponentCheck.cpp source file.

NoteNote

If you are using Visual Studio Tools for Office, you must ensure that both the .NET Framework 2.0 Software Development Kit (SDK) (x86) and the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime are installed. By default, Visual Studio 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, by using the Add or Remove Programs command in Visual Studio Tools for Office. These downloads are not required if you are using Visual Studio Team System.

  • The primary interop assembly redistributable packages are always installed by Setup.exe.

    The redistributable packages install the primary interop assemblies only for those applications that are currently installed. Thus the prerequisite packages are configured to always install the primary interop assembly packages to ensure that all of the primary interop assemblies are installed.

    You can configure the prerequisite packages to install the primary interop assemblies only if the ones that your solution requires are not already installed.

    To do this, edit the product.xml file for the appropriate redistributable package. For example, if your solution requires the Word and SmartTag primary interop assemblies, add the following check to the <InstallChecks> node.

    <ExternalCheck 
          Property="PIAsRegistered" 
          PackageFile="ComponentCheck.exe" 
          Arguments="{816D4DFD-FF7B-4C16-8943-EEB07DF989CB} {00B41853-4377-4AD8-AD44-8404E0D331EC}"/>
    

    The component codes for the various Office primary interop assemblies can be found in the Product Codes and Component IDs section.

    Next, add the following check into the <InstallConditions> node.

    <BypassIf Property="PIAsRegistered" Compare="ValueEqualTo" Value="0"/>
    

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}. 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 can 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

VSTO 2005 SE 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}

Primary interop assemblies for Office 2003

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

Use component IDs for specific primary interop assemblies listed below.

Primary interop assemblies for the 2007 release of Office

{50120000-1105-0000-0000-0000000FF1CE}

Use component IDs for specific primary interop assemblies listed below.

The VSTO 2005 and VSTO 2005 SE runtimes share the same product code. To detect which version of the VSTO 2005 runtime is installed, examine the Update value in the following registry key:

HKLM\Software\Microsoft\vsto runtime Setup\v2.0.50727

The Update values have the following meanings:

  • If the registry key is present but there is no Update setting, then the first edition of the VSTO 2005 runtime is installed (version 8.0.50727.42).

  • If Update = 1, the original VSTO 2005 SE runtime is installed (version 8.0.50727.816).

  • If Update = 2, then version 8.0.50727.891 of the VSTO 2005 SE runtime is installed.

  • If Update = 3, then version 8.0.50727.940 of the VSTO 2005 SE runtime is installed. The bootstrapper packages that accompany this article are configured to detect and install build 940.

Office Primary Interop Assemblies Component IDs

The following table lists the component IDs for the primary interop assemblies. These values are the same whether Microsoft Office or the redistributable package installs the primary interop assemblies.

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. Component IDs for the primary interop assemblies

Primary interop assembly

Office 2003component ID

Office 2007component ID

Excel

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

{1ABEAF09-435F-47D6-9FEB-0AD05D4EF3EA}

InfoPath

{C1E59364-35F6-44B3-AF0F-FCA934C4B252}

{F1B5AE30-CB00-4DCF-978B-07D33B034ADB}

Outlook

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

{ED569DB3-58C4-4463-971F-4AAABB6440BD}

PowerPoint

{3F40FA9E-26CA-4CA2-93C9-603622349915}

{04E73476-518E-4B6A-8E10-021A00078847}

Visio

{6F1AE751-4D8A-4B25-AC0A-C6CB912A9791}

{C1F1028F-D91A-43E8-A117-4F7CAFD7A041}

Word

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

{816D4DFD-FF7B-4C16-8943-EEB07DF989CB}

Microsoft Forms 2.0*

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

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

Microsoft Graph

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

{580CB155-841D-4D48-9F59-866A035C2241}

Smart Tag

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

{00B41853-4377-4AD8-AD44-8404E0D331EC}

* No change between the 2003 and 2007 releases.

Conclusion

This article provides an overview of deploying a Visual Studio Tools for Office solution using a Visual Studio Setup project to create a Windows Installer package. This article provides samples that show how you can install the required prerequisites (the .NET Framework 2.0, the VSTO 2005 SE runtime, and the primary interop assemblies), 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 the Office System SE Solutions Using Windows Installer: Walkthroughs (Part 2 of 2).

Additional Resources

To learn more about the products and technologies mentioned or used in this article, see these resources:

Code Security

Redistributable Packages