Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Walkthrough: Deploying a Document-Level Customization Using a Deployment Manifest

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 deploy a document-level customization for Microsoft Office Excel or Microsoft Office Word to a network share on a server. At the end of the walkthrough, you will be able to run the solution on the server from your development computer. For more information about document-level customizations, see Office Solutions Architecture Overview.

In a production environment, a Microsoft Visual Studio 2005 Tools for the Microsoft Office System solution is often published first to a test server, and then it is redeployed to a production server after the IT department approves it. In this walkthrough, you will publish a solution to a temporary location on your development computer, and then redeploy the solution from the temporary location to a server. For more information about options for deploying your solution, see Deployment Models.

During this walkthrough, you will learn how to:

  • Use the Publish Wizard to publish your solution to a location on your development computer.

  • Manually redeploy the solution from your local computer to a network share on a server.

  • Programmatically modify the application manifest that is embedded in the document to point to the new deployment manifest location.

  • Edit the deployment manifest to point to the new location of the external application manifest.

  • Edit the external application manifest to point to the new assembly location and the deployment manifest.

To complete this walkthrough, you will need:

  • Visual Studio Tools for Office.

  • Microsoft Office Word 2003 or Microsoft Office Excel 2003.

    NoteNote

    This walkthrough assumes that you are deploying a Word solution. If you want to perform the walkthrough with an Excel solution, replace the name of the Word project with the name of your Excel project in all code and XML examples.

  • Access to a network server for deployment. This walkthrough assumes that you are redeploying your solution to the network share \\DeployServer\ShareFolder.

  • Administrator privileges on the development computer, so you can set the security policy for a network location.

In this step, you will create a Word Document project.

To create a new project

Visual Studio opens the new Word document in the designer and adds the WordDeployment project to Solution Explorer.

In this step, you will add a message box to the Startup event handler of the document. This will enable 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 ThisDocument.vb or ThisDocument.cs, and then click View Code on the shortcut menu.

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

    private void ThisDocument_Startup(object sender, System.EventArgs e)
    {
        MessageBox.Show("The document is deployed correctly.");
    }
    
    
  3. Press F5 to run the project.

    Word starts and the message box appears.

  4. Close the message box.

  5. Exit Word.

Next, you will publish this solution.

In this step, you will publish your solution to a temporary location on your local computer.

To publish the solution

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

  2. Click Publish on the shortcut menu.

    The Publish Wizard appears.

  3. In the Specify the location to publish this application box, type C:\TestDeploy.

  4. Click Finish.

    The solution document and deployment manifest are copied to C:\TestDeploy. The solution assembly, updated application manifest, and copies of the solution document and deployment manifest are copied to C:\TestDeploy\WordDeployment_1.0.0.0. For more information, see Deploying Document-Level Customizations.

  5. Close the WordDeployment project in Visual Studio.

    NoteNote

    The assembly does not have permission to execute yet, so if you try to run the solution it will throw an error. You will update your security policy to grant full trust permission to the assembly in a later step.

When you publish a solution, the embedded application manifest in the solution document points to the full path of the deployment manifest. If you redeploy the solution files to another location, you must update the embedded application manifest to point to the new location of the deployment manifest. You must also update the deployment manifest and the external application manifest to point to the new file locations.

To edit the embedded application manifest, use the ServerDocument class that Visual Studio Tools for Office provides. When you use the ServerDocument class, you must run your code in a new project (not your Visual Studio Tools for Office solution), such as a console project, and the Visual Studio Tools for Office solution document must be closed.

NoteNote

Visual Studio Tools for Office includes a sample that demonstrates how to create a tool that can be used to edit the embedded application manifest. For more information, see Application Manifest Editor Sample.

To update the embedded application manifest

  1. Create a new Console Application project.

  2. Add references to the Microsoft.VisualStudio.Tools.Applications.Runtime and System.Windows.Forms assemblies to this project.

  3. Open the Program.cs or Module1.vb file, and add the following Imports or using statement to the top of the file.

    using Microsoft.VisualStudio.Tools.Applications.Runtime;
    
    
  4. Copy the following code into the Main function. This code creates a ServerDocument that provides access to the embedded application manifest of your solution document. The code assigns the new deployment manifest path to the DeployManifestPath property, and then saves and closes the ServerDocument.

    ServerDocument sd = null;
    try
    {
        sd = new ServerDocument(@"C:\TestDeploy\WordDeployment.doc");
        sd.AppManifest.DeployManifestPath = 
            @"\\DeployServer\ShareFolder\WordDeployment.application";
        sd.Save();
    }
    finally
    {
        if (sd != null)
        {
            sd.Close();
        }
    }
    
    
  5. Press F5 to run the project.

    A console window appears briefly while the embedded application manifest is being updated, and then the console window closes.

Now that you have updated the embedded application manifest in the Visual Studio Tools for Office solution document, you must update the deployment manifest to point to the new location of the external application manifest.

To update the deployment manifest

  1. Open the deployment manifest in a text editor, such as Notepad. The deployment manifest is named WordDeployment.application, and is located in the publish folder C:\TestDeploy.

  2. Set the codebase attribute of the <dependentAssembly> element to the full path of the final deployment location of the external application manifest. For more information, see <dependentAssembly> Element (Visual Studio Tools for Office Reference). The attribute for this walkthrough should look like this:

    <dependentAssembly
        codebase="\\DeployServer\ShareFolder\
        WordDeployment_1.0.0.0\WordDeployment.dll.manifest"
    
  3. Save and close the deployment manifest file.

In addition to updating the deployment manifest, you must also edit the external application manifest to point to the final deployment locations of the solution assembly and the deployment manifest. Every time you publish a Visual Studio Tools for Office solution, a new external application manifest is generated that points to the current version of the solution assembly.

To update the external application manifest

  1. Open the application manifest in a text editor, such as Notepad. The application manifest is named WordDeployment.dll.manifest, and is located in the publish folder C:\TestDeploy\WordDeployment_1.0.0.0.

  2. Locate the <installFrom> element that is the child of the <dependency> element, and set the codebase attribute to the full path of the current solution assembly. For more information, see <installFrom> Element (Visual Studio Tools for Office Reference). The attribute for this walkthrough should look like this:

    <dependentAssembly
        codebase="\\DeployServer\ShareFolder\
        WordDeployment_1.0.0.0\WordDeployment.dll"
    
  3. Locate the <installFrom> element that is the child of the <assembly> element, and set the codebase attribute to the full path of the deployment manifest. For more information, see <installFrom> Element (Visual Studio Tools for Office Reference). The attribute for this walkthrough should look like this:

    <dependentAssembly
        codebase="\\DeployServer\ShareFolder\WordDeployment.application"
    
  4. Save and close the application manifest file.

Now that you have edited the manifests, you are ready to copy the solution files to the server.

To copy the solution files to the server

  1. Create a WordDeployment_1.0.0.0 folder under the network file share \\DeployServer\ShareFolder.

  2. Copy the solution document and the deployment manifest to \\DeployServer\ShareFolder.

  3. Copy the solution assembly and the application manifest to \\DeployServer\ShareFolder\WordDeployment_1.0.0.0.

To run your Visual Studio Tools for Office solution from the network folder, you must grant full trust to the network folder in your security policy on the development computer. You can modify the security policy from a command prompt by using the Code Access Security Policy tool (Caspol.exe). To grant trust to a network location, you must have administrator privileges and you must change the security policy at the Machine level.

NoteNote

This procedure is intended for the purpose of performing this walkthrough. Do not use this procedure to grant trust to assemblies or directories if you are not certain that they are safe and secure. For more information about granting and removing permissions, see How to: Grant Permissions to Folders and Assemblies and How to: Remove Permissions from Folders and Assemblies.

To grant full trust to the network folder

  • Type the following command in the Visual Studio Command Prompt:

    caspol -m -ag LocalIntranet_Zone -url \\DeployServer\ShareFolder\* FullTrust -n "Remote Deployment" -d "Deployment Walkthrough"
    

Now you can test your solution to make sure that your code runs when you open the document from the development computer.

To test the deployment

  1. On the development computer, open the WordDeployment.doc file at \\DeployServer\ShareFolder\.

  2. Confirm that the message box appears.

You can also deploy your solution using a Microsoft Windows Installer (.msi) file. For more information, see Walkthrough: Deploying a Document-Level Customization Using a Windows Installer File.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft