This documentation is archived and is not being maintained.

How to: Attach Managed Code Extensions to Documents

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

You can attach a Microsoft Visual Studio 2005 Tools for the Microsoft Office System 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 supported by Visual Studio Tools for Office, including WordprocessingML files. For more information, see Office Solutions Architecture Overview.

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.

NoteNote

If the specified document does not contain a control that the solution assembly expects the document to have, the assembly will fail to load when the user opens the document.

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.

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 (http://www.contoso.com/Document1.application).

    NoteNote

    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.

    NoteNote

    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 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.

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 Microsoft.VisualStudio.Tools.Applications.Runtime to the project.

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

    using Microsoft.VisualStudio.Tools.Applications.Runtime;
    
    
  4. Call the static AddCustomization 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 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

Show: