This section describes how to create a Windows Installer package for Excel or Word document-based solutions. Although the example shows you how to deploy an Excel solution, you can use the same steps to deploy a Word solution. To perform this walkthrough, your development computer needs to have Office 2003 installed with VSTO 2005 SE. However, you can install the solution on a computer that has Office 2007 installed.
This walkthrough shows how to perform the following steps:
- Create a Setup project that you can use to build the bootstrapper and the Windows Installer package.
- Modify the Setup project so that the Windows Installer file installs your VSTO 2005 SE solution.
- Add the prerequisites.
- Add a custom action to grant security trust to the customization assembly.
- Add a custom action to edit the application manifest that is embedded in the solution document.
Creating the Project
In this step, you create an Excel Workbook project in Visual C#.
To create a new project
-
Create an Excel Workbook project in Visual C# with the name ExcelApplication.
-
Verify that you have selected Create a new document.
Visual Studio opens the new Excel workbook in the designer and adds the ExcelApplication project to Solution Explorer.
Signing the Assembly
Later in this article, you grant trust to the customization assembly based on a strong name and the assembly location. Before you can grant trust, you must sign the assembly.
To sign the assembly
-
In Solution Explorer, right-click ExcelApplication, and then click Properties.
-
Click the Signing tab.
-
Select the Sign the assembly check box.
-
In the Choose a strong name key file list, click <New. . .>.
-
Type ExcelApplication in the Key file name box.
-
Type a password in the Enter password and Confirm password boxes.
-
Click OK.
-
Close the Properties page.
Adding Code Behind the Workbook
In this step, you add a message box to the Microsoft.Office.Tools.Excel.Workbook.Startup event handler of the workbook. This enables you to verify that the solution is working when you open the document.
To add a message box to an initialization event
-
In Solution Explorer, right-click ThisWorkbook.cs, and then click View Code.
-
Add the following code to the ThisWorkbook_Startup event handler inside the ThisWorkbook class to show a message box during initialization.
private void ThisWorkbook_Startup(object sender, System.EventArgs e)
{
MessageBox.Show("The document has been deployed successfully.");
}
-
Press F5 to run the project.
Excel starts and the message box appears.
-
Close the message box, and then exit Excel.
Creating a Setup Project
In this step, you create a Setup project that you can compile to create a Windows Installer file for your solution.
To create a Setup project for your solution
-
In Solution Explorer, right-click Solution, point to Add, and then click New Project.
The Add New Project dialog box appears.
-
In the Project Types pane, expand Other Project Types, and then select Setup and Deployment.
-
In the Templates pane, select Setup project.
-
Name the project ExcelApplicationSetup.
-
Click OK.
The Setup project appears in Solution Explorer. By default, the Windows Installer file that you build by using this Setup project includes a dialog box that enables the user to specify the installation location of the solution.
Adding the Workbook and Solution Assembly to the Setup Project
In this step, you add the primary output of the ExcelApplication project to the Setup project. The primary output of the ExcelApplication project consists of the workbook and the solution assembly.
To add the workbook and assembly to the Setup project
-
In Solution Explorer, right-click ExcelApplicationSetup.
-
Point to View on the shortcut menu, and then click File System.
-
Right-click Application Folder in the left pane.
-
Point to Add on the shortcut menu, and then click Project Output.
-
In the Project box, select ExcelApplication.
-
In the list of output types, select Primary output.
-
Click OK.
The project output and dependencies appear in the right pane.
When you add the primary output of a project to the Setup project, Visual Studio detects the dependencies. These dependencies can appear as a list of separate DLLs. Next, exclude these DLL dependencies, because they are part of the prerequisite packages and you add the packages as dependencies later.
To exclude the DLL dependencies
-
In Solution Explorer, under the ExcelApplicationSetup node, expand Detected Dependencies.
-
Right-click every dependency except Microsoft .NET Framework, and then click Exclude.
Adding the Prerequisites to the Setup Project
This step assumes you have prepared your development environment as described in http://msdn.microsoft.com/en-us/library/bb332051(v=office.12).aspx.
There are two ways to start the setup process:
- Setup.exe
When Setup.exe runs, the bootstrapper executes first. It examines the list of prerequisites needed by the application and installs them if necessary. After the prerequisites are installed, the .msi file is processed, which performs the actual installation of the application.
 Important: |
| 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).
|
- An .msi file
When this executable file launches, the bootstrapper does not execute and the prerequisites are not installed. However, it is possible to add launch conditions that prevent installation when the prerequisites are not present.
Add the prerequisites that the bootstrapper installs. You add launch conditions in a later step.
To add the prerequisites
-
In Solution Explorer, right-click ExcelApplicationSetup.
-
Click Properties.
-
In the Property Pages dialog box, click Prerequisites.
-
In the list of prerequisites, select the following items:
- Microsoft Office 2003 Primary Interop Assemblies
- 2007 Microsoft Office Primary Interop Assemblies
- Microsoft Visual Studio Tools for Office SE Runtime
-
Select Microsoft Visual Studio 2005 Tools for Office Runtime Language Pack, if any users run your solutions with non–English settings for Microsoft Windows.
These users must have the Visual Studio 2005 Tools for Office Language Pack to see runtime messages in the same language as Windows.
-
Click OK twice.
Adding a Custom Action to Grant Trust to the Assembly
Before a Visual Studio Tools for Office solution can run, the customization assembly must have FullTrust permissions. The sample custom action included in the source code that accompanies this article demonstrates how to grant permissions to the assembly that is installed on the user's computer.
To add the custom action project to the solution
-
Using Windows Explorer, copy the SetSecurity project from the {SamplesDir}\projects directory to the directory that contains the ExcelApplication solution.
 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\
|
-
In Solution Explorer, right-click ExcelApplication.
-
Point to Add on the shortcut menu, and then click Existing Project.
-
Select the SetSecurity project.
-
Click OK.
-
In Solution Explorer, right-click the SetSecurity project, and then click Build.
To add the primary output of the custom action project to the Setup project
-
In Solution Explorer, right-click ExcelApplicationSetup.
-
Point to View on the shortcut menu, and then click Custom Actions.
-
In the Custom Actions editor, right-click the Custom Actions node, and then click Add Custom Action.
-
In the Look In list, click Application Folder, and then click Add Output.
The Add Project Output Group dialog box opens.
-
In the Project list, click SetSecurity.
-
In the list of output types, select Primary output, and then click OK.
-
Verify that Primary output from SetSecurity (Active) is in the list of primary outputs for the Setup project, and then click OK.
To add the custom action data for the Install method
-
In the Custom Actions editor, expand Install.
-
Right-click Primary output from SetSecurity (Active), and then click Properties Window.
-
In the Properties window, set the CustomActionData property to the following string. Enter this as one long string, and changeMyCompanyName to your company name.
/assemblyName="ExcelApplication.dll" /targetDir="[TARGETDIR]\"
/solutionCodeGroupName="MyCompanyName.ExcelApplication"
/solutionCodeGroupDescription="Code group for ExcelApplication"
/assemblyCodeGroupName="ExcelApplication"
/assemblyCodeGroupDescription="Code group for ExcelApplication"
/allUsers=[ALLUSERS]
| Tip: |
| You do not need to add extra quotation marks if your company name contains a space.
|
To add the custom action data for the Rollback method
-
In the Custom Actions editor, expand Rollback.
-
Right-click Primary output from SetSecurity (Active), and then click Properties Window.
-
In the Properties window, set the CustomActionData property to the following string:
/solutionCodeGroupName="MyCompanyName.ExcelApplication"
To add the custom action data for the Uninstall method
-
In the Custom Actions editor, expand Uninstall.
-
Right-click Primary output from SetSecurity (Active), and then click Properties Window.
-
In the Properties window, set the CustomActionData property to the following string:
/solutionCodeGroupName="MyCompanyName.ExcelApplication"
| Note: |
| Although the custom action does not override the Commit method, the base Windows Installer class provides an implementation. Thus, you must still call the method. However, it does not require any custom action data.
|
Adding a Custom Action to Update the Location of the Assembly
When you pressed F5 earlier to run your project, the build process edited the application manifest embedded in the workbook to point to the relative path of the assembly. If the workbook and the assembly remain in the same folder after installation, then you do not have to modify the embedded application manifest, and you can ignore this section. However, if you do 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 template projects and Word template projects because the workbook or document created from a template typically resides in a location that is different from the template location.
A sample custom action has been created for you. Add this custom action to the Setup project.
To add the custom action project to the solution
-
Using Windows Explorer, copy the UpdateManifest project from the {SamplesDir}\projects directory to the directory that contains the ExcelApplication solution.
-
In Solution Explorer, right-click ExcelApplication.
-
Point to Add on the shortcut menu, and then click Existing Project.
-
Select the UpdateManifest project.
-
Click OK.
-
In Solution Explorer, right-click the UpdateManifest project, and then click Build.
-
Add the primary output of the UpdateManifest project to the Setup project.
This enables the Windows Installer file to run the custom action that edits the application manifest.
To add the primary output of the custom action project to the Setup project
-
In Solution Explorer, right-click ExcelApplicationSetup.
-
Point to View on the shortcut menu, and then click Custom Actions.
-
In the Custom Actions editor, right-click the Custom Actions node, and then click Add Custom Action.
-
In the Look In list, click Application Folder, and then click Add Output.
The Add Project Output Group dialog box opens.
-
In the Project list, click UpdateManifest.
-
In the list of output types, select Primary output, and then click OK.
-
Verify that Primary output from UpdateManifest (Active) is in the list of primary outputs for the Setup project, and then click OK.
-
Add the required custom action data.
| Note: |
| Although the custom action does not override the Commit, Rollback, and Uninstall methods, the base Windows Installer class provides an implementation. Thus, the methods must be called. However, they do not require any custom action data.
|
To add the custom action data for the Install method
-
In the Custom Actions editor, expand Install.
-
Right-click Primary output from UpdateManifest (Active), and then click Properties Window.
-
In the Properties window, set the CustomActionData property to the following string. Enter this as one long string.
/targetDir="[TARGETDIR]/" /documentName="ExcelApplication.xls" /assemblyName="ExcelApplication.dll"
Adding Launch Conditions to the .msi File
When the user runs Setup.exe, Windows Installer checks for the prerequisites and installs them if necessary. Alternatively, the user can double-click the .msi file to install the solution. In that case, the prerequisites are not installed and the solution cannot run. In other cases, Setup might fail because resources it needs are not present; for example, custom actions might require the .NET Framework.
This section shows you how to use the Launch Conditions editor to add launch conditions to the .msi file to prevent installation when certain dependencies are not installed.
To view the Launch Conditions editor
-
In Solution Explorer, right-click ExcelApplicationSetup.
-
Point to View on the shortcut menu, and then click Launch Conditions.
-
Add a launch condition for the Visual Studio 2005 Tools for Office runtime.
To add a launch condition for the VSTO 2005 SE runtime
-
In the Launch Conditions editor, right-click Requirements on Target Machine, and then click Add Registry Launch Condition.
-
Select the newly added search condition, Search for RegistryEntry1.
-
Rename the search condition to Search for VSTO 2005 SE Runtime.
-
In the Properties window, change the value of Property to VSTORTVERSION.
-
Also in the Properties window, set the value of RegKey to the following string:
Software\Microsoft\vsto runtime Setup\v2.0.50727
-
Leave the Root property set to vsdrrHKLM.
-
Change the Value property to Update.
-
Select the newly added launch condition, Condition1.
-
Rename it to Display message if the Visual Studio 2005 Tools for Office SE Runtime is not installed.
-
In the Properties window, change the value of the Condition property to the following:
VSTORTVERSION >= "#3"
-
Leave the InstallURL property blank.
-
Change the value of the Message property to The Visual Studio 2005 Tools for Office SE Runtime is not installed. Please run Setup.exe.
If any users run your solutions with non–English settings for Windows, they must have the Visual Studio 2005 Tools for Office Language Pack to see runtime messages in the same language as Windows. Add a launch condition to check for the Language Pack.
To add a launch condition for the Visual Studio 2005 Tools for Office Language Pack
-
In the Launch Conditions editor, right-click Requirements on Target Machine, and then click Add Windows Installer Launch Condition.
-
Select the newly added search condition, Search for Component1.
-
Rename the search condition to Search for VSTO Language Pack.
-
In the Properties window, in the ComponentId property, type the following GUID:
{2E3A394E-C9BD-40C3-9990-BA7AF7C8B4AF}
-
Change the value of Property to COMPONENTEXISTS_VSTOLP.
-
Select the newly added launch condition, (Condition1).
-
Rename it to Display message if the Visual Studio 2005 Tools for Office Language Pack is not installed.
-
In the Properties window, change the value of the Condition property to COMPONENTEXISTS_VSTOLP.
-
Leave the InstallURL property blank.
-
Change the value of the Message property to The Visual Studio 2005 Tools for Office Language Pack is not installed. Please run Setup.exe.
Testing the Installation
To test your Windows Installer, run it on a computer other than your development computer, because many of the prerequisites are already installed. Build your Setup project, and then run the Setup.exe file to test the bootstrapper.
To build the project