在文件層級自訂中取得原生 Office 物件的擴充物件

Office 事件的多數事件處理常式都會接收代表引發事件之活頁簿、工作表或文件的原生 Office 物件。 某些情況下，您可能只有在文件層級自訂的活頁簿或文件引發事件時，才想要執行一些程式碼。 例如，使用 Excel 的文件層級自訂時，您可能想要在使用者啟動自訂活頁簿內其中一個工作表時執行一些程式碼，但不要在使用者啟動某個恰巧同時開啟之其他活頁簿內的工作表時執行程式碼。

當您有原生 Office 物件時，可以測試該物件是否已擴充成為文件層級自訂中的「主項目」(Host Item) 或「主控制項」(Host Control)。 主項目和主控制項是 Visual Studio Tools for Office Runtime 提供的型別，這些型別可將功能加入至原本就存在於 Word 或 Excel 物件模型的物件，稱為「原生 Office 物件」(Native Office Object)。 主項目和主控制項也統稱為「擴充物件」(Extended Object)。如需主項目和主控制項的詳細資訊，請參閱主項目和主控制項概觀。

**適用於：**本主題中的資訊適用於下列應用程式的文件層級專案：Excel 2007 和 Excel 2010、Word 2007 和 Word 2010。如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

了解 GetVstoObject 和 HasVstoObject 方法

若要測試原生 Office 物件，請在專案中使用 HasVstoObject 和 GetVstoObject 方法：

• 如果您想要判斷自訂中是否有原生 Office 物件的擴充物件，請使用 HasVstoObject 方法。 如果原生 Office 物件具有擴充物件，這個方法會傳回 true，否則傳回 false。

• 如果您想要取得原生 Office 物件的擴充物件，請使用 GetVstoObject 方法。 如果指定的原生 Office 物件具有擴充物件，這個方法會傳回 Microsoft.Office.Tools.Excel.ListObject、Microsoft.Office.Tools.Excel.Workbook、Microsoft.Office.Tools.Excel.Worksheet 或 Microsoft.Office.Tools.Word.Document 物件。 否則，GetVstoObject 會傳回 null。 例如，如果指定的 Microsoft.Office.Interop.Word.Document 是 Word 文件專案中之文件的基礎物件，則 GetVstoObject 方法會傳回 Microsoft.Office.Tools.Word.Document。

在文件層級專案中，您無法使用 GetVstoObject 方法在執行階段建立新的 Microsoft.Office.Tools.Excel.Workbook、Microsoft.Office.Tools.Excel.Worksheet 或 Microsoft.Office.Tools.Word.Document。 您只能使用這個方法來存取在設計階段產生於專案中的現有主項目。 如果您想要在執行階段建立新的主項目，則必須開發應用程式層級專案。 如需詳細資訊，請參閱主項目和主控制項的程式設計限制和在應用程式層級增益集的執行階段中擴充 Word 文件和 Excel 活頁簿。

使用 GetVstoObject 和 HasVstoObject 方法

呼叫 HasVstoObject 和 GetVstoObject 方法的方式，取決於專案的目標 .NET Framework 版本：

• 在目標為 .NET Framework 4 的專案中，請使用 Globals.Factory.GetVstoObject 或 Globals.Factory.HasVstoObject 方法，並傳遞至您要測試的原生 Word 或 Excel 物件 (例如 Microsoft.Office.Interop.Word.Document 或 Microsoft.Office.Interop.Excel.Worksheet)。

• 在目標為 .NET Framework 3.5 的專案中，請存取 Excel 和 Word 主要 Interop 組件的下列其中一個型別執行個體的方法：

  • Microsoft.Office.Interop.Excel.ListObject。

  • Microsoft.Office.Interop.Excel.Workbook。

  • Microsoft.Office.Interop.Excel.Worksheet。

  • Microsoft.Office.Interop.Word.Document。

注意事項
若要在目標為 .NET Framework 3.5 的文件層級專案中使用 GetVstoObject 和 HasVstoObject 方法，您必須將 Microsoft.Office.Tools.Excel.Extensions 或 Microsoft.Office.Tools.Word.Extensions 命名空間的 using (C#) 或 Imports (Visual Basic) 陳述式加入至程式碼檔的頂端。 GetVstoObject 和 HasVstoObject 方法會實作成「擴充方法」(Extension Method)，而這些陳述式可讓您呼叫這些方法。

範例：判斷主項目是否已引發事件

下列程式碼範例示範 HasVstoObject 和 GetVstoObject 方法。 這兩個範例都會在 Excel 活頁簿專案中處理 ThisWorkbook 類別的 SheetActivate 事件。 第一個範例會將 Sh 參數與每個預設主項目的 InnerObject 屬性進行比較，以判斷是否已啟動其中一個 Microsoft.Office.Tools.Excel.Worksheet 主項目。

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

下一個範例會使用 Sh 參數的 HasVstoObject 和 GetVstoObject 方法，簡化這個程序。 這個範例示範如何在目標為 .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.
    }
}

下列範例示範在目標為 .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.
    }
}

請參閱

參考

擴充方法 (C# 程式設計手冊)

概念

主項目和主控制項概觀

在應用程式層級增益集的執行階段中擴充 Word 文件和 Excel 活頁簿

擴充方法 (Visual Basic)

其他資源

文件層級自訂程式設計