Export (0) Print
Expand All

Walkthrough: Deploying a Document-Level Customization Using a Windows Installer File

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005

    -or-

    Visual Studio Team System

  • Microsoft Office 2003

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 Office Solutions Architecture Overview.

During this walkthrough, you will learn how to:

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

  • Modify the Setup project so that the Windows Installer file installs your Microsoft Visual Studio 2005 Tools for the Microsoft Office System solution.

  • Add 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 more information about the prerequisites for running Visual Studio Tools for Office solutions, see How to: Prepare End User Computers to Run Office Solutions.

NoteNote

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 further information about security in Visual Studio Tools for Office solutions, see Security Requirements to Run Office Solutions and Best Practices for Security in Office Solutions. For information about setting security policy on end user computers, see Deploying Security Policy.

To complete this walkthrough, you will need:

  • Visual Studio Tools for Office.

  • Microsoft Office Word 2003 or Microsoft Office Excel 2003.

    NoteNote

    This walkthrough includes steps for building a simple Excel solution that you can use in the walkthrough. 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 be sure to replace the project name ExcelDeployment with the name of your project in all code examples and instructions.

In this step, you will create an Excel Workbook project.

To create a new project

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

In this step, you will add a message box to the Startup event handler of the workbook. This enables you to quickly verify that the solution is working when you open the document.

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

Next, you will add a Setup project to your solution.

In this step, you will create a Setup project 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.

In this step, you will add the primary output of the ExcelDeployment project to the Setup project. The primary output of the ExcelDeployment project consists of the workbook and the solution assembly.

To add the document and assembly to the Setup project

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

  2. Select 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.

In this step, you will create a project that contains custom actions for your Setup project. Custom actions are a Windows Installer feature. You can use them to run code at the end of an installation 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.

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 installation, 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, 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.

    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.

    // 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.

In this step, you will add the primary output of the ExcelCustomAction 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

  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.

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

To test the installation

  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.

Community Additions

ADD
Show:
© 2014 Microsoft