Quick Start #2: Deploying a Document and an Assembly to Different Local Folders

Note: There are other Quick Starts in this series, including:

Deploying a Document and an Assembly to a Local Folder

Deploying a Document to a Local Folder, and an Assembly to a Network Folder

Deploying a Document and an Assembly to a Network Folder

Please send us your feedback on these Quick Starts!

-----

This Quick Start demonstrates how to deploy a Microsoft Visual Studio 2005 Tools for the Microsoft Office System solution for Microsoft Office Word 2003 or Microsoft Office Excel 2003 so that the document and the assembly are located in different folders on the end user computer. This Quick Start is intended for users who have little or no experience with deploying Visual Studio 2005 Tools for Office solutions.

This Quick Start includes the following sections:

• Prerequisites
• Creating a Solution to Deploy
• Deploying the Solution
• Setting Security Policy
• Next Steps

Prerequisites

This Quick Start assumes the end user computer already has the following prerequisites installed for running Visual Studio 2005 Tools for Office solutions:

• A version of Word or Excel that supports Visual Studio 2005 Tools for Office.
• The primary interop assemblies (PIAs).
• The .NET Framework 2.0.
• The Visual Studio 2005 Tools for Office runtime.

This Quick Start does not show you how to install these prerequisites on the end user computer. For more information about the prerequisites, see How to: Prepare End User Computers to Run Office Solutions.

Creating a Solution to Deploy

In the following steps, you will create a basic Visual Studio 2005 Tools for Office solution to deploy. If you already have a solution that you want to deploy, you can skip this section and proceed to the Deploying the Solution section.

1. Create a new Excel Workbook or Word Document project. For more information, see How to: Create Visual Studio Tools for Office Projects.

2. In Solution Explorer, right-click the ThisWorkbook (for Excel) or ThisDocument (for Word) code file and click View Code.

3. Add the following code in the ThisWorkbook_Startup (for Excel) or ThisDocument_Startup (for Word) event handler. This code displays a message box when the document opens, which will make it easy to verify whether the solution has been deployed successfully.

   ' Visual Basic
   MessageBox.Show("The deployment is successful")

   // C#
   MessageBox.Show("The deployment is successful");

   For more information about the Startup event, see Visual Studio Tools for Office Project Events.

4. Press F5 to build and run the project. Verify that the message box appears.

Deploying the Solution

In the following steps, you will deploy the document and assembly to different folders on the end user computer.

1. Choose or create two folders on the end user computer to deploy the solution to. One folder will contain the document, and the other folder will contain the assembly.

2. Edit the embedded application manifest in the document so that the document can find the assembly.
   When you build your solution, the document assumes the assembly is in the same folder as the document. The location of the assembly is stored in an application manifest that is embedded in the document. If you deploy the document and assembly to different folders, then you must edit the embedded application manifest to specify the new assembly path. You must use the ServerDocument class, which is provided with the Visual Studio 2005 Tools for Office runtime, to edit the embedded application manifest.

   To edit the embedded application manifest:

   a. Create a new Console Application project. You must use ServerDocument in a project that is different from the Word or Excel project, because ServerDocument cannot access the embedded application manifest if the document is open. You can also use ServerDocument in other project types, such as Windows Forms projects.
   b. Add a reference to the Microsoft.VisualStudio.Tools.Applications.Runtime.dll assembly to the new project. This is the assembly that provides ServerDocument.
   c. Add the following using statement (C#) or Imports statement (Visual Basic) to the top of the Program.cs or Module1.vb code file. This statement declares the namespace in which ServerDocument is defined.

   ' Visual Basic
   Imports Microsoft.VisualStudio.Tools.Applications.Runtime

   // C#
   using Microsoft.VisualStudio.Tools.Applications.Runtime;

   d. Add the following code in the Main method to update the embedded application manifest. Replace <full document path> with the full path of the document in its current location on the development computer—for example, <project folder> \bin\debug\WordDocument1.doc. Replace <full assembly path> with the full path of the assembly in the folder it will be deployed to—for example, C:\DeploymentFolder\WordDocument1.dll.

   ' Visual Basic
   Dim sd As ServerDocument = Nothing
   Try
   sd = New ServerDocument(" <full document path> ")
   sd.AppManifest.Dependency.AssemblyPath = _
   " <full assembly path> "
   sd.Save()
   Finally
   If Not sd Is Nothing Then
   sd.Close()
   End If
   End Try

   // C#
   ServerDocument sd = null;
   try
   {
   sd = new ServerDocument(@" <full document path> ");
   sd.AppManifest.Dependency.AssemblyPath =
   @" <full assembly path> ";
   sd.Save();
   }
   finally
   {
   if (sd != null)
   {
   sd.Close();
   }
   }

   e. Make sure that the document is not open in an instance of Word or Excel, or in the project designer. If the document is open, the attempt to access the document using ServerDocument will fail.
   f. Build and run the project. The Console application updates the assembly path in the embedded application manifest and then closes.
   g. Close the Console Application project.

3. Copy the document and assembly from the build output folder (typically <project folder> \bin\debug or <project folder> \bin\release) to their respective deployment folders on the end user computer. Make sure that you copy the assembly to the folder that you specified in the <full assembly path> placeholder in step 2.

4. Open the document in the deployment folder. You will see an error message stating that the current .NET security policy does not permit the customization to run. This is because you have not granted full trust to the assembly yet.

5. Click OK, and then close the document.

Setting Security Policy

In the following steps, you will grant full trust to the assembly in the .NET Framework 2.0 security policy of the end user. This Quick Start shows how to grant full trust to the assembly using the Code Access Security Policy tool (Caspol.exe). For more information about using Caspol.exe, see Code Access Security Policy Tool (Caspol.exe) and Configuring Security Policy Using the Code Access Security Policy Tool (Caspol.exe).

Security Note: These are basic steps for setting a security policy based on URL evidence for the purpose of completing this Quick Start. Do not use these steps to grant trust to assemblies in a real-world solution if you are not certain that the location is safe and secure. You should also base the security of a real-world solution on more evidence than the URL of the assembly. For more information, see Security Requirements to Run Office Solutions.

To grant full trust to the assembly:

1. On the end user computer, click Start, point to All Programs, point to Accessories, and then click Command Prompt.
2. Type the following command to create a new code group that grants full trust to the assembly.
   %windir%\Microsoft.NET\Framework\v2.0.50727\caspol -u -ag All_Code -url " <full assembly path> " FullTrust -n "Test_Deployment_Assembly"
   Replace <full assembly path> with the full path of the assembly on the end user computer—for example, C:\DeploymentFolder\WordDocument1.dll.
   The -n parameter specifies a name for the new code group. This parameter is not required, but specifying a label makes it easier to later identify and remove the new code group after you have completed this Quick Start.
3. Click Yes when prompted to confirm that you want to perform the operation, and press ENTER.
4. Open the deployed document and verify that the message box appears.

Next Steps

There are many other ways to deploy Visual Studio 2005 Tools for Office solutions, such as deploying the document and assembly to a remote computer or using a deployment manifest to enable automatic assembly updates. Refer to the following topics in the Visual Studio 2005 Tools for Office documentation more detailed information about deploying solutions.

For more information about deployment models for for Word and Excel solutions, see:

• Deploying Word and Excel Solutions
• Deployment Models

For more information about the embedded application manifest, see:

• Application and Deployment Manifests in Office Solutions
• Office Solutions Architecture Overview

For more information about security in Visual Studio 2005 Tools for Office solutions, see:

• Security Requirements to Run Office Solutions
• Secure Deployment

-- McLean Schofield

-----
This posting is provided "AS IS" with no warranties, and confers no rights.
Use of included script samples are subject to the terms specified at https://www.microsoft.com/info/cpyright.htm.

Comments

• Anonymous
  April 10, 2006
  Deploying Visual Studio 2005 Tools for Office Solutions Using Windows Installer: Walkthroughs (Part 2...

• Anonymous
  November 28, 2006
  PingBack from http://www.kintespace.com/rasxlog/?p=503

• Anonymous
  September 06, 2007
  Code Access Security Policy Tool (Caspol.exe) can be used to modify security policy for different policy