Persisting Dynamic Controls in Office Documents
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 Adding 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.
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.
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 Microsoft.Office.Tools.Excel.NamedRange or Microsoft.Office.Tools.Excel.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(ListObject) method and pass in the existing Microsoft.Office.Interop.Excel.ListObject. The following code example demonstrates this in a document-level project for Excel. The code re-creates a dynamic Microsoft.Office.Tools.Excel.ListObject that is based on an existing Microsoft.Office.Interop.Excel.ListObject named
MyListObject in the
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
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(Range, String) or AddChart(Double, Double, Double, Double, String) 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.
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 Removing ActiveX Wrappers in an Add-in.
You can re-create deleted Windows Forms controls when the user reopens the document. To do this, your solution must perform the following tasks:
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 this data to the data cache in the document. In an VSTO Add-in, you can save this data to a custom XML part in the document.
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
ThisDocument_Startupevent handlers. In VSTO Add-in projects, you can do this in the event handlers for the WorkbookOpen or E:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.DocumentOpen events.
When you add dynamic Windows Forms controls to documents by using an 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.
To remove all ActiveX wrappers, call the GetVstoObject method to generate a host item for the Microsoft.Office.Interop.Word.Document or Microsoft.Office.Interop.Excel.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 E:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.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
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 Extending Word Documents and Excel Workbooks in VSTO Add-ins at Run Time.
Note that 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.
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