Getting Extended Objects from Native Office Objects in Document-Level Customizations

Applies to
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type Document-level projects Microsoft Office version Excel 2007 Word 2007 For more information, see Features Available by Application and Project Type.

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 Microsoft.Office.Tools.Excel.Worksheet host items in the customization, but not when the user activates a worksheet in some other workbook that happens to be open at the same time.

Starting in Visual Studio 2008 Service Pack 1 (SP1), when you get a native Office object, you can test whether that object has been extended into a host item or Microsoft.Office.Tools.Excel.ListObject host control in a document-level customization.

Host items and host controls are Visual Studio Tools for Office objects 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.

Using the GetVstoObject and HasVstoObject Methods

To test a native Office object, use the HasVstoObject and GetVstoObject methods of an instance of one of the following native Office objects:

• A ListObject.

• A Workbook.

• A Worksheet.

• A Document.

If you just want to determine whether the native Office object has an extended object in your customization, use the HasVstoObject method. This method returns true if the native Office object has an extended object, and false otherwise.

If you want to get the extended object, use the GetVstoObject method. 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 native Office object has one. Otherwise, GetVstoObject returns null. For example, the GetVstoObject method of a Document object returns a Microsoft.Office.Tools.Word.Document if the Document is the underlying object for the document in your Word document project.

You cannot use GetVstoObject in a document-level solution to create a new host item at run time. You can use it only to access existing host items that are generated in your project at design time. For more information, see Programmatic Limitations of Host Items and Host Controls.

In application-level projects, you can use the GetVstoObject method to generate new host items at run time. For more information, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.

Note

To use the GetVstoObject and HasVstoObject methods, 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 in the Visual Studio Tools for Office runtime, and these statements enable you to call these methods.

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
    ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet2
    ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet3
    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;
    else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet2;
    else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet3;

    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.

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

Concepts

Programming Document-Level Customizations

Host Items and Host Controls Overview

Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time

Extension Methods (Visual Basic)

Reference

Extension Methods (C# Programming Guide)

Change History

Date	History	Reason
July 2008	Added topic.	SP1 feature change.