Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
Globals.ThisAddIn.Application.ActiveSheet
If sheet.ListObjects.Count > 0 Then
Dim listObject As Excel.ListObject = sheet.ListObjects(1)
Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
Globals.Factory.GetVstoObject(listObject)
End If
Add managed controls to documents and worksheets
After you generate a Document or Worksheet, you can add controls to the document or worksheet that these extended objects represent. To add controls, use the Controls property of the Document or Worksheet. For more information, see Add controls to Office documents at run time.
You can add Windows Forms controls or host controls. A host control is a control provided by the Visual Studio Tools for Office runtime that wraps a corresponding control in the Word or Excel primary interop assembly. A host control exposes all of the behavior of the underlying native Office object. It also raises events and can be bound to data by using the Windows Forms data binding model. For more information, see Host items and host controls overview.
You cannot add a XmlMappedRange control to a worksheet, or a XMLNode or XMLNodes control to a document, by using a VSTO Add-in. These host controls cannot be added programmatically. For more information, see Programmatic limitations of host items and host controls.
Persist and remove controls
When you add managed controls to a document or worksheet, the controls are not persisted when the document is saved and then closed. All host controls are removed so that only the underlying native Office objects are left behind. For example, a ListObject becomes a ListObject. All Windows Forms controls are also removed, but ActiveX wrappers for the controls are left behind in the document. You must include code in your VSTO Add-in to clean up the controls, or to recreate the controls the next time the document is opened. For more information, see Persist dynamic controls in Office documents.
Access application-level events on documents and workbooks
Some document, workbook, and worksheet events in the native Word and Excel object models are raised only at the application level. For example, the DocumentBeforeSave event is raised when a document is opened in Word, but this event is defined in the Application class, rather than the Document class.
When you use only native Office objects in your VSTO Add-in, you must handle these application-level events and then write additional code to determine whether the document that raised the event is one that you have customized. Host items provide these events at the document level, so that it is easier to handle the events for a specific document. You can generate a host item and then handle the event for that host item.
Example that uses native Word objects
The following code example demonstrates how to handle an application-level event for Word documents. The CreateDocument method creates a new document, and then defines a DocumentBeforeSave event handler that prevents this document from being saved. The event is an application-level event that is raised for the Application object, and the event handler must compare the Doc parameter with the document1 object to determine if document1 represents the saved document.
private Word.Document document1 = null;
private void CreateDocument1()
document1 = this.Application.Documents.Add(ref missing,
ref missing, ref missing, ref missing);
this.Application.DocumentBeforeSave +=
new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
Application_DocumentBeforeSave);
private void Application_DocumentBeforeSave(Word.Document Doc,
ref bool SaveAsUI, ref bool Cancel)
if (Type.ReferenceEquals(Doc, document1))
Cancel = true;
Private document1 As Word.Document = Nothing
Private Sub CreateDocument1()
document1 = Me.Application.Documents.Add()
End Sub
Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
Handles Application.DocumentBeforeSave
If Type.ReferenceEquals(Doc, document1) Then
Cancel = True
End If
End Sub
Examples that use a host item
The following code examples simplify this process by handling the BeforeSave event of a Document host item. The CreateDocument2 method in these examples generates a Document that extends the document2 object, and then it defines a BeforeSave event handler that prevents the document from being saved. The event handler is called only when document2 is saved, and can cancel the save action without doing any extra work to verify which document was saved.
The following code example demonstrates this task.
private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;
private void CreateDocument2()
document2 = this.Application.Documents.Add(ref missing,
ref missing, ref missing, ref missing);
vstoDocument = Globals.Factory.GetVstoObject(document2);
vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
e.Cancel = true;
Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing
Private Sub CreateDocument2()
document2 = Me.Application.Documents.Add()
vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub
Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
e.Cancel = True
End Sub
Determine whether an Office object has been extended
To determine whether an extended object has already been generated for a particular native Office object, use the HasVstoObject method. This method returns true if an extended object has already been generated.
Use the Globals.Factory.HasVstoObject method. Pass in the native Word or Excel object, such as a Document or Worksheet, that you want to test for an extended object.
The HasVstoObject method is useful when you want to run code only when a specified Office object has an extended object. For example, if you have a Word VSTO Add-in that handles the DocumentBeforeSave event to remove managed controls from a document before it's saved, use the HasVstoObject method to determine whether the document has been extended. If the document has not been extended, it cannot have managed controls, and the event handler can return without trying to clean up controls on the document.
Related content
Program VSTO Add-ins
Add controls to Office documents at run time
Host items and host controls overview
Office development samples and walkthroughs
