How to: Attach Managed Code Extensions to Documents (2003 System)

You can attach a Visual Studio Tools for Office solution assembly to an existing Microsoft Office Word 2003 document or Microsoft Office Excel 2003 workbook. The document or workbook can be in any file format that is supported by Visual Studio Tools for Office. For more information, see Architecture of Document-Level Customizations.

If you attach a solution assembly to a document that does not yet have Visual Studio Tools for Office customizations, the Visual Studio Tools for Office runtime automatically creates a Runtime Storage Control in the document. For more information, see Runtime Storage Control Overview.

There are two ways to attach a solution assembly to a document:

• Manually set custom document properties in the document itself.

• Programmatically attach the assembly by using the ServerDocument class.

Using Custom Document Properties

You can attach a Visual Studio Tools for Office solution assembly to a Word or Excel document by manually setting the _AssemblyName and _AssemblyLocation custom document properties. For more information, see Custom Document Properties Overview.

The following procedure assumes that you have already deployed the solution assembly and that the solution uses a deployment manifest. For more information, see Deploying Document-Level Customizations (2003 System).

To attach a solution assembly by setting the custom document properties

1. Open the document in Word or Excel.

2. On the File menu, click Properties, and then click the Custom tab.

3. Set the _AssemblyName property:

   1. If _AssemblyName appears in the Properties list, select _AssemblyName, and type an asterisk (*) in the Value box.

   2. If _AssemblyName is not in the list, type _AssemblyName in the Name box, type an asterisk (*) in the Value box, and then click Add.

4. Set the _AssemblyLocation property:

   1. If _AssemblyLocation appears in the Properties list, select _AssemblyLocation, and type the full path of the deployment manifest in the Value box.

   2. If _AssemblyLocation is not in the list, type _AssemblyLocation in the Name box, type the full path of the deployment manifest in the Value box, and then click Add.

   The location of the deployment manifest can be a disk path (C:\deploy\Document1.application), a file share (\\server\Document1.application), or a Web site (https://www.contoso.com/Document1.application).

   Note

   The value of a custom document property can contain 255 characters. If the manifest path is longer than 255 characters, create a property named _AssemblyLocation0 and set this property to the first 255 characters in the path. Then, create a property named _AssemblyLocation1 and set this property to the remaining characters in the manifest path.

5. Click OK, and then save and close the document.

   The next time the document is opened and saved, the Visual Studio Tools for Office runtime attaches the solution assembly to the document, and creates the Runtime Storage Control, if necessary. The Visual Studio Tools for Office runtime also sets the value of the _AssemblyLocation custom document property to the GUID for the Runtime Storage Control. For more information, see Runtime Storage Control Overview.

   Note

   The document must be opened and saved on a computer that has the Visual Studio Tools for Office runtime installed. For more information, see How to: Install the Visual Studio Tools for Office Runtime. 

Using the ServerDocument Class

You can attach a Visual Studio Tools for Office solution assembly to a Word or Excel document by using the AddCustomization(String, String, String, String, Boolean) method of the ServerDocument class. You must put code that uses the ServerDocument class in a new project (not your Visual Studio Tools for Office solution), for example in a Windows Forms project. In addition, the document to which you are attaching the assembly must be closed, and the document must be on a computer that has Word (for Word documents) or Excel (for Excel workbooks) installed.

The following procedure assumes that you have already deployed the solution assembly and that the solution uses a deployment manifest. For more information, see Deploying Document-Level Customizations (2003 System).

To attach a solution assembly to a document by using the ServerDocument class

1. Create a new Windows Forms project.

2. Add a reference to the Microsoft.VisualStudio.Tools.Applications.Runtime.dll assembly to the project.

3. Add an Imports or using statement for the runtime to the top of your code file.

   Imports Microsoft.VisualStudio.Tools.Applications.Runtime
   

   using Microsoft.VisualStudio.Tools.Applications.Runtime;
   

4. Call the static AddCustomization(String, String, String, String, Boolean) method of the ServerDocument class, and specify the solution document path, assembly name, and deployment manifest path in the parameters. The following code assumes that you attaching an assembly to a Word document named WordDocument1.doc that is located in the folder C:\WordDocument1, and the assembly and deployment manifest are located at the network share \\deployserver\WordDocument1\.

   Private Sub AddNewCustomization()
   
       Dim fileName As String = "C:\WordDocument1\WordDocument1.doc" 
   
       If Not ServerDocument.IsCustomized(fileName) Then 
   
           Dim assemblyName As String = "\\deployserver\WordDocument1\WordDocument1.dll" 
           Dim manifestPath As String = "\\deployserver\WordDocument1\WordDocument1.application" 
           Dim applicationVersion As String = "1.0.0.0"
   
           ServerDocument.AddCustomization( _
               fileName, assemblyName, manifestPath, applicationVersion, False)
   
       Else
           System.Windows.Forms.MessageBox.Show( _
               "The specified document is already customized.")
       End If 
   End Sub
   

   private void AddNewCustomization()
   {
       string fileName = @"C:\WordDocument1\WordDocument1.doc";
   
       if (!ServerDocument.IsCustomized(fileName))
       {
           string assemblyName = @"\\deployserver\WordDocument1\WordDocument1.dll";
           string manifestPath = @"\\deployserver\WordDocument1\WordDocument1.application";
           string applicationVersion = "1.0.0.0";
   
           ServerDocument.AddCustomization(
               fileName, assemblyName, manifestPath, applicationVersion, false);
       }
       else
       {
           System.Windows.Forms.MessageBox.Show(
               "The specified document is already customized.");
       }
   }
   

   The Visual Studio Tools for Office runtime attaches the solution assembly to the document, and creates a Runtime Storage Control, if necessary. For more information, see Runtime Storage Control Overview.

See Also

Tasks

How to: Write Code that Uses Both Versions of the ServerDocument Class

How to: Remove Managed Code Extensions from Documents (2003 System)

How to: Remove Managed Code Extensions from Documents (2007 System)

How to: Attach Managed Code Extensions to Documents (2007 System)

Concepts

Managing Documents on a Server by Using the ServerDocument Class

Application and Deployment Manifests in Office Solutions

Runtime Storage Control Overview