Share via


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:

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:

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)

Other Resources

Programming Document-Level Customizations