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

發行項
08/21/2008

更新： 2008 年 7 月

適用於
本主題中的資訊僅適用於指定的 Visual Studio Tools for Office 專案和 Microsoft Office 版本。專案類型應用程式層級專案 Microsoft Office 版本 Excel 2007 Word 2007 如需詳細資訊，請參閱依應用程式和專案類型提供的功能。

本主題中的資訊僅適用於指定的 Visual Studio Tools for Office 專案和 Microsoft Office 版本。

專案類型

應用程式層級專案

Microsoft Office 版本

Excel 2007
Word 2007

如需詳細資訊，請參閱依應用程式和專案類型提供的功能。

從 Visual Studio 2008 Service Pack 1 (SP1) 開始，您可以使用應用程式層級增益集，以下列方式對文件和活頁簿進行自訂：

將 Managed 控制項加入至任何開啟的文件或工作表。
建立可在特定文件或活頁簿中辨識的智慧標籤。
將 Excel 工作表中的現有清單物件轉換為 Visual Studio Tools for Office 清單物件，這個清單物件會公開 (Expose) 事件，而且可以使用 Windows Form 資料繫結模型繫結至資料。
存取 Word 和 Excel 為特定文件、活頁簿和工作表公開的應用程式層級事件。

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

使用增益集產生擴充物件

「擴充物件」(Extended Object) 是 Visual Studio Tools for Office 物件，這個物件會將功能加入至原本就存在於 Word 或 Excel 物件模型 (稱為「原生 Office 物件」(Native Office Object)) 的物件。若要使用增益集產生擴充物件，請使用 Excel 和 Word 主要 Interop 組件的下列其中一個型別執行個體的 GetVstoObject 方法：

第一次呼叫原生 Office 物件的 GetVstoObject 方法時，它會傳回可擴充該物件的新 Visual Studio Tools for Office 物件。每當您呼叫同一個原生 Office 物件上的方法時，它都會傳回相同的擴充物件。

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

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

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

注意事項：
若要在 ThisAddIn.cs 或 ThisAddIn.vb 以外的程式碼檔中，或是在 SP1 安裝之前所建立的專案中使用 GetVstoObject 和 HasVstoObject 方法，您必須修改專案。如需詳細資訊，請參閱設定專案以使用 GetVstoObject 和 HasVstoObject 方法。

產生主項目

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

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

若要產生 Word 文件的主項目

請使用 Microsoft.Office.Interop.Word.Document 的 GetVstoObject 方法。下列程式碼範例會產生現用文件的主項目。

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 = _
        NativeDocument.GetVstoObject()
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 活頁簿的主項目

請使用 Microsoft.Office.Interop.Excel.Workbook 的 GetVstoObject 方法。下列程式碼範例會產生現用活頁簿的主項目。

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 工作表的主項目

請使用 Microsoft.Office.Interop.Excel.Worksheet 的 GetVstoObject 方法。下列程式碼範例會產生現用工作表的主項目。

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 主控制項

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

若要產生 ListObject 的主控制項

請使用 Microsoft.Office.Interop.Excel.ListObject 的 GetVstoObject 方法。下列程式碼範例會產生現用工作表中第一個 Microsoft.Office.Interop.Excel.ListObject 的 Microsoft.Office.Tools.Excel.ListObject。

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)。主控制項是將對應控制項包裝在 Word 或 Excel 主要 Interop 組件中的 Visual Studio Tools for Office 控制項。主控制項會公開 (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 文件的應用程式層級事件。這個範例中的 CreateDocument1 方法會建立新文件，然後定義防止儲存這份文件的 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 時才會呼叫這個事件處理常式，所以此事件處理常式可以直接取消儲存動作，而不需另外執行任何工作來驗證已儲存哪個文件。

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 = 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 物件產生 Visual Studio Tools for Office 物件，請使用 Office 物件的 HasVstoObject 方法。如果已經產生擴充物件，這個方法會傳回 true，否則會傳回 false。

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

設定專案以使用 GetVstoObject 和 HasVstoObject 方法

當您在安裝 Visual Studio 2008 SP1 之後建立應用程式層級專案時，專案會自動為您設定為可在 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.Excel.Extensions
```
```
using Microsoft.Office.Tools.Excel.Extensions;
```

若要在安裝 SP1 之前所建立的應用程式層級專案中使用這些方法，您必須對專案進行下列變更。

若要修改現有 Excel 增益集以建立擴充物件

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

若要修改現有 Word 增益集以建立擴充物件

加入 Microsoft.Office.Tools.Word.v9.0.dll 組件的參考。
在您要在其中使用 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 執行階段之 Microsoft.Office.Tools.Excel.Extensions 和 Microsoft.Office.Tools.Word.Extensions 命名空間的型別所定義。如需擴充方法的詳細資訊，請參閱擴充方法 (C# 程式設計手冊) 和擴充方法 (Visual Basic)。