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

Applies to
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type Document-level projects Microsoft Office version 2007 Microsoft Office system For more information, see Features Available by Application and Project Type.

You can attach a Visual Studio Tools for Office customization to an existing Microsoft Office Word 2007 document or Microsoft Office Excel 2007 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.

Note

The customization will fail to load if the code expects controls that the specified document does not have.

To attach a Visual Studio Tools for Office customization to a Word or Excel document, use the AddCustomization method of the ServerDocument class. Because the ServerDocument class is designed to be run on a computer that does not have Microsoft Office installed, you can use this method in solutions that are not based on Visual Studio Tools for Office projects (such as a console or Windows Forms application).

For a related video demonstration, see How Do I: Attach or Detach a VSTO Assembly from a Word Document?.

To attach managed code extensions to a document

1. Create a new project that does not start Word or Excel, such as a console application or Windows Forms project.

2. In the new project, add a reference to the following assemblies.

   • Microsoft.VisualStudio.Tools.Applications.ServerDocument.v9.0.dll

   • Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll

3. Add the following Imports or using statements to the top of your code file.

   Imports Microsoft.VisualStudio.Tools.Applications
   Imports Microsoft.VisualStudio.Tools.Applications.Runtime
   

   using Microsoft.VisualStudio.Tools.Applications;
   using Microsoft.VisualStudio.Tools.Applications.Runtime;
   

4. Call the static AddCustomization method.

   The following code example uses the AddCustomization overload. This overload takes the full path of the document and a Uri that specifies the location of the deployment manifest for the customization you want to attach to the document. This example assumes that a Word document named WordDocument1.docx is on the desktop, and that the deployment manifest is located in a folder that is named Publish that is also on the desktop.

   Dim documentPath As String = System.Environment.GetFolderPath( _
        Environment.SpecialFolder.Desktop) + "\WordDocument1.docx" 
   Dim runtimeVersion As Integer = 0
   
   Try
       runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath)
   
       ' Make sure that this document does not yet have any Visual Studio Tools  
       ' for Office customizations. 
       If runtimeVersion = 0 Then 
           Dim deployManifestPath As String = System.Environment.GetFolderPath( _
               Environment.SpecialFolder.Desktop) & "\Publish\WordDocument1.vsto" 
           Dim deploymentManifestUri As New Uri(deployManifestPath)
           ServerDocument.AddCustomization(documentPath, deploymentManifestUri)
           System.Windows.Forms.MessageBox.Show("The document was successfully customized.")
       Else
           System.Windows.Forms.MessageBox.Show("The document is already customized.")
       End If 
   Catch ex As FileNotFoundException
       System.Windows.Forms.MessageBox.Show("The specified document does not exist.")
   Catch ex As DocumentNotCustomizedException
       System.Windows.Forms.MessageBox.Show("The document could not be customized." & _
           vbLf & ex.Message)
   End Try
   

   string documentPath = System.Environment.GetFolderPath(
       Environment.SpecialFolder.Desktop) + @"\WordDocument1.docx";
   int runtimeVersion = 0;
   
   try
   {
       runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath);
   
       // Make sure that this document does not yet have any Visual Studio Tools  
       // for Office customizations. 
       if (runtimeVersion == 0)
       {
           string deployManifestPath = System.Environment.GetFolderPath(
               Environment.SpecialFolder.Desktop) + @"\Publish\WordDocument1.vsto";
   
           Uri deploymentManifestUri = new Uri(deployManifestPath);
           ServerDocument.AddCustomization(documentPath, deploymentManifestUri);
           System.Windows.Forms.MessageBox.Show("The document was successfully customized.");
       }
       else
       {
           System.Windows.Forms.MessageBox.Show("The document is already customized.");
       }
   }
   catch (FileNotFoundException)
   {
       System.Windows.Forms.MessageBox.Show("The specified document does not exist.");
   }
   catch (DocumentNotCustomizedException ex)
   {
       System.Windows.Forms.MessageBox.Show("The document could not be customized.\n" +
           ex.Message);
   }
   

See Also

Tasks

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

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

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

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

Concepts

Managing Documents on a Server by Using the ServerDocument Class

Application and Deployment Manifests in Office Solutions