Summary: Learn how to deploy a Microsoft Visual Studio Tools for the Office system 3.0 add-in or document-level solution using a Visual Studio 2008 setup project to create a Windows Installer package that targets the 2007 Microsoft Office system. (29 printed pages)
Wouter van Vugt, Code Counsel
Ted Pattison, Ted Pattison Group
Applies to: Microsoft Visual Studio Tools for the Microsoft Office system 3.0, 2007 Microsoft Office system, Visual Studio 2008
Download: http://code.msdn.microsoft.com/VSTO3MSI
Contents
Overview
You can develop a Visual Studio Tools for the Office system 3.0 solution for the 2007 Microsoft Office system, and deploy the solution by using a Visual Studio 2008 Setup project to create a Windows Installer package. The discussion includes steps for deploying a simple add-in, including additional files and components, and trusting the solution. This applies to both application-level add-ins and document-level solutions.
Deployment Methods
You can use ClickOnce to create and install self-updating applications with minimal user interaction. This has an automated mechanism for easily distributing updates to your application. However, ClickOnce is not capable of deploying additional components such as Visio stencils or additional registry keys. It is also possible the customization is part of a greater project where using ClickOnce may be unwanted.
Besides ClickOnce, you can also use Windows Installer to deploy a Visual Studio Tools for Office customization. Windows Installer allows you to configure the deployment in great detail, but this does require more effort to configure correctly. You lose the simple ease of deploying using ClickOnce technology and advantages such as automated updates, but you receive benefits such as branding and configurability. You can also combine these two technologies by having your Windows Installer setup file call into the ClickOnce installation tool provided with Visual Studio Tools for Office.
The following table shows various advantages and disadvantages of these two deployment methods related to Visual Studio Tools for Office. For a complete overview of the benefits of each deployment technology, see Choosing Between ClickOnce and Windows Installer.
Table 1. Advantages and disadvantages of the available deployment methods
| Method | Advantages | Disadvantages |
|---|
ClickOnce
|
- Little user interaction
- Automated updates
- Little effort for the developer
|
- Always deploys as a single solution, cannot be part of a greater whole
- Cannot deploy additional files or registry keys
- Cannot interact with the user to configure the installation
- Cannot brand the installation
|
Windows Installer
|
- Can deploy additional components and registry settings
- Can interact with the user to configure the installation.
- Custom branding of the installation
|
- Requires advanced configuration
- Higher developer effort required
- No automated updates
|
Deploying Visual Studio Tools for the Office system 3.0 solutions
Both ClickOnce and Windows Installer packages need to perform the same rudimentary tasks when installing a VSTO 3.0 Solution.
- Install prerequisite components on the user computer.
- Deploy the solution specific components.
- For add-ins, create registry entries.
- Trust the solution to allow it to execute.
Required Prerequisite Components on the Target Computer
To run Visual Studio Tools for the Office system 3.0 solutions, the following software must be available on the user computer.
- The 2007 Microsoft Office system.
- The Microsoft .NET Framework, version 3.5.
Visual Studio Tools for the Office system 3.0 depends on the Microsoft .Net 3.5 Framework. The 3.5 Framework has new features that support specific requirements of Visual Studio Tools for Office.
- The Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 runtime).
Visual Studio Tools for the Office system 3.0 provides a runtime environment that manages add-ins and document-level solutions. For more information about runtime, see How to: Install the Visual Studio Tools for Office Runtime.
- The primary interop assemblies for the 2007 Microsoft Office system.
For application-level add-ins or document-level solutions for the 2007 Microsoft Office system, these primary interop assemblies need to be available. The 2007 Microsoft Office system installs these assemblies by default. However, this does not ensure their availability.
Microsoft provides a downloadable redistributable package of the primary interop assemblies that does not require access to the Office installation media. This redistributable package is deployed as part of the overall deployment of your Visual Studio Tools for Office solution.
- Optionally, language packs for the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 runtime).
 Note: |
|---|
| A primary interop assembly is a unique, vendor-supplied assembly containing type definitions (as metadata) of types implemented with COM. For more information about primary interop assemblies and Visual Studio Tools for the Office system 3.0 see Office Primary Interop .
|
Solution Specific Components
The installer package must install the following components to the user computer.
- The Microsoft Office document, if you create a document-level solution.
- The customization assembly and any assemblies it requires.
- Additional components such as configuration files.
- The application manifest (.manifest).
- The deployment manifest (.vsto).
Registry Entries for Add-ins
Add-ins require a set of registry entries for the Microsoft Office application to locate the add-in. You should create the registry entries as part of the deployment process. For more information about registry entries pertaining to a Visual Studio Tools for Office add-in, see
Registry Entries for Application-Level Add-Ins. When developing an Outlook add-in that displays custom form regions you should create additional registry keys as part of the installation procedure to allow the form regions to be identified. For more information about registry entries pertaining to Outlook form regions, see
Specifying Form Regions in the Windows Registry.
Document-level solutions do not require these registry entries because the customization is located by using information inside the Microsoft Office document. For more information about the document properties used for locating document-level customizations, see
Custom Document Properties Overview.
For the RTM version of Visual Studio 2008, there is an issue with the registry when the same name as your Visual Studio Tools for Office project is used. See the
Known Issuessection for more details.
| Note: |
|---|
| An important difference between Microsoft Office 2003 and the 2007 Microsoft Office system is that the 2007 Microsoft Office system no longer supports registering managed add-ins inside the HKEY_LOCAL_MACHINE hive.
|
Trusting the Visual Studio Tools for Office Solution
Before you allow the customization to execute, a solution must be trusted. This trust relationship is based on the signed application and deployment manifests. You can either sign the manifests with a certificate that identifies a known and trusted publisher, or create a trust-relationship at installation time with an inclusion list entry. For more information about how to obtain a certificate for signing, see
ClickOnce Deployment and Authenticode. For more information about using the user inclusion list, see
Trusting Office Solutions by Using Inclusion Lists (2007 System).
If neither option is used, a trust prompt is displayed to the user to let them decide whether to trust the solution. You can add an inclusion list entry with a custom action in your Windows Installer file. For more information about enabling the inclusion list, see
How to: Configure Inclusion List Security (2007 System).
Document-level solutions have an extra requirement where the document location must also be trusted before the Office application allows the customization to load. For more information about security related to document-level solutions, see
Granting Trust to Documents (2007 System).
Required Administrative Rights to Perform an Installation
Visual Studio Tools for the Office system 3.0 solutions install at a user level, but tasks like installing prerequisites or changing custom configurations require administrative rights. Other tasks requiring administrative rights include the following:
- Deploying primary interop assemblies with your setup project.
- Deploying the Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 runtime) with your setup project.
- Deploying the Microsoft .NET Framework with your setup project.
- Deploying components to folders such as the program files folder.
- Writing registry entries outside of the HKEY_CURRENT_USER hive.
Mixed Mode Installs
An application-level add-in is only installed for the user executing the MSI. Installation for all users is not supported by Visual Studio Tools for the Office system 3.0. This is incorporated into the design of the 2007 Microsoft Office system.
Required Components for Creating an Installer
Primary Interop Assemblies
You should deploy the primary interop assemblies as part of your Windows Installer file. Visual Studio 2008 installs the primary interop assemblies on your development computer, not as a redistributable package, but as a set of loose assemblies. While you can use these assemblies for development, it is important that you do not distribute them.
You can download the package containing the redistributable primary interop assemblies for the 2007 Microsoft Office system from the Microsoft Download Center: 2007 Microsoft Office System Update: Redistributable Primary Interop Assemblies. After downloading and installing the package on your developer computer, you can use the redistributable module and the bootstrapper configuration file in the download of this article to have the primary interop assemblies appear in the Prerequisites Dialog Box inside the Visual Studio 2008 IDE.
Language Packs
The Visual Studio Tools for Office runtime is capable of displaying administrative messages in various languages. To allow messages to be displayed in a different language than English, you should download the appropriate language pack and deploy it on the target computer along with your solution.
You can only deploy a single language pack for each installer that you build. To provide more than one language for your product, you can either maintain separate Visual Studio setup projects for each language or reconfigure a single setup project for each language before building the installer package.
The following language packs are available for download:
Language
|
Download location
|
Japanese
|
http://go.microsoft.com/fwlink/?LinkId=95147&clcid=0x411
|
| Note: |
|---|
Visual Studio populates the Prerequisites dialog box by processing a specific folder that contains the available prerequisite packages. Each package has its own folder in that directory. To read more about bootstrapper packages, see Adding Custom Prerequisites.
For Visual Studio 2008, the default folder for prerequisite packages is %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages
|
Product Codes and Component IDs
You can use product codes and component IDs to check for the presence of certain components on the user computer to make sure that the computer meets certain requirements. The product code is a unique identifier for the particular product release, represented as a string GUID, for example: {12345678-1234-1234-1234-123456789012}. A product consists of many components that can be shared across multiple products. These components have an ID that is also in 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, to verify the presence of a required component. 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 2 displays relevant product codes and component IDs related to Visual Studio Tools for the Office system 3.0. Note that the language packs for Visual Studio Tools for Office are now separated into language specific packs. Previous versions of Visual Studio Tools for Office provided one generic language pack that contained all available languages. The following table will be updated when new language packs are released.
Table 2. Product codes and component IDs of the 2007 Microsoft Office System and Visual Studio Tools for Office
| Package | Product code | Component ID |
|---|
Visual Studio Tools for the Office system (version 3.0 runtime)
|
{8FB53850-246A-3507-8ADE-0060093FFEA6}
|
{AF68A0DE-C0CD-43E1-96DD-CBD9726079FD}
|
Visual Studio Tools for the Office system 3.0 Language Pack – Japanese
|
{A6A9008F-79A3-3118-88B1-0235BDEB718D}
|
{A2E56E4D-4E2D-4E2C-8A44-6115CABBB4EF}
|
Primary interop assemblies for the 2007 release of Office
|
{50120000-1105-0000-0000-0000000FF1CE}
|
Use component IDs for specific primary interop assemblies listed below.
|
Besides a component ID, you can also determine the presence of the Visual Studio Tools for Office runtime by checking for the presence of the following registry key.
HKLM\Software\Microsoft\VSTO Runtime Setup\v9.0.21022
When Visual Studio Tools for Office is installed, this key has a value named Install with a DWORD value of 1. Later updates to the runtime are located by the Update value found under this registry key. The Update value is not present on the RTM installation of Visual Studio Tools for the Office system 3.0.
Table 3 lists the component IDs of the primary interop assemblies. You can use these values to check for the presence of specific interop assemblies during the installation process. The Office Shared primary interop assembly is used by all Visual Studio Tools for Office solutions.
Table 3. Component IDs of the Redistributable Primary Interop Assemblies for the Microsoft Office System
| Primary interop assembly | Office 2007 component ID |
|---|
Excel
|
{1ABEAF09-435F-47D6-9FEB-0AD05D4EF3EA}
|
InfoPath
|
{F1B5AE30-CB00-4DCF-978B-07D33B034ADB}
|
Outlook
|
{ED569DB3-58C4-4463-971F-4AAABB6440BD}
|
PowerPoint
|
{04E73476-518E-4B6A-8E10-021A00078847}
|
Visio
|
{C1F1028F-D91A-43E8-A117-4F7CAFD7A041}
|
Word
|
{816D4DFD-FF7B-4C16-8943-EEB07DF989CB}
|
Microsoft Forms 2.0
|
{835AC3CE-E36B-4D65-B50F-2863A682ABEE}
|
Microsoft Graph
|
{580CB155-841D-4D48-9F59-866A035C2241}
|
Smart Tag
|
{00B41853-4377-4AD8-AD44-8404E0D331EC}
|
Office Shared
|
{FAB10E66-B22C-4274-8647-7CA1BA5EF30F}
|
Project
|
{957A4EC0-E67B-4E86-A383-6AF7270B216A}
|
Download Samples Provided with this Article
The walkthroughs provided in this article use various sample files contained in the download. The download contains the source code for the following components:
- All sample projects created in this article.
- Bootstrapper configuration files for the Redistributable Primary Interop Assemblies for the 2007 Microsoft Office system.
- Custom action classes for the Setup projects used to deploy the Visual Studio Tools for Office solution.
By default, these files are installed into the following folder:
%ProgramFiles%\Microsoft Visual Studio Tools for the Office system 3.0 Resources\Windows Installer Sample\
This article refers to this installation folder as {SamplesDir}.
Download: http://code.msdn.microsoft.com/VSTO3MSI
Preparing your Development Computer
Before creating a Windows Installer package, you first need to prepare your development computer.
To download and install the redistributable Primary Interop Assemblies
Download the installer for the Redistributable Primary Interop Assemblies for the 2007 Microsoft Office System.
Run the installer.
Accept the Microsoft Software License Terms. This gives you permission to package the primary interop assemblies as part of your installer.
In Windows Explorer, open the folder where the installer extracted the files. Copy O2007PIA.msi to the directory {SamplesDir}\packages\Office2007PIA.
If you intend to provide a different language other than English you can download and install the appropriate language packs for the Visual Studio Tools for Office runtime and bootstrapper package.
To download and install language packs
Download the language pack for the language that you require.
For Japanese, download from http://go.microsoft.com/fwlink/?LinkId=95147&clcid=0x411
Copy the downloaded file to the language specific subfolder of {SamplesDir}\packages\VSTOR30.
For Japanese, use the ja subfolder.
The bootstrapper configuration files use the ComponentCheck.exe tool for the primary interop assemblies to verify the presence of Microsoft Office on the user computer. To compile it, you need to have a C++ compiler available, like the one provided with Visual Studio 2008.
| Note: |
|---|
| Because the prerequisite packages are executed before the installation begins, you cannot be certain that the Microsoft .NET Framework is available on the user computer. For this reason, the ComponentCheck.exe tool is written in C++ and compiles to native code, so that the Microsoft .NET runtime environment is not needed at this point during the installation. It is also not feasible to distribute the ComponentCheck.exe tool as part of Visual Studio Tools for Office because this environment might not be installed on the user computer.
|
To prepare the Office ComponentCheck
Open a Visual Studio 2008 Command Prompt.
In the command prompt window, change the directory to {SamplesDir}\projects\ComponentCheck.
Compile the component checker by typing the following command
cl.exe /Oxs /MT /GS ComponentCheck.cpp advapi32.lib
Close the command prompt window.
Using Windows Explorer, copy the executable file ComponentCheck.exe from {SamplesDir}\projects\ComponentCheck into the{SamplesDir}\packages\Office2007PIA folder.
The following procedure shows how you can move the bootstrapper packages to the bootstrapper directory, so that you can select them from the Prerequisites Dialog Box in the Visual Studio 2008 IDE.
To copy the packages into the bootstrapper directory
Determine where your bootstrapper package directory is located. For an overview of directories that Visual Studio searches for bootstrapper packages, see
Adding Custom Prerequisites. For Visual Studio 2008, the default folder for prerequisite packages is
%ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages.
Copy the contents from {SamplesDir}\packages into the bootstrapper packages directory.
Creating the Add-in Project
The first step is to create a sample add-in project. In this walkthrough, you create a basic Excel add-in using and Visual Studio 2008.
The ExcelAddIn is a simple add-in for Microsoft Office Excel 2007 that displays a custom message when the add-in is loaded. The add-in is kept as simple as possible to allow focus on the general concepts of the deployment.
To create the ExcelAddIn project
Open Microsoft Visual Studio 2008.
On the File menu, expand New and click Project to create a new Visual Studio project.
In the New Project dialog box, in the Project types pane, expand Visual Basic or Visual C#, expand Office, and then select 2007.
In the Templates pane, select Excel 2007 Add-in.
In the Name box, type ExcelAddIn.
In the Solution name box, type VSTO v3 Deployment Demo.
Select Create Directory for Solution, and click OK to create the new Excel 2007 add-in. The Solution Explorer displays the opened solution, and opens the main code file.
Figure 1. Solution Explorer (C#)
Visual Studio provides two build configurations out of the box. You should make sure only to distribute release builds because these assemblies are optimized. Be aware that release builds might hinder debugging of your solution because of optimizations in the execution order.
For more information about Visual Studio and build configurations, see Build Configurations.
To set the build configuration to release
In the Solution Explorer, right-click Solution ‘VSTO v3 Deployment Demo’ (1 project) and click Configuration Manager to show the build configuration manager for the Visual Studio solution.
Note Your computer might show different names or locations for some of the Visual Studio user interface elements in the following procedures. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see
Visual Studio Settings.
In the Configuration Manager dialog box, for Active Solution Configuration, select Release.
Figure 2. Configuration Manager dialog box
Click Close to close the dialog box.
The last step for the add-in project is to add some code to verify that the add-in is running correctly.
To add code to the ExcelAddIn project
If the code file for the ThisAddIn class is not currently open, in the Solution Explorer, right-click the ThisAddIn.vb or ThisAddIn.cs file and click View code to open the main code file for the ExcelAddIn add-in.
In the code editor, locate the ThisAddIn_StartUp method. Add a call to the System.Windows.Forms.MessageBox.Show method to display a custom message when the add-in starts.
Public Class ThisAddIn
Private Sub ThisAddIn_Startup( _
ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Startup
System.Windows.Forms.MessageBox.Show("Hello World")
End Sub
End Class
public partial class ThisAddIn
{ private void ThisAddIn_Startup(object sender, System.EventArgs e) { System.Windows.Forms.MessageBox.Show("Hello World"); }}
Before you create the setup project for the ExcelAddIn add-in, first build the project so the project output is available for the setup project. Building the add-in generates the deployment and application manifests required for the deployment and installation of the add-in.
To build the ExcelAddIn project
On the Build menu, select Build Solution to compile the modified add-in. Make sure that there are no compilation errors.
Figure 3. Solution Explorer for ExcelAddIn
Note Building the ExcelAddIn project generates a new project item called ExcelAddIn_TemporaryKey.pfx. This file contains the certificate used to sign the deployment manifest in PKCS #12 format. The Visual Studio Tools for Office environment automatically adds a temporary certificate to sign the solution. You should never use this certificate for actual deployment of a Visual Studio Tools for Office solution. Request a certificate from a certificate authority trusted by both you and the user or request a certificate from one of the well-known commercial certificate authorities.
Creating a Basic Installer
Visual Studio 2008 provides a built-in project type for creating Windows Installer packages. With some added configuration, this project type is used to deploy a Visual Studio Tools for Office solution. To create an installer for the ExcelAddIn customization, perform the following tasks.
- Configure prerequisite components.
- Verify that the required prerequisite components are available. The user might not execute the bootstrapper (setup.exe), but execute the MSI directly instead. This circumvents the installation of prerequisite components.
- Add the components of the ExcelAddIn.
- Configure registry entries for the add-in
When a Visual Studio Tools for Office solution is locally installed using Windows Installer there are differences in the behavior of the Visual Studio Tools for Office runtime compared to solutions deployed using ClickOnce. First of all, the security is verified each time the solution is loaded. Additionally, the solution is not added to the ClickOnce cache, which means there are no automatic updates of the add-in. Deploying updates to your solution requires redistribution and installation of a new Windows Installer package.
You must specify that the solution is locally installed. This is indicated using the deployment manifest property. This property is defined in the Windows registry for add-ins and inside the document properties for document-level solutions. The manifest property is the location with the postfix |vstolocal to indicate the local install.
Start by creating the setup project. This project contains the configuration for the Windows Installer package. Part of the configuration is performed using built-in features. Additional tasks are performed using custom actions.
To create the ExcelAddInSetup project
On the File menu, expand Add and click New Project to add a new project to the VSTO v3 Deployment Demo solution.
In the Add New Project dialog box, in the Project types pane, expand Other Project Types and then select Setup and Deployment.
In the Templates pane, select Setup Project from the Visual Studio installed templates group.
In the Name box, type ExcelAddInSetup.
Ensure that the folder identified by the Location box is inside the VSTO v3 Deployment Demo folder created for the solution, and click Open to create the new setup project. Visual Studio opens the File Explorer for the new setup project. This explorer allows you to add files to the setup project from locations such as the projects inside your solution or loose files from your file-system.
Figure 4. Solution Explorer for ExcelAddInSetup
The setup project needs to deploy the ExcelAddIn DLL. You can configure the setup project for this task by adding the ExcelAddIn project output to the setup project.
To add the ExcelAddIn project output
In the Solution Explorer, right-click ExcelAddInSetup, click Add and then Project Output.
In the Add Project Output Group dialog box, confirm that the ExcelAddIn project is selected, and the Primary Output option is selected.
Click Open to add the project output to the setup project.
Figure 5. ExcelAddInSetup Dependencies
The setup project needs to deploy the deployment manifest and application manifest. You can add these two files to the setup project as stand-alone files from the output folder of the ExcelAddIn project.
To add the deployment and application manifests
In the Solution Explorer, right-click ExcelAddInSetup, click Add, and click File.
In the Add Files dialog box, navigate to the ExcelAddIn output directory. Usually the output directory is the bin\release subfolder of the project root directory, depending on the selected build configuration.
Select the ExcelAddIn.vsto and ExcelAddIn.dll.manifest files and click OK to add these two files to the setup project.
Figure 6. ExcelAddIn Manifests
The downside of adding loose files to a setup project is that you reference the default output folder of the Release build configuration explicitly. When you change the build configuration back to Debug, the setup project still references the files from this folder. Because you should only distribute release builds this is acceptable. Alternatively, you can configure the Debug and Release build configuration to output their files to the same directory.
Referencing the ExcelAddIn includes all the components that ExcelAddIn requires. These components must be excluded and deployed using prerequisite packages to allow them to be registered correctly. Also, the Software License Terms must be displayed and accepted before the installation begins.
To exclude the ExcelAddIn project dependencies
In the Solution Explorer, in the ExcelAddInSetup node, select all dependency items beneath the Detected Dependencies item except for Microsoft .NET Framework.
Right-click the group and select Properties.
In the Properties window, change the Exclude property to True to exclude the dependent assemblies from the setup project.
Figure 7. Excluding Dependencies
Your Windows Installer package should install the prerequisite components. The setup project can include and install the redistributables provided by the component vendors, a process called bootstrapping. For the ExcelAddIn, the following prerequisites must be installed before the add-in can run correctly.
- Microsoft .NET Framework 3.5
- Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime)
- Redistributable Primary Interop Assemblies for the 2007 Microsoft Office system.
- Windows Installer 3.1
For the Redistributable Primary Interop Assemblies for the 2007 Microsoft Office system to appear in Visual Studio 2008, you must perform the steps detailed in
Preparing your Development Computer.
To configure dependent components as prerequisites
In the Solution Explorer, right-click the ExcelAddInSetup project and select Properties.
The ExcelAddInSetup Property Pages dialog box appears.
Click Prerequisites.
In the Prerequisites dialog box, perform the following tasks.
- Select Create setup program to install prerequisite components. This creates the setup.exe bootstrapper together with the MSI file.
- In the Choose prerequisites to install list, select the following:
Windows Installer 3.1
.NET Framework 3.5
2007 Microsoft Office Primary Interop Assemblies
Visual Studio Tools for the Office system 3.0 Runtime
- For Specify the install location for prerequisites, select Download prerequisites from the same location as my application.
- Click OK to close the Prerequisites dialog box
- Click OK to close the property pages of ExcelAddInSetup.
| Note: |
|---|
| You cannot download the Redistributable Primary Interop Assemblies package for the 2007 Microsoft Office system from the internet as part of the MSI installation. Doing so skips the Microsoft Software License Terms acceptance step that allows you to redistribute the package. Your installation options are to pre-install the PIA package (and exclude the package in the setup), download from the same location as the setup, or download from a separate network location. This procedure uses the second option.
|
Figure 8. Prerequisites Dialog Box
| Note: |
|---|
| The configured prerequisite packages in your Visual Studio 2008 Setup Project are dependent on the selected build configuration. You must select the right prerequisite components for each build configuration that you use. The samples and procedures only use the default Release build configuration.
|
Microsoft Office locates the application-level add-in by using registry keys in the HKEY_CURRENT_USER hive. The Visual Studio setup project is capable of configuring the required registry keys.
| Note: |
|---|
| The keys live in a user specific key hive, which makes the add-in available only to the user running the setup.
|
To configure the registry
In the Solution Explorer, right-click ExcelAddInSetup.
Expand View.
Click Registry to open the registry editor window.
In the Registry(ExcelAddInSetup) editor, expand HKEY_LOCAL_MACHINE and then Software.
Delete the [Manufacturer] key found under HKEY_LOCAL_MACHINE\Software. This key is automatically added when the setup project is created and is not used by the add-in.
Expand HKEY_CURRENT_USER and then Software.
Delete the [Manufacturer] key found under HKEY_CURRENT_USER\Software. This key is also added automatically and isn’t used by the add-in.
Right-click the Software key under HKEY_CURRENT_USER, select New and then Key. Use the text Microsoft for the name of the new key.
Use a similar process to create the entire key hierarchy required for the add-in registration. The following key hierarchy is used for the ExcelAddIn add-in.
HKEY_CURRENT_USER\Software\Microsoft\Office\Excel\Addins\SampleCompany.ExcelAddIn
| Note: |
|---|
| The name of your company is used as a prefix for the name of the add-in. This provide uniqueness for this part of the registry key and allows add-ins with similar names originating from different suppliers to work without accidentally overwriting each other's registration keys. This does not provide full uniqueness but should suffice to prevent collisions.
|
Right-click the SampleCompany.ExcelAddIn key, select New and click String value. Use the text Description for the new value.
Use this step to add three more values. Use the following names and data type.
- FriendlyName of type String
- LoadBehavior of type DWORD
- Manifest of type String
Right-click the Description value in the registry editor and click Properties Window. In the Properties Window enter Excel Demo AddIn for the Value property.
Select the FriendlyName key in the registry editor. In the Properties Window, change the Value property to Excel Demo AddIn.
Select the LoadBehavior key in the registry editor. In the Properties Window, change the Value property to 3.
The value 3 for the LoadBehavior value indicates that the add-in should be loaded at startup of the host application.
Select the Manifest key in the registry editor. In the Properties Window, change the Value property to [TARGETDIR]ExcelAddIn.vsto|vstolocal
Figure 9. Registry Keys setup
| Note: |
|---|
| There are a few interesting notes on how the Visual Studio Tools for Office locates the add-in. Visual Studio Tools for Office searches for the deployment manifest indicated by the Manifest value. The [TARGETDIR] part is a macro that the Windows Installer expands to the actual folder where the add-in is installed. This macro expands to include the trailing \ character, so the filename of the deployment manifest is appended as ExcelAddIn.vsto without the \ character. Finally there is the use of the vstolocal postfix. This tells the Visual Studio Tools for Office runtime that the add-in should load from the location indicated by the Manifest value, and not loaded into the ClickOnce cache. Removing this postfix will cause the runtime to copy the customization into the ClickOnce cache.
|
In the Registry (ExcelAddInSetup) editor, right-click the SampleCompany.ExcelAddIn key and click Properties Windows.
In the Properties window, set the value of DeleteAtUninstall to True to ensure that the registry keys are deleted when the Visual Studio Tools for Office add-in is uninstalled.
Figure 10. Registry Keys Properties Window
 Warning: |
|---|
| You should be very careful with the Registry Editor in Visual Studio. For example, if you accidentally set DeleteAtUninstall for the wrong key, you might delete an active part of the registry, leaving the user computer in an inconsistent, or even worse, broken state.
|
When the user does not execute the setup bootstrapper (setup.exe), it is possible that the MSI package will install on a computer without the required prerequisites. Launch conditions are used to prevent the ExcelAddIn from installing on computers without installed prerequisites.
To see if the Visual Studio Tools for Office runtime is installed, check a registry key on the user computer. To see if the Redistributable Primary Interop Assemblies for the 2007 Microsoft Office system are installed, check for the component ID of the interop assemblies required for your solution. The ExcelAddIn requires the Microsoft Excel and Office Shared PIAs.
To configure launch conditions
In Solution Explorer, right-click ExcelAddInSetup.
Expand View.
Click Launch Conditions.
In the Launch Conditions(ExcelAddInSetup) editor, right-click Requirements on Target Machine, and then click Add Registry Launch Condition. This search condition searches the registry for a key the Visual Studio Tools for Office runtime installs. The value of the key is then available to the various pieces of the installer through a named property. The launch condition uses the property defined by the search condition to check for a certain value.
In the Launch Conditions(ExcelAddInSetup) editor, select the Search for RegistryEntry1 search condition, right-click the condition and select Properties Window.
In the Properties window, perform the following tasks.
- Set the value of (Name) to Search for VSTO 3.0 Runtime.
- Change the value of Property to VSTORUNTIME.
- Set the value of RegKey to Software\Microsoft\vsto runtime Setup\v9.0.21022
- Leave the Root property set to vsdrrHKLM.
- Change the Value property to Install.
Figure 11. Launch Conditions Properties Window – Search for Runtime
In the Launch Conditions(ExcelAddInSetup) editor, select the Condition1 launch condition, right-click the condition and select Properties Window.
In the Properties window, perform the following tasks.
- Set (Name) to Verify VSTO 3.0 Runtime availability.
- Change the value of the Condition property to the following VSTORUNTIME = "#1"
- Leave the InstallURL property blank.
- Change the value of the Message property to The Visual Studio Tools for Office 3.0 Runtime is not installed. Please run Setup.exe.
Figure 12. Launch Conditions Properties Window – Verify Runtime Availability
In the Launch Conditions(ExcelAddInSetup) editor, right-click Requirements on Target Machine, and then click Add Windows Installer Launch Condition. This launch condition searches for the Microsoft Office Excel 2007 Primary Interop Assembly by searching for the specific component ID.
Right-click Search for Component1 and click Properties Window to show the properties of the launch condition.
In the Properties window, change the values of the following properties.
- Set the value of the (Name) property to Search for Office Excel 2007 PIA
- Set the value of the ComponentID property to {1ABEAF09-435F-47D6-9FEB-0AD05D4EF3EA}.
- Set the value of the Property property to HASEXCELPIA.
Figure 13. Launch Conditions Properties Window - Search for Excel PIA
In the Launch Conditions(ExcelAddInSetup) editor, right-click Condition1 and click Properties Window to show the properties of the launch condition.
Set the properties of Condition1 using the following information:
- Set (Name) to Verify Excel 2007 PIA availability.
- Set Condition to HASEXCELPIA.
- Leave InstallUrl blank.
- Set Message to A required component for interacting with Excel 2007 is not available. Please run setup.exe.
Figure 14. Launch Conditions Properties Window - Verify PIA availability
In the Launch Conditions(ExcelAddInSetup) editor, right-click Requirements on Target Machine, and then click Add Windows Installer Launch Condition. This launch condition searches for the Microsoft Office 2007 Shared Primary Interop Assembly by searching for the specific component ID.
Right-click Search for Component1 and click Properties Window to show the properties of the launch condition.
In the Properties Window, change the values of the following properties:
- Set the value of the (Name) property to Search for Office 2007 Shared PIA
- Set the value of the ComponentID property to {FAB10E66-B22C-4274-8647-7CA1BA5EF30F}.
- Set the value of the Property property to HASSHAREDPIA.
Figure 15. Launch Conditions Properties Window - Search for Office Shared PIA
In the Launch Conditions(ExcelAddInSetup) editor, right-click Condition1 and click Properties Window to show the properties of the launch condition.
Set the properties of Condition1 using the following information:
- Set (Name) to Verify Office 2007 Shared PIA availability.
- Set Condition to HASSHAREDPIA.
- Leave InstallUrl blank.
- Set Message to A required component for interacting with Excel 2007 is not available. Please run setup.exe.
Figure 16. Launch Conditions Properties Window - Verify Office Shared PIA
The final set of launch conditions should resemble the following image.
Figure 17. Final Launch Conditions
| Note: |
|---|
| You can further refine the launch conditions for the ExcelAddIn installation. For instance, it is useful to verify if the actual target Office application is installed because each individual component can be disabled by the user.
|
Because the 2007 Microsoft Office system no longer supports the registration of add-ins in the HKEY_LOCAL_MACHINE registry hive, you can no longer install the add-in for all-users. The control that allows the selection of all-users or the current-user during the installation procedure should be hidden.
To configure a single-user installation
In the Solution Explorer, right-click the ExcelAddInSetup project, expand View and select User Interface.
In the User Interface (ExcelAddInSetup) editor, right-click Installation Folder and select Properties Window.
In the Properties window, set the value of the InstallAllUsersVisible property to False.
Figure 18. Single User Installation
To allow non-administrative users to install the Visual Studio Tools for Office solution, you need to verify that no files are copied to folders that are restricted to the user. The application data folder for the user is a suitable place to install the solution.
To change the default installation folder
In Solution Explorer, right-click the Setup project, expand View and click File System.
In the File System Editor, right-click the Application Folder node and click Properties Window.
In the Properties window, set DefaultLocation to [AppDataFolder][Manufacturer]\[ProductName]. Note the slash between the manufacturer and product name.
Figure 19. Default Installation Folder
If you downloaded a language pack for the Visual Studio Tools for Office runtime you should select the appropriate language in the setup project properties. Selecting the language for the setup project provides localized messages during the setup process as well as for the Visual Studio Tools for Office runtime.
To deploy a language pack
In the Solution Explorer, click the ExcelAddInSetup project.
In the Properties window, for the Localization property, select the language that you want to use. Note that this should be a language that you have already downloaded to the appropriate location in the bootstrapper directory.
Figure 20. Language Pack Properties
The setup project is not compiled as part of a general solution compilation because the build can take a long time on larger projects. You need to manually compile the setup project and copy the resulting files to an accessible location.
To build the setup project
In the Solution Explorer, right-click the ExcelAddInSetup project and click Build.
Using Windows Explorer, navigate to the output directory of the ExcelAddInSetup project found in the VSTO v3 Deployment Demo\ExcelAddInSetup\Release folder. Copy all files to a location that users can access. Sample locations include a network share, CD or USB stick.
It is a good idea to test the basic setup before you add more advanced features to the setup project. You should perform the following steps on a test computer where the add-in is not installed.
To test the ExcelAddIn setup
Navigate to the location where you copied ExcelAddInSetup in the previous procedure.
Right-click the setup.exe file and click Open to install the ExcelAddInSetup add-in. Accept any Software License Terms that appear, and complete the setup wizard to install the add-in on the user computer.
When setup.exe is executed, the required prerequisite packages are not available yet on the target computer. These prerequisites are installed before the MSI with the ExcelAddIn customization is installed. The verification of prerequisite components using launch conditions is part of the MSI. Hence the configured launch conditions are checked after the installation of prerequisite components. This allows you to prepare the target computer before the MSI is executed.
Because the user can bypass the installation of prerequisite components by not executing setup.exe but by executing the MSI directly, the MSI checks the target computer using the launch conditions. One visible side-effect is that you might be presented with a user interface pertaining to the installation of the primary interop assemblies for the 2007 Microsoft Office system before the user interface for the installation of your Visual Studio Tools for Office solution is displayed.
You can create the trust relationship as part of the installation process because running the setup project is considered a trust decision.
Perform the following procedure on a separate test computer.
To test the ExcelAddIn
Open Excel. You are presented with a trust prompt asking whether it is safe to execute the add-in.
Click Install in the Microsoft Office Customization Installer dialog box to trust and run the add-in. The following section uses other methods to define the trust relationship between Excel and your add-in.
Figure 21. Microsoft Office Customization Installer
| Note: |
|---|
| This dialog box is somewhat misleading for Visual Studio Tools for Office add-ins that can be locally installed using Windows Installer. The add-in is actually already installed, but it is not trusted to run yet by the user. For locally installed add-ins the Install button does not install the add-in, but it creates the trust-relationship to allow the add-in to execute.
|
The add-in is executed.
Figure 22. Hello World
Known Issues
There is an issue with Visual Studio 2008 RTM and registry keys for application-level add-ins. If the registry key name used for the Visual Studio Tools for Office solution and the name of Visual Studio Tools for Office project inside Visual Studio are the same, then during build time Visual Studio 2008 overwrites the value for the manifest so it matches the Visual Studio 2005 SE manifest format. To avoid this issue make sure that the registry key name differs from the project name such as CompanyName.AddinName. This issue is resolved with Visual Studio 2008 SP1.
Conclusion
This article provides an overview of deploying a Visual Studio Tools for Office solution using a Visual Studio 2008 Windows Installer package. This article provides a walkthrough to show how you can install the prerequisites (the .NET Framework 3.5, the VSTO 3.0 runtime, and the Office primary interop assemblies), add the project output and manifests, create registry keys to load an application-level add-in, and use the ClickOnce prompt to grant trust to your solution.
To expand your installer to also handle trust, deploy additional components, and deploy document-level solutions, see the walkthrough examples in Deploying a Visual Studio Tools for the Office System 3.0 Solution for the 2007 Microsoft Office System using Windows Installer (Part 2 of 2). In addition, the second article discusses how to modify the Setup project for Vista and provides a list of known issues that you may encounter during the process.
The samples in this article include the walkthrough in Deploying a Visual Studio Tools for the Office System 3.0 Solution for the 2007 Microsoft Office System using Windows Installer (Part 1 of 2) and the three walkthroughs in Deploying a Visual Studio Tools for the Office System 3.0 Solution for the 2007 Microsoft Office System using Windows Installer (Part 2 of 2).
Additional Resources
Deploying Solutions for 2007 Office System with ClickOnce Using Visual Studio Tools for the Office System (3.0)
Specifying Form Regions in the Windows Registry
About the Authors
Wouter van Vugt is a Microsoft MVP with Office Open XML technologies and an independent consultant focusing on creating Office Business Applications (OBAs) with SharePoint, the Office 2007 system and related .NET technologies. Wouter is a frequent contributor to developer community sites such as
OpenXmlDeveloper.organd
MSDN. He has published several white papers and articles as well a book available on line titled
Open XML: Explained e-book. Wouter is the founder of Code-Counsel, a Dutch company focusing on delivering cutting-edge technical content through a variety of channels. You can find out more about Wouter by reading his
blog and visiting the
Code-Counsel Web site.
Ted Pattison is a SharePoint MVP, author, trainer and the founder of Ted Pattison Group. In the fall of 2005, Ted was hired by Microsoft’s Developer Platform Evangelism group to author the Ascend developer training curriculum for Windows SharePoint Services 3.0 and Microsoft Office SharePoint Server 2007. Since that time, Ted has been entirely focused on educating professional developers on SharePoint 2007 technologies. Ted has just finished writing a book for Microsoft Press titled Inside Windows SharePoint Services 3.0 that focuses on how to use SharePoint as a development platform for building business solutions. Ted also writes a developer-focused column for MSDN Magazine titled Office Space.
