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.

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.

The way that you call the HasVstoObject and GetVstoObject methods depends on what version of the .NET Framework your project targets:

NoteNote

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.

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.


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.


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.


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.
    }
}


Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2015 Microsoft