從其他 Office 方案呼叫 VSTO 增益集的程式碼

  • 發行項

您可以將 VSTO 增益集中的物件公開給其他方案 (包括其他 Microsoft Office 方案)。 如果您想要讓其他方案也能使用 VSTO 增益集提供的服務，這就很有用。 例如，如果您的 Microsoft Office Excel VSTO 增益集會計算 Web 服務的財務資料，則其他方案可以在執行階段呼叫這個 Excel VSTO 增益集來執行這些計算。

適用對象： 本主題資訊適用於 VSTO 增益集專案。 如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

這個程序包含兩個主要步驟：

  • 在您的 VSTO 增益集中，將物件公開給其他方案。

  • 在其他方案中，存取您的 VSTO 增益集所公開的物件，並呼叫該物件的成員。

可以呼叫增益集程式碼的方案類型

您可以將 VSTO 增益集中的物件公開給下列類型的方案：

  • 和 VSTO 增益集載入到相同應用程式處理序之文件內的 Visual Basic for Applications (VBA) 程式碼。

  • 和 VSTO 增益集載入到相同應用程式處理序的文件層級自訂。

  • 使用 Visual Studio 中的 Office 專案範本建立的其他 VSTO 增益集。

  • COM VSTO 增益集 (即直接實作 IDTExtensibility2 介面的 VSTO 增益集)。

  • 任何在與 VSTO 增益集不同的處理序中執行的方案 (這類方案也稱為 「跨處理序用戶端」(Out-Of-Process Client))。 這包括將 Office 應用程式自動化的應用程式 (例如 Windows Forms 或主控台應用程式)，以及在不同處理序中載入的 VSTO 增益集。

將物件公開給其他方案

若要將您 VSTO 增益集中的物件公開給其他方案，請在 VSTO 增益集中執行下列步驟：

  1. 定義您要公開給其他方案的類別。

  2. 覆寫 RequestComAddInAutomationService 類別中的 ThisAddIn 方法。 傳回您要公開給其他方案之類別的執行個體。

定義您要公開給其他方案的類別

您要公開的類別至少必須是公用的、其 ComVisibleAttribute 屬性必須設為 true，而且必須公開 IDispatch 介面。

公開 IDispatch 介面的建議方法是執行下列步驟：

  1. 定義介面，這個介面宣告您要公開給其他方案的成員。 您可以在 VSTO 增益集專案中定義這個介面。 不過，如果您要將類別公開給非 VBA 方案，可以在個別的類別庫專案中定義這個介面，讓呼叫您 VSTO 增益集的方案不需參考您的 VSTO 增益集專案，就可以參考這個介面。

  2. 將 ComVisibleAttribute 屬性套用至這個介面，並將這個屬性設為 true。

  3. 修改您的類別以實作這個介面。

  4. 將 ClassInterfaceAttribute 屬性套用至您的類別，並將此屬性設定為 ClassInterfaceType 列舉的 None 值。

  5. 如果您要將此類別公開給跨處理序用戶端，可能還必須執行下列作業：

    下列程式碼範例示範 AddInUtilities 類別，該類別具有其他方案可以呼叫的 ImportData 方法。 若要在更詳細的逐步解說內容中查看此程式碼，請參閱逐步解說：從 VBA 呼叫 VSTO 增益集的程式碼。

    [ComVisible(true)]
public interface IAddInUtilities
{
    void ImportData();
}

[ComVisible(true)]
[ClassInterface(ClassInterfaceType.None)]
public class AddInUtilities : IAddInUtilities
{
    // This method tries to write a string to cell A1 in the active worksheet.
    public void ImportData()
    {
        Excel.Worksheet activeWorksheet = Globals.ThisAddIn.Application.ActiveSheet as Excel.Worksheet;

        if (activeWorksheet != null)
        {
            Excel.Range range1 = activeWorksheet.get_Range("A1", System.Type.Missing);
            range1.Value2 = "This is my data";
        }
    }
}

將類別公開給 VBA

當您執行上述步驟時，VBA 程式碼只能呼叫您在介面中宣告的方法。 VBA 程式碼無法呼叫您類別中的其他任何方法，包括您的類別從 Object等基底類別取得的方法。

您也可以透過將 ClassInterfaceAttribute 屬性設定為 ClassInterfaceType 列舉的 AutoDispatch 或 AutoDual 值，以公開 IDispatch 介面。 如果公開介面，則不需要在個別的介面中宣告方法。 不過，VBA 程式碼可以呼叫您類別中的任何公用和非靜態方法，包括從 Object等基底類別取得的方法。 此外，使用早期繫結的跨處理序用戶端無法呼叫您的類別。

將類別公開給跨處理序用戶端

如果您要將 VSTO 增益集中的類別公開給跨處理序用戶端，您應該從 StandardOleMarshalObject 衍生類別，以確保跨處理序用戶端可以呼叫所公開的 VSTO 增益集物件。 否則，當嘗試在跨處理序用戶端中取得所公開的物件執行個體時，可能會意外失敗。

此失敗是因為所有對 Office 應用程式物件模型的呼叫都必須在主要 UI 執行緒中進行，但是跨處理序用戶端會在任意 RPC (遠端程序呼叫) 執行緒中執行對您物件的呼叫。 .NET Framework 中的 COM 封送處理機制並不會切換執行緒，而是會嘗試在連入 RPC 執行緒 (而不是主要 UI 執行緒) 上封送處理對您物件的呼叫。 如果您的物件是衍生自 StandardOleMarshalObject之類別的執行個體，則對您物件的連入呼叫會自動封送處理至當初用以建立已公開物件的執行緒，而該執行緒會成為主應用程式的主要 UI 執行緒。

如需在 Office 方案中使用執行緒的詳細資訊，請參閱 Office 中的執行緒支援。

覆寫 RequestComAddInAutomationService 方法

下列程式碼範例示範如何在您的 VSTO 增益集中覆寫 RequestComAddInAutomationService 類別中的 ThisAddIn 。 範例假設您已經定義想要公開給其他方案，且名稱為 AddInUtilities 的類別。 若要在更詳細的逐步解說內容中查看此程式碼，請參閱逐步解說：從 VBA 呼叫 VSTO 增益集的程式碼。

private AddInUtilities utilities;

protected override object RequestComAddInAutomationService()
{
    if (utilities == null)
        utilities = new AddInUtilities();

    return utilities;
}

載入 VSTO 增益集時，Visual Studio Tools for Office Runtime 會呼叫 RequestComAddInAutomationService 方法。 執行階段會將傳回的物件指派給代表 VSTO 增益集之 COMAddIn 物件的 COMAddIn.Object 屬性。 這個 COMAddIn 物件可供其他 Office 方案以及將 Office 自動化的方案使用。

從其他方案存取物件

若要呼叫您 VSTO 增益集中公開的物件，請在用戶端方案中執行下列步驟：

  1. 取得代表已公開 VSTO 增益集的 COMAddIn 物件。 用戶端可以使用主 Office 應用程式的物件模型中的 Application.COMAddIns 屬性，存取所有可用的 VSTO 增益集。

  2. 存取 COMAddIn 物件的 COMAddIn.Object 屬性。 這個屬性會傳回 VSTO 增益集中已公開的物件。

  3. 呼叫已公開物件的成員。

    對於 VBA 用戶端和非 VBA 用戶端，您使用 COMAddIn.Object 屬性之傳回值的方式會不同。 對於跨處理序用戶端，還需要其他程式碼才能避免可能的競爭情形。

從 VBA 方案存取物件

下列程式碼範例示範如何使用 VBA 呼叫 VSTO 增益集所公開的方法。 這個 VBA 巨集會呼叫 ImportData ExcelImportData VSTO 增益集中定義的方法。 若要在更詳細的逐步解說內容中查看此程式碼，請參閱逐步解說：從 VBA 呼叫 VSTO 增益集的程式碼。

Sub CallVSTOMethod()
    Dim addIn As COMAddIn
    Dim automationObject As Object
    Set addIn = Application.COMAddIns("ExcelImportData")
    Set automationObject = addIn.Object
    automationObject.ImportData
End Sub

從非 VBA 方案存取物件

在非 VBA 方案中，您必須將 COMAddIn.Object 屬性值轉型為方案所實作的介面，然後才能在介面物件上呼叫已公開的方法。 下列程式碼範例示範如何從使用 Visual Studio 中的 Office Developer Tools 所建立的不同 VSTO 增益集呼叫 ImportData 方法。

object addInName = "ExcelImportData";
Office.COMAddIn addIn = Globals.ThisAddIn.Application.COMAddIns.Item(ref addInName);
ExcelImportData.IAddInUtilities utilities = (ExcelImportData.IAddInUtilities)addIn.Object;
utilities.ImportData();

在這個範例中，如果您嘗試將 COMAddIn.Object 屬性的值轉型為 AddInUtilities 類別 (而不是 IAddInUtilities 介面)，則程式碼會擲回 InvalidCastException。

相關內容