Share via

How to: Attach managed code extensions to documents

  • Article

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

You can attach a customization assembly to an existing Microsoft Office Word document or Microsoft Office Excel workbook. The document or workbook can be in any file format that is supported by the Microsoft Office projects and development tools in Visual Studio. For more information, see Architecture of document-level customizations.

Applies to: The information in this topic applies to document-level projects for Excel and Word. For more information, see Features available by Office application and project type.

To attach a 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 directly related to Microsoft Office development (such as a console or Windows Forms application).

Note

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

To attach managed code extensions to a document

  1. In a project that does not require Microsoft Office, such as a console application or Windows Forms project, add a reference to the Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.dll assemblies.

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

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

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

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

    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);
}

    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

  4. Build the project and run the application on the computer where you want to attach the customization. The computer must have the Visual Studio 2010 Tools for Office Runtime installed.

See also