Walkthrough: Deploying a Document-Level Customization Using a Windows Installer File (2003 System)

  • Article

Applies to

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Project type

  • Document-level projects

Microsoft Office version

  • Microsoft Office 2003

For more information, see Features Available by Application and Project Type.

This walkthrough demonstrates how to create a Microsoft Windows Installer (.msi) file that can be used to deploy a document-level customization. For more information about document-level customizations, see Architecture of Document-Level Customizations.

This walkthrough illustrates the following tasks:

  • Creating a Setup project that you can use to build a Windows Installer file.

  • Modifying the Setup project so that the Windows Installer file installs your Visual Studio Tools for Office solution.

  • Adding a step to the Setup project so that the Windows Installer file edits the application manifest embedded in the Visual Studio Tools for Office solution document.

This walkthrough assumes that the target computer already has the prerequisites installed for running Visual Studio Tools for Office solutions. The Windows Installer file you build does not check for or install these prerequisites. For information about how to install the prerequisites, see Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer. For information about what the prerequisites are for running Visual Studio Tools for Office solutions, see How to: Prepare End User Computers to Run Office Solutions (2003 System). 

Note

Assemblies in Visual Studio Tools for Office solutions must be granted full trust in the security policy of the end user before the solution will run. The Windows Installer file you build in this walkthrough does not deploy the security policy required to run the solution. For information about how to add a custom action to grant trust to the customization assembly, see Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer. For information about security in Visual Studio Tools for Office solutions, see Security Requirements to Run Office Solutions (2003 System) and Best Practices for Security in Office Solutions (2003 System). For information about setting security policy on end user computers, see Deploying Security Policy.

Prerequisites

You need the following components to complete this walkthrough:

  • Visual Studio Tools for Office (an optional component of Visual Studio 2008 Professional and Visual Studio Team System).

  • Microsoft Office Word 2003 or Microsoft Office Excel 2003.

Creating the Project

In this step, create an Excel Workbook project. If you want to perform the walkthrough with an existing Word or Excel solution, begin the walkthrough at the heading "Creating the Setup Project", and replace the project name ExcelDeployment with the name of your project in all code examples and instructions.

To create a new project

Visual Studio opens the new Excel workbook in the designer and adds the ExcelDeployment project to Solution Explorer.

Adding Code Behind the Workbook

The project needs some code so you can verify that the solution is working when you open the document. For this walkthrough, add a message box to the Startup event handler of the workbook.

To add a message box to an initialization event

  1. In Solution Explorer, right-click ThisWorkbook.vb or ThisWorkbook.cs, and then click View Code on the shortcut menu.

  2. Add the following code to the Startup event handler inside the ThisWorkbook class to show a message box during initialization.

    Private Sub ThisWorkbook_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Startup

    MessageBox.Show("The workbook is deployed successfully.")
End Sub

    private void ThisWorkbook_Startup(object sender, System.EventArgs e)
{
    MessageBox.Show("The workbook is deployed successfully.");
}

  3. Press F5 to run the project.

    Excel starts and the message box appears.

  4. Close the message box.

  5. Exit Excel.

Creating a Setup Project

Setup projects provide files and code that you can compile to create a Windows Installer file for your solution. For more information, see Setup Projects.

To create a Setup project for your solution

  1. Right-click the solution node in Solution Explorer.

  2. Point to Add on the shortcut menu, and then click New Project.

    The Add New Project dialog box appears.

  3. In the Project types pane, expand Other Project types and select Setup and Deployment.

  4. In the Templates pane, select Setup project.

  5. Name the project ExcelSetup.

  6. Click OK.

    The Setup project appears in Solution Explorer. By default, the Windows Installer file that you will build using this Setup project includes a dialog box that enables the end user to specify the installation location of the solution. For more information, see Installation Folder User Interface Dialog Box.

Adding the Workbook and Solution Assembly to the Setup Project

The primary output of the ExcelDeployment project consists of the workbook and the solution assembly. Add these components to the Setup project.

To add the document and assembly to the Setup project

  1. Right-click the ExcelSetup project node in Solution Explorer.

  2. Point to View on the shortcut menu, and then click File System.

  3. Right-click Application Folder in the left pane.

  4. Point to Add on the shortcut menu, and then click Project Output.

  5. Select ExcelDeployment in the Project box.

  6. Select Primary output in the list of output types.

  7. Click OK.

    The project output and dependencies appear in the right pane.

  8. In Solution Explorer, expand Detected Dependencies under the ExcelSetup project node.

  9. Right-click every dependency except for Microsoft .NET Framework, and click Exclude in the shortcut menu.

Creating a Custom Action Project

Custom actions are a Windows Installer feature. You can use them to run code at the end of the installation process to perform actions that cannot be performed during installation. For more information, see Custom Actions.

To create a custom action project

  1. Right-click the solution node in Solution Explorer.

  2. Point to Add on the shortcut menu, and then click New Project.

    The Add New Project dialog box appears.

  3. In the Project types pane, expand the node for your programming language, and select Windows.

  4. In the Templates pane, select Class Library.

  5. Name the project ExcelCustomAction.

  6. Click OK.

    The new project appears in Solution Explorer.

  7. In Solution Explorer, right-click Class1.vb or Class1.cs under the ExcelCustomAction project and then click Delete. This file is unnecessary for this walkthrough.

Creating a Custom Action that Edits the Application Manifest

When you ran your project earlier in this walkthrough by pressing F5, 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 need 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 installing the solution, then you must edit the application manifest to point to the full path of the assembly.

You must update the application manifest that is embedded in the Visual Studio Tools for Office solution document by running a custom action after the installation process is done, because the location of the solution assembly is unknown until the user specifies the location during installation. Edit the embedded application manifest by using the ServerDocument class. To use the ServerDocument class in your Setup project, add code to an Installer class within the custom action project.

To create a custom action that edits the application manifest

  1. Right-click the ExcelCustomAction project in Solution Explorer.

  2. Point to Add on the shortcut menu, and then click New Item.

    The Add New Item dialog box appears.

  3. Select Installer Class, and name the class ManifestEditor.

  4. Add a reference to the Microsoft.VisualStudio.Tools.Applications.Runtime assembly to the ExcelCustomAction project.

  5. In Solution Explorer, right-click the ManifestEditor.cs or ManifestEditor.vb file and then click View Code.

  6. Add the following Imports or using statement to the top of the code file.

    Imports Microsoft.VisualStudio.Tools.Applications.Runtime

    using Microsoft.VisualStudio.Tools.Applications.Runtime;

  7. Copy the following code into the ManifestEditor class.

    This code overrides the Install method, which is used to perform custom installation actions. The code sets the installation location specified by the user to the AssemblyPath property. The user-specified installation path and the names of the document and assembly are obtained from the Parameters property.

    Public Overrides Sub Install(ByVal stateSaver As System.Collections.IDictionary)
    UpdateApplicationManifest()
    MyBase.Install(stateSaver)
End Sub 

Private Sub UpdateApplicationManifest()

    ' Get the parameters passed to the task. 
    Dim targetDir As String = Me.Context.Parameters("targetdir")
    Dim documentName As String = Me.Context.Parameters("documentname")
    Dim assemblyName As String = Me.Context.Parameters("assemblyname")

    ' Get the application manifest from the document. 
    Dim documentPath As String = System.IO.Path.Combine(targetDir, documentname)
    Dim serverDocument1 As ServerDocument = New ServerDocument(documentPath, _
            System.IO.FileAccess.ReadWrite)

    Try 
        Dim appManifest1 As AppManifest = serverDocument1.AppManifest
        Dim assemblyPath As String = System.IO.Path.Combine(targetDir, assemblyName)
        appManifest1.Dependency.AssemblyPath = assemblyPath
        serverDocument1.Save()

    Finally 
        If Not serverDocument1 Is Nothing Then
            serverDocument1.Close()
        End If 
    End Try 
End Sub

    // Override the Install method to update the customization location 
// in the application manifest. 
public override void Install(System.Collections.IDictionary stateSaver)
{
    UpdateApplicationManifest();
    base.Install(stateSaver);
}

// Update the application manifest according to the the install location. 
private void UpdateApplicationManifest()
{
    // Get the parameters passed to the task. 
    string targetDir = this.Context.Parameters["targetdir"];
    string documentName = this.Context.Parameters["documentname"];
    string assemblyName = this.Context.Parameters["assemblyname"];

    // Get the application manifest from the document. 
    string documentPath = System.IO.Path.Combine(targetDir, documentName);
    ServerDocument serverDocument1 = new ServerDocument(documentPath,
        System.IO.FileAccess.ReadWrite);

    try
    {
        AppManifest appManifest1 = serverDocument1.AppManifest;
        string assemblyPath = System.IO.Path.Combine(targetDir, assemblyName);
        appManifest1.Dependency.AssemblyPath = assemblyPath;
        serverDocument1.Save();
    }
    finally
    {
        if (serverDocument1 != null)
        {
            serverDocument1.Close();
        }
    }
}

  8. Right-click the ExcelCustomAction project in Solution Explorer, and then click Build.

Adding the Custom Action to the Setup project

Now you can enable the Windows Installer file to run the custom action that edits the application manifest. To do this, add the primary output of the ExcelCustomAction project to the Setup project.

To add the primary output of the custom action project to the Setup project

  1. Right-click the ExcelSetup project node in Solution Explorer.

  2. Point to View on the shortcut menu, and then click Custom Actions.

  3. In the Custom Actions Editor, right-click the Install node and click Add Custom Action.

  4. In the Look In box, select Application Folder, and then click Add Output.

  5. Select ExcelCustomAction in the Project box.

  6. Select Primary output in the list of output types, and then click OK.

  7. Verify that Primary output from ExcelCustomAction (Active) is added to the list of primary outputs for the Setup project, and then click OK.

  8. In the Custom Actions Editor, expand Install.

  9. Right-click Primary output from ExcelCustomAction (Active), and then click Properties Window.

  10. In the Properties window, set the CustomActionData property to the following string.

    /targetdir="[TARGETDIR]\" /documentname="ExcelDeployment.xls" /assemblyname="ExcelDeployment.dll"

    For information about the CustomActionData property, see CustomActionData Property.

  11. Right-click the ExcelSetup project in Solution Explorer, and then click Build.

Testing the Project

Now you can test the project to make sure that your solution is installed when you run the Windows Installer file on your development computer.

To test the project

  1. Right-click the ExcelSetup project in Solution Explorer, and then click Run.

  2. Follow the instructions in the setup wizard, and specify an installation folder on your development computer.

  3. Open the Excel workbook from the installation folder.

  4. Confirm that the message box appears.

See Also

Tasks

Walkthrough: Deploying a Document-Level Customization Using a Deployment Manifest (2003 System)

Concepts

Deploying Office Solutions (2003 System)

Deploying Document-Level Customizations (2003 System)

Deployment Models (2003 System)

Custom Actions

Other Resources

Windows Installer Deployment Concepts