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

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 Architecture of Document-Level Customizations.

In a production environment, a Visual Studio Tools for Office 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 (2003 System).

This walkthrough illustrates the following tasks:

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

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

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

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

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

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.

  Note

  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.

Creating the Project

In this step, create a Word Document project.

To create a new project

• Create a Word Document project with the name WordDeployment, using the project template for Office 2003.

  In the wizard, select Create a new document. For more information, see How to: Create Visual Studio Tools for Office Projects.

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

Adding Code Behind the Document

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 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 Sub ThisDocument_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
       Handles Me.Startup
   
       MessageBox.Show("The document is deployed correctly.")
   End Sub
   

   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.

Publishing the Solution

The first deployment step of this process is to 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 (2003 System).

5. Click Close Solution on the File menu to close the WordDeployment solution in Visual Studio.

   Note

   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.

Updating the Embedded Application Manifest

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. 

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.

   Imports Microsoft.VisualStudio.Tools.Applications.Runtime
   

   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.

   Dim sd As ServerDocument = Nothing 
   Try
       sd = New ServerDocument("C:\TestDeploy\WordDeployment.doc")
       sd.AppManifest.DeployManifestPath = _
           "\\DeployServer\ShareFolder\WordDeployment.application"
       sd.Save()
   
   Finally 
       If Not sd Is Nothing Then
           sd.Close()
       End If 
   End Try
   

   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.

Updating the Deployment Manifest

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 located in the publish folder C:\TestDeploy. It is named WordDeployment.application.

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 the following example.

   <dependentAssembly
       codebase="\\DeployServer\ShareFolder\
       WordDeployment_1.0.0.0\WordDeployment.dll.manifest"
   

3. Save and close the deployment manifest file.

Updating the External Application Manifest

In addition to updating the deployment manifest, you must also edit the external application manifest to point to the final deployment location 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 located in the publish folder C:\TestDeploy\WordDeployment_1.0.0.0. It is named WordDeployment.dll.manifest.

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 the following example.

   <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 the following example.

   <dependentAssembly
       codebase="\\DeployServer\ShareFolder\WordDeployment.application"
   

4. Save and close the application manifest file.

Copying the Solution Files to the Server

Now that you have edited the manifests, you are ready to copy the solution files to the final deployment destination on 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.

Granting Full Trust to the Network Folder

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.

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"
  

Testing the Solution

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.

Next Steps

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 (2003 System).

See Also

Tasks

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

Concepts

Deploying Office Solutions (2003 System)

Deploying Document-Level Customizations (2003 System)

Deployment Models (2003 System)