Persist dynamic controls in Office documents

Applies to: Visual Studio Visual Studio for Mac

Controls that are added at run time are not persisted when the document or workbook is saved and closed. The exact behavior is different for host controls and Windows Forms controls. In both cases, you can add code to your solution to re-create the controls when the user reopens the document.

Controls that you add to documents at run time are called dynamic controls. For more information about dynamic controls, see Add controls to Office documents at run time.

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

Persist host controls in the document

When a document is saved and then closed, all dynamic host controls are removed from the document. Only the underlying native Office objects remain behind. For example, a Microsoft.Office.Tools.Excel.ListObject host control becomes a Microsoft.Office.Interop.Excel.ListObject. The native Office objects are not connected to the host control events, and they do not have the data binding functionality of the host control.

The following table lists the native Office object that is left behind in a document for each type of host control.

Re-create dynamic host controls when documents are opened

You can re-create dynamic host controls in place of existing native controls every time a user opens the document. Creating host controls in this manner when a document is opened simulates the experience that users might expect.

To re-create a host control for Word, or a NamedRange or ListObject host control for Excel, use an Add<control class> method of an Microsoft.Office.Tools.Excel.ControlCollection or Microsoft.Office.Tools.Word.ControlCollection object. Use a method that has a parameter for the native Office object.

For example, if you want to create a Microsoft.Office.Tools.Excel.ListObject host control from an existing native Microsoft.Office.Interop.Excel.ListObject when the document is opened, use the AddListObject method and pass in the existing ListObject. The following code example demonstrates this in a document-level project for Excel. The code re-creates a dynamic ListObject that is based on an existing ListObject named MyListObject in the Sheet1 class.

private Microsoft.Office.Tools.Excel.ListObject vstoListObject;
private const int DISP_E_BADINDEX = unchecked((int)0x8002000B);

private void Sheet1_Startup(object sender, System.EventArgs e)
{
    Excel.ListObject nativeListObject = null;

    try
    {
        nativeListObject = this.ListObjects.get_Item("MyListObject");
    }
    catch (System.Runtime.InteropServices.COMException ex)
    {
        // "MyListObject" does not exist.
        if (ex.ErrorCode != DISP_E_BADINDEX)
            throw;
    }

    if (nativeListObject != null)
    {
        vstoListObject = this.Controls.AddListObject(nativeListObject);
    }
}

Private vstoListObject As Microsoft.Office.Tools.Excel.ListObject
Private Const DISP_E_BADINDEX As Integer = CInt(&H8002000B)

Private Sub Sheet1_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
    Dim nativeListObject As Excel.ListObject = Nothing

    Try
        nativeListObject = Me.ListObjects("MyListObject")
    Catch ex As System.Runtime.InteropServices.COMException
        ' "MyListObject" does not exist.
        If ex.ErrorCode <> DISP_E_BADINDEX Then
            Throw
        End If
    End Try

    If nativeListObject IsNot Nothing Then
        vstoListObject = Me.Controls.AddListObject(nativeListObject)
    End If
End Sub

Re-create chart

To re-create a Microsoft.Office.Tools.Excel.Chart host control, you must first delete the native Microsoft.Office.Interop.Excel.Chart, and then re-create the Microsoft.Office.Tools.Excel.Chart by using the AddChart method. There is no Add<control class> method that enables you to create a new Microsoft.Office.Tools.Excel.Chart based on an existing Microsoft.Office.Interop.Excel.Chart.

If you do not first delete the native Chart, then you'll create a second, duplicate chart when you re-create the Microsoft.Office.Tools.Excel.Chart.

Persist Windows Forms controls in documents

When a document is saved and then closed, the Visual Studio Tools for Office runtime automatically removes all dynamically created Windows Forms controls from the document. However, the behavior is different for document-level and VSTO Add-in projects.

In document-level customizations, the controls and their underlying ActiveX wrappers (which are used to host the controls on the document) are removed the next time the document is opened. There is no indication that the controls were ever there.

In VSTO Add-ins, the controls are removed, but the ActiveX wrappers remain in the document. The next time the user opens the document, the ActiveX wrappers are visible. In Excel, the ActiveX wrappers display images of the controls as they appeared the last time the document was saved. In Word, the ActiveX wrappers are invisible unless the user clicks on them, in which case they display a dotted line that represents the border of the controls. There are several ways you can remove the ActiveX wrappers. For more information, see Remove ActiveX Wrappers in an Add-in.

Re-create Windows Forms controls when documents are opened

You can re-create deleted Windows Forms controls when the user reopens the document. To do this, your solution must perform the following tasks:

1. Store information about the size, location, and state of the controls when the document is saved or closed. In a document-level customization, you can save the data to the data cache in the document. In a VSTO Add-in, you can save the data to a custom XML part in the document.

2. Re-create the controls in an event that is raised when the document is opened. In document-level projects, you can do this in the Sheetn_Startup or ThisDocument_Startup event handlers. In VSTO Add-in projects, you can do this in the event handlers for the WorkbookOpen or DocumentOpen events.

Remove ActiveX wrappers in an Add-in

When you add dynamic Windows Forms controls to documents by using a VSTO Add-in, you can prevent the ActiveX wrappers for the controls from appearing in the document the next time it is opened in the following ways.

Remove ActiveX wrappers when the document is opened

To remove all ActiveX wrappers, call the GetVstoObject method to generate a host item for the Document or Workbook that represents the newly opened document. For example, to remove all ActiveX wrappers from a Word document, you can call the GetVstoObject method to generate a host item for the Document object that is passed to the event handler for the DocumentOpen event.

This procedure is useful when you know that the document will be opened only on computers that have the VSTO Add-in installed. If the document might be passed to other users who do not have the VSTO Add-in installed, consider removing the controls before closing the document instead.

The following code example demonstrates how to call the GetVstoObject method when the document is opened.

Private Sub Application_DocumentOpen_ClearActiveXWrappers( _
    ByVal Doc As Word.Document) Handles Application.DocumentOpen

    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

End Sub

private void Application_DocumentOpen_ClearActiveXWrappers(Word.Document Doc)
{
    Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

}

Although the GetVstoObject method is used primarily to generate a new host item at run time, this method also clears all ActiveX wrappers from the document the first time it is called for a specific document. For more information about how to use the GetVstoObject method, see Extend Word documents and Excel workbooks in VSTO Add-ins at run time.

If your VSTO Add-in creates dynamic controls when the document is opened, your VSTO Add-in will already call the GetVstoObject method as part of the process to create the controls. You do not need to add a separate call to the GetVstoObject method to remove the ActiveX wrappers in this scenario.

Remove the dynamic controls before the document is closed

Your VSTO Add-in can explicitly remove each dynamic control from the document before the document is closed. This procedure is useful for documents that might be passed to other users who do not have the VSTO Add-in installed.

The following code example demonstrates how to remove all of the Windows Forms controls from a Word document when the document is closed.

Private Sub Application_DocumentBeforeClose(ByVal Doc As Word.Document, _
    ByRef Cancel As Boolean) Handles Application.DocumentBeforeClose

    Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)

    If isExtended Then

        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

        Dim controlsToRemove As System.Collections.ArrayList = _
            New System.Collections.ArrayList()

        ' Get all of the Windows Forms controls.
        For Each control As Object In vstoDocument.Controls
            If TypeOf control Is System.Windows.Forms.Control Then
                controlsToRemove.Add(control)
            End If
        Next

        ' Remove all of the Windows Forms controls from the document.
        For Each control As Object In controlsToRemove
            vstoDocument.Controls.Remove(control)
        Next
    End If
End Sub

void Application_DocumentBeforeClose(Word.Document Doc, ref bool Cancel)
{

    bool isExtended = Globals.Factory.HasVstoObject(Doc);

    if (isExtended)
    {
        Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

        
        System.Collections.ArrayList controlsToRemove = 
            new System.Collections.ArrayList();
        
        // Get all of the Windows Forms controls.
        foreach (object control in vstoDocument.Controls)
        {
            if (control is System.Windows.Forms.Control)
            {
                controlsToRemove.Add(control);
            }
        }

        // Remove all of the Windows Forms controls from the document.
        foreach (object control in controlsToRemove)
        {
            vstoDocument.Controls.Remove(control);
        }
    }
}

See also

• Add controls to Office documents at run time