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

發行項
08/12/2011

您可以使用應用程式層級增益集，以下列方式自訂 Word 文件和 Excel 活頁簿：

將 Managed 控制項加入至任何開啟的文件或工作表。
建立可在特定文件或活頁簿中辨識的智慧標籤。

注意事項

智慧標籤在 Excel 2010 和 Word 2010 中已被取代。如需詳細資訊，請參閱智慧標籤概觀。
將 Excel 工作表上的現有清單物件轉換為擴充的 ListObject，這個物件會公開事件，而且可以透過 Windows Forms 資料繫結模型繫結至資料。
存取 Word 和 Excel 為特定文件、活頁簿和工作表公開的應用程式層級事件。

注意事項
智慧標籤在 Excel 2010 和 Word 2010 中已被取代。如需詳細資訊，請參閱智慧標籤概觀。

若要使用這個功能，請在執行階段產生可擴充文件或活頁簿的物件。

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

使用增益集產生擴充物件

「擴充物件」(Extended Object) 是 Visual Studio Tools for Office 執行階段所提供類型的執行個體，這些類型會將功能加入至原本就存在於 Word 或 Excel 物件模型中的物件 (稱為「原生 Office 物件」(Native Office Object))。若要產生 Word 或 Excel物件的擴充物件，請使用 GetVstoObject 方法。第一次對指定的 Word 或 Excel 物件呼叫 GetVstoObject 方法時，它會傳回擴充該物件的新物件。每當您呼叫這個方法並指定同一個 Word 或 Excel 物件時，它都會傳回相同的擴充物件。

擴充物件的型別具有與原生 Office 物件型別相同的名稱，但是該型別是定義於 Microsoft.Office.Tools.Excel 或 Microsoft.Office.Tools.Word 命名空間 (Namespace)。例如，如果您呼叫 GetVstoObject 方法以擴充 Microsoft.Office.Interop.Word.Document 物件，該方法會傳回 Microsoft.Office.Tools.Word.Document 物件。

存取 GetVstoObject 方法的方式，取決於專案的目標 .NET Framework 版本：

在目標為 .NET Framework 3.5 的專案中，請使用 Excel 和 Word 主要 Interop 組件的下列其中一個型別執行個體的 GetVstoObject 方法：
在目標為 .NET Framework 4 的專案中，請使用 Globals.Factory.GetVstoObject 方法，並傳入您要擴充的原生 Word 或 Excel 物件 (例如 Microsoft.Office.Interop.Word.Document 或 Microsoft.Office.Interop.Excel.Worksheet)。

GetVstoObject 方法主要是用於應用程式層級專案。您也可以在文件層級專案中使用這些方法，但它們會有不同的行為，而且用途較少。如需詳細資訊，請參閱在文件層級自訂中取得原生 Office 物件的擴充物件。

若要判斷是否已經為特定原生 Office 物件產生擴充物件，請使用 HasVstoObject 方法。如需詳細資訊，請參閱判斷 Office 物件是否已經擴充。

注意事項
若要在目標為 .NET Framework 3.5 之專案中 ThisAddIn.cs 或 ThisAddIn.vb 以外的程式碼檔中使用 GetVstoObject 和 HasVstoObject 方法，您必須修改專案。如需詳細資訊，請參閱設定專案以使用 GetVstoObject 和 HasVstoObject 方法。

產生主項目

當您使用 GetVstoObject 擴充文件層級物件 (也就是 Microsoft.Office.Interop.Excel.Workbook、Microsoft.Office.Interop.Excel.Worksheet 或 Microsoft.Office.Interop.Word.Document) 時，傳回的物件就稱為「主項目」(Host Item)。主項目是可以包含其他物件 (包括其他擴充物件和控制項) 的型別。它類似 Word 或 Excel 主要 Interop 組件中的對應型別，但是具有額外的功能。如需主項目的詳細資訊，請參閱主項目和主控制項概觀。

產生主項目之後，您可以用它將智慧標籤或 Managed 控制項加入至文件、活頁簿或工作表。如需詳細資訊，請參閱將智慧標籤加入至文件和活頁簿和將 Managed 控制項加入至文件和工作表。

若要產生 Word 文件的主項目

下列程式碼範例示範如何在目標為 .NET Framework 4 的專案中產生現用文件的主項目。

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
        Globals.ThisAddIn.Application.ActiveDocument
    Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
        Globals.Factory.GetVstoObject(NativeDocument)
End If

if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        Globals.Factory.GetVstoObject(nativeDocument);
}

下列程式碼範例示範在目標為 .NET Framework 3.5 的專案中進行相同工作。

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document =
        Globals.ThisAddIn.Application.ActiveDocument
    If NativeDocument IsNot Nothing Then
        Dim vstoDocument As Microsoft.Office.Tools.Word.Document =
            NativeDocument.GetVstoObject()
    End If
End If

if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        nativeDocument.GetVstoObject();
}

若要產生 Excel 活頁簿的主項目

下列程式碼範例示範如何在目標為 .NET Framework 4 的專案中產生現用活頁簿的主項目。

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook =
    Globals.ThisAddIn.Application.ActiveWorkbook
If NativeWorkbook IsNot Nothing Then
    Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook =
        Globals.Factory.GetVstoObject(NativeWorkbook)
End If

Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

下列程式碼範例示範在目標為 .NET Framework 3.5 的專案中進行相同工作。

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook = _
    Globals.ThisAddIn.Application.ActiveWorkbook

If NativeWorkbook IsNot Nothing Then
    Dim VstoWorkbook As Microsoft.Office.Tools.Excel.Workbook = _
        NativeWorkbook.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Workbook nativeWorkbook =
    Globals.ThisAddIn.Application.ActiveWorkbook;

if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook =
        nativeWorkbook.GetVstoObject();
}

若要產生 Excel 工作表的主項目

下列程式碼範例示範如何在目標為 .NET Framework 4 的專案中產生現用工作表的主項目。

Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If NativeWorksheet IsNot Nothing Then
    Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
        Globals.Factory.GetVstoObject(NativeWorksheet)
End If

Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

下列程式碼範例示範在目標為 .NET Framework 3.5 的專案中進行相同工作。

Dim NativeSheet As Microsoft.Office.Interop.Excel.Worksheet = _
    TryCast(Globals.ThisAddIn.Application.ActiveSheet,  _
    Microsoft.Office.Interop.Excel.Worksheet)

If NativeSheet IsNot Nothing Then
    Dim VstoSheet As Microsoft.Office.Tools.Excel.Worksheet = _
        NativeSheet.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Worksheet nativeSheet =
    Globals.ThisAddIn.Application.ActiveSheet as
    Microsoft.Office.Interop.Excel.Worksheet;

if (nativeSheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet =
        nativeSheet.GetVstoObject();
}

產生 ListObject 主控制項

當您使用 GetVstoObject 方法擴充 Microsoft.Office.Interop.Excel.ListObject 時，這個方法會傳回 Microsoft.Office.Tools.Excel.ListObject。 Microsoft.Office.Tools.Excel.ListObject 除了擁有原始 Microsoft.Office.Interop.Excel.ListObject 的所有功能，還具備其他功能，例如使用 Windows Form 資料繫結模型繫結至資料的能力。如需詳細資訊，請參閱 ListObject 控制項。

若要產生 ListObject 的主控制項

下列程式碼範例示範如何在目標為 .NET Framework 4 的專案中，為現用工作表的第一個 Microsoft.Office.Interop.Excel.ListObject 產生 Microsoft.Office.Tools.Excel.ListObject。

Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
        Globals.Factory.GetVstoObject(listObject)
End If

Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = 
        sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        Globals.Factory.GetVstoObject(listObject);
}

下列程式碼範例示範在目標為 .NET Framework 3.5 的專案中進行相同工作。

Dim sheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet

If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject = _
        listObject.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet as
    Microsoft.Office.Interop.Excel.Worksheet;

if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        listObject.GetVstoObject();
}

將智慧標籤加入至文件和活頁簿

產生 Microsoft.Office.Tools.Word.Document 或 Microsoft.Office.Tools.Excel.Workbook 之後，您就可以建立可在這些物件所代表之文件或活頁簿的內容中辨識的智慧標籤。若要進行這項作業，請使用 Microsoft.Office.Tools.Word.Document 或 Microsoft.Office.Tools.Excel.Workbook 的 VstoSmartTags 屬性。如需詳細資訊，請參閱下列主題：

將 Managed 控制項加入至文件和工作表

產生 Microsoft.Office.Tools.Word.Document 或 Microsoft.Office.Tools.Excel.Worksheet 之後，您就可以將控制項加入至這些擴充物件所代表的文件或工作表。若要進行這項作業，請使用 Microsoft.Office.Tools.Word.Document 或 Microsoft.Office.Tools.Excel.Worksheet 的 Controls 屬性。如需詳細資訊，請參閱在執行階段將控制項加入至 Office 文件。

您可以加入 Windows Form 控制項或「主控制項」(Host Control)。主控制項是 Visual Studio Tools for Office Runtime 所提供的控制項，可包裝 Word 或 Excel 主要 Interop 組件中對應的控制項。主控制項會公開 (Expose) 基礎原生 Office 物件的所有行為，而且會引發事件，並使用 Windows Form 資料繫結模型繫結至資料。如需詳細資訊，請參閱主項目和主控制項概觀。

注意事項
您無法使用增益集將 XmlMappedRange 控制項加入至工作表，或是將 XMLNode 或 XMLNodes 控制項加入至文件。這些主控制項無法以程式設計方式加入。如需詳細資訊，請參閱主項目和主控制項的程式設計限制。

保存和移除控制項

如果將 Managed 控制項加入至文件或工作表，則文件在儲存並關閉時，該控制項無法保存。所有的主控制項都會移除，因此就只剩下基礎原生 Office 物件 (例如，Microsoft.Office.Tools.Excel.ListObject 會變成 Microsoft.Office.Interop.Excel.ListObject)。所有的 Windows Form 控制項也會移除，但是控制項的 ActiveX 包裝函式會留在文件中。您必須用增益集，加入清除控制項的程式碼，或在下次開啟文件時重新建立控制項。如需詳細資訊，請參閱在 Office 文件中保存動態控制項。

存取文件和活頁簿上的應用程式層級事件

原生 Word 和 Excel 物件模型中的某些文件、活頁簿和工作表事件只會在應用程式層級上引發。例如，用 Word 開啟文件時會引發 DocumentBeforeSave 事件，但這個事件是定義在 Microsoft.Office.Interop.Word.Application 類別中，而非 Microsoft.Office.Interop.Word.Document 類別中。

如果只透過增益集使用原生 Office 物件，您就必須處理這些應用程式層級事件，然後撰寫額外的程式碼，判斷引發該事件的文件是不是您所自訂的文件。主項目會在文件層級提供這些事件，如此就比較容易處理特定文件的事件。您可以產生主項目，然後再處理這個主項目的事件。

使用原生 Word 物件的範例

下列程式碼範例將示範如何處理 Word 文件的應用程式層級事件。 CreateDocument 方法會建立新文件，然後定義防止儲存這份文件的 DocumentBeforeSave 事件處理常式。因為這是針對 Microsoft.Office.Interop.Word.Application 物件引發的應用程式層級事件，事件處理常式必須將 Doc 參數與 document1 進行比較，才能判斷 document1 是否代表儲存的文件。

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

使用主項目的範例

下列程式碼範例會處理 Microsoft.Office.Tools.Word.Document 主項目的 BeforeSave 事件以簡化這個程序。以下範例中的 CreateDocument2 方法會產生擴充 document2 物件的 Microsoft.Office.Tools.Word.Document，然後再定義防止文件儲存的 BeforeSave 事件處理常式。因為只有在儲存 document2 時才會呼叫這個事件處理常式，所以此事件處理常式可以直接取消儲存動作，而不需另外執行任何工作來驗證已儲存哪個文件。

下列程式碼範例示範在目標為 .NET Framework 4 的專案中進行此項工作。

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

下列程式碼範例示範在目標為 .NET Framework 3.5 的專案中進行此項工作。

Private document2 As Microsoft.Office.Interop.Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = document2.GetVstoObject()
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object,
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = document2.GetVstoObject();
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

判斷 Office 物件是否已經擴充

若要判斷是否已經為特定原生 Office 物件產生擴充物件，請使用 HasVstoObject 方法。如果已經產生擴充物件，這個方法會傳回 true，否則會傳回 false。

在目標為 .NET Framework 3.5 的專案中，可在 Excel 和 Word 主要 Interop 組件的下列型別執行個體上使用 HasVstoObject 方法：

在目標為 .NET Framework 4 的專案中，使用 Globals.Factory.HasVstoMethod 方法。傳入您要針對擴充物件進行測試的原生 Word 或 Excel 物件 (例如 Microsoft.Office.Interop.Word.Document 或 Microsoft.Office.Interop.Excel.Worksheet)。

如果您只想在指定的 Office 物件具有擴充物件時才執行程式碼，HasVstoObject 方法會很有用。例如，如果您有一個會處理 DocumentBeforeSave 事件，以便在文件儲存之前移除其中的 Managed 控制項的 Word 增益集，這時您就可以使用 HasVstoObject 方法，判斷該文件是否經過擴充。如果文件尚未擴充，它就無法包含 Managed 控制項，這樣一來，事件處理常式可能會直接返回，而不嘗試清除文件上的控制項。

設定 .NET Framework 3.5 專案以使用 GetVstoObject 和 HasVstoObject 方法

當您建立目標為 .NET Framework 3.5 的應用程式層級專案時，會自動為您將專案設定成使用 ThisAddIn.cs 或 ThisAddIn.vb 程式碼檔中的 GetVstoObject 和 HasVstoObject 方法。若要在 ThisAddIn.cs 或 ThisAddIn.vb 以外的程式碼檔中使用這些方法，您必須對程式碼檔進行下列修改。

若要在 Excel 專案中修改程式碼檔以建立擴充物件

在您要在其中使用 GetVstoObject 和 HasVstoObject 方法之程式碼檔的最上方，加入下列 using (適用於 C#) 或 Imports (適用於 Visual Basic) 陳述式。
```
Imports Microsoft.Office.Tools.Excel.Extensions
```
```
using Microsoft.Office.Tools.Excel.Extensions;
```

若要在 Word 專案中修改程式碼檔以建立擴充物件

在您要在其中使用 GetVstoObject 和 HasVstoObject 方法之程式碼檔的最上方，加入下列 using (適用於 C#) 或 Imports (適用於 Visual Basic) 陳述式。
```
Imports Microsoft.Office.Tools.Word.Extensions
```
```
using Microsoft.Office.Tools.Word.Extensions;
```

這些是必要的變更，因為 GetVstoObject 和 HasVstoObject 方法會實作成「擴充方法」(Extension Method)。雖然您使用 GetVstoObject 和 HasVstoObject 方法時很像它們是使用 Excel 或 Word 主要 Interop 組件中的型別所定義，但是這些方法實際上是使用 Visual Studio Tools for Office Runtime 之 Microsoft.Office.Tools.Excel.Extensions 和 Microsoft.Office.Tools.Word.Extensions 命名空間中的型別所定義。如需擴充方法的詳細資訊，請參閱擴充方法 (C# 程式設計手冊) 和擴充方法 (Visual Basic)。