Getting Extended Objects from Native Office Objects in Document-Level Customizations
Many event handlers for Office events receive a native Office object that represents the workbook, worksheet, or document that raised the event. In some cases, you might want to run some code only if the workbook or document in your document-level customization raised the event. For example, in a document-level customization for Excel, you might want to run some code when the user activates one of the worksheets in the customized workbook, but not when the user activates a worksheet in some other workbook that happens to be open at the same time.
When you have a native Office object, you can test whether that object has been extended into a host item or host control in a document-level customization. Host items and host controls are types provided by the Visual Studio Tools for Office runtime that add functionality to objects that exist natively in the Word or Excel object models (called native Office objects). Collectively, host items and host controls are also called extended objects. For more information about host items and host controls, see Host Items and Host Controls Overview.
Applies to: The information in this topic applies to document-level projects for the following applications: Excel 2007 and Excel 2010; Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.
Understanding the GetVstoObject and HasVstoObject Methods
To test a native Office object, use the HasVstoObject and GetVstoObject methods in your project:
Use the HasVstoObject method if you want to determine whether the native Office object has an extended object in your customization. This method returns true if the native Office object has an extended object, and false otherwise.
Use the GetVstoObject method if you want to get the extended object for a native Office object. This method returns a Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet, or Microsoft.Office.Tools.Word.Document object if the specified native Office object has one. Otherwise, GetVstoObject returns null. For example, the GetVstoObject method returns a Microsoft.Office.Tools.Word.Document if the specified Microsoft.Office.Interop.Word.Document is the underlying object for the document in your Word document project.
In document-level projects, you cannot use the GetVstoObject method to create a new Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet, or Microsoft.Office.Tools.Word.Document host item at run time. You can use this method only to access existing host items that are generated in your project at design time. If you want to create new host items at run time, you must develop an application-level project. For more information, see Programmatic Limitations of Host Items and Host Controls and Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.
Using the GetVstoObject and HasVstoObject Methods
The way that you call the HasVstoObject and GetVstoObject methods depends on what version of the .NET Framework your project targets:
In projects that target the .NET Framework 4, use the Globals.Factory.GetVstoObject or Globals.Factory.HasVstoObject method, and pass in the native Word or Excel object (such as a Microsoft.Office.Interop.Word.Document or Microsoft.Office.Interop.Excel.Worksheet) that you want to test.
In projects that target the .NET Framework 3.5, access the methods on an instance of one of the following types in the Excel and Word primary interop assemblies:
Note
To use the GetVstoObject and HasVstoObject methods in document-level projects that target the .NET Framework 3.5, you must add using (for C#) or Imports (for Visual Basic) statements for the Microsoft.Office.Tools.Excel.Extensions or Microsoft.Office.Tools.Word.Extensions namespaces to the top of your code file. The GetVstoObject and HasVstoObject methods are implemented as extension methods, and these statements enable you to call these methods.
Example: Determining Whether a Host Item Raised an Event
The following code examples demonstrate the HasVstoObject and GetVstoObject methods. Both examples handle the SheetActivate event of the ThisWorkbook class in an Excel workbook project. The first example determines whether one of the Microsoft.Office.Tools.Excel.Worksheet host items was activated by comparing the Sh parameter with the InnerObject property of each default host item.
Sub ThisWorkbook_SheetActivate1(ByVal Sh As Object) Handles Me.SheetActivate
Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing
If Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh) Then
vstoWorksheet = Globals.Sheet1.Base
ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
vstoWorksheet = Globals.Sheet2.Base
ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
vstoWorksheet = Globals.Sheet3.Base
End If
If vstoWorksheet IsNot Nothing Then
' Do something with the VSTO worksheet here.
End If
End Sub
void ThisWorkbook_SheetActivate1(object Sh)
{
Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;
if (Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh))
vstoWorksheet = Globals.Sheet1.Base;
else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
vstoWorksheet = Globals.Sheet2.Base;
else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
vstoWorksheet = Globals.Sheet3.Base;
if (vstoWorksheet != null)
{
// Do something with the VSTO worksheet here.
}
}
The next example simplifies this process by using the HasVstoObject and GetVstoObject methods of the Sh parameter. This example demonstrates how to call these methods in a project that targets the .NET Framework 4.
Private Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object)
Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing
Dim interopWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
CType(Sh, Microsoft.Office.Interop.Excel.Worksheet)
If interopWorksheet IsNot Nothing AndAlso
Globals.Factory.HasVstoObject(interopWorksheet) Then
vstoWorksheet = Globals.Factory.GetVstoObject(interopWorksheet)
End If
If vstoWorksheet IsNot Nothing Then
' Do something with the VSTO worksheet here.
End If
End Sub
void ThisWorkbook_SheetActivate2(object Sh)
{
Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;
Microsoft.Office.Interop.Excel.Worksheet interopWorksheet =
Sh as Microsoft.Office.Interop.Excel.Worksheet;
if (interopWorksheet != null && Globals.Factory.HasVstoObject(interopWorksheet))
{
vstoWorksheet = Globals.Factory.GetVstoObject(interopWorksheet);
}
if (vstoWorksheet != null)
{
// Do something with the VSTO worksheet here.
}
}
The following example demonstrates the same task in a project that targets the .NET Framework 3.5.
Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object) Handles Me.SheetActivate
Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing
Dim interopWorksheet As Microsoft.Office.Interop.Excel.Worksheet = _
CType(Sh, Microsoft.Office.Interop.Excel.Worksheet)
If interopWorksheet IsNot Nothing AndAlso _
interopWorksheet.HasVstoObject() Then
vstoWorksheet = interopWorksheet.GetVstoObject()
End If
If vstoWorksheet IsNot Nothing Then
' Do something with the VSTO worksheet here.
End If
End Sub
void ThisWorkbook_SheetActivate2(object Sh)
{
Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;
Microsoft.Office.Interop.Excel.Worksheet interopWorksheet =
Sh as Microsoft.Office.Interop.Excel.Worksheet;
if (interopWorksheet != null && interopWorksheet.HasVstoObject())
{
vstoWorksheet = interopWorksheet.GetVstoObject();
}
if (vstoWorksheet != null)
{
// Do something with the VSTO worksheet here.
}
}
See Also
Reference
Extension Methods (C# Programming Guide)
Concepts
Host Items and Host Controls Overview
Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time
Extension Methods (Visual Basic)