文章編號: 302901 - 上次校閱: 2006年3月30日 - 版次: 7.4

如何使用 Visual C# .NET 建置 Office COM 增益集

檢視此文章適用的產品。
系統提示本文適用於您使用的作業系統之外的作業系統。與您不相關的文章內容已停用。

在此頁中

全部展開 | 全部摺疊

結論

Microsoft Office XP 和 Microsoft Office 2003 支援統一的設計架構，可用於建置應用程式增益集以利增強與控制 Office 應用程式。這些增益集稱為 COM 增益集。本文將逐步告訴您 Office COM 增益集的相關資訊，及如何使用 Microsoft Visual C# .NET 建置 Office COM 增益集。

回此頁最上方

IDTExensibility2 介面

如「Microsoft 增益集設計工具」型別程式庫 (Msaddndr.dll) 所述，COM 增益集是實作 IDTExensibility2 介面的同處理序 COM 伺服器或 ActiveX 動態連結程式庫 (DLL)。所有的 COM 增益集均繼承自此介面，且必須實作此介面的五個方法。

OnConnection

每當連接 COM 增益集時，都將觸發 OnConnection 事件。連接增益集的可能方式包括：啟動時連接、由使用者連接，或透過 Automation 連接。如果 OnConnection 成功回傳，即表示已載入增益集。但若傳回錯誤訊息，主應用程式將立刻釋放其對增益集的參考並終結物件。

OnConnection 接受下列四個參數：
  • Application - 主應用程式物件的參考。
  • ConnectMode - 指定如何連接增益集的常數。連接增益集的可行方式如下：
    • ext_cm_AfterStartup - 使用者從 [COM 增益集] 對話方塊啟動增益集。
    • ext_cm_CommandLine - 從命令列連接增益集。請注意，此方式不適用於為 Office 應用程式建置 COM 增益集。
    • ext_cm_External - 外部應用程式透過 Automation 連接增益集。請注意，此方式不適用於為 Office 應用程式建置 COM 增益集。
    • ext_cm_Startup - 主應用程式啟動時啟動增益集。此行為是由登錄中的設定所控制。
  • AddInInst - 主應用程式的 COMAddIns 集合中 COMAddIn 物件的參考，代表目前連接的增益集。
  • Custom - Variant 型別值的陣列，存放使用者定義的資料。

OnDisconnection

當 COM 增益集已中斷連接而從記憶體卸載之前，將觸發 OnDisconnection 事件。增益集應在此事件中執行清理資源的工作，並還原對主應用程式所做的一切變更。

OnDisconnection 接受下列兩個參數：
  • RemoveMode - 指定如何中斷連接增益集的常數。中斷連接增益集的可行方式如下：
    • ext_dm_HostShutdown - 主應用程式關閉時中斷連接增益集。
    • ext_dm_UserClosed - 由使用者或 Automation 控制器中斷連接增益集。
  • Custom - Variant 型別值的陣列，存放使用者定義的資料。

OnAddInsUpdate

當已註冊的整組 COM 增益集有所變更時，將觸發 OnAddInsUpdate 事件。也就是說，每當主應用程式安裝或移除 COM 增益集時，都會觸發此事件。

OnStartupComplete 和 OnBeginShutdown

當應用程式正忙於從記憶體載入或卸載其本身時，均應避免與使用者互動，而主應用程式若已解除或即將進入此忙碌狀態，便會呼叫 OnStartupComplete 和 OnBeginShutdown 方法。主應用程式只在啟動期間連接增益集之後呼叫 OnStartupComplete，並且只在關閉期間中斷連接增益集之時呼叫 OnBeginShutdown。

由於觸發這些事件時，主應用程式的使用者介面方為全數可用，某些動作大概只能在這兩個事件中執行，如果透過 OnConnection 和 OnDisconnection 來執行則毫無意義。

回此頁最上方

COM 增益集註冊

除了正規的 COM 註冊外，COM 增益集還必須向其執行所在的每個 Office 應用程式自行註冊。如果要向特定的應用程式自行註冊，增益集應使用其 ProgID 當作機碼的名稱，在下列位置底下建立子機碼：
HKEY_CURRENT_USER\Software\Microsoft\Office\OfficeApp\Addins\ProgID
增益集可在此機碼位置提供值，以代表易記的顯示名稱和完整描述。此外，增益集應使用名為
LoadBehavior
的 DWORD 值指定其載入行為。此值決定主應用程式載入增益集的方式，由下列值的組合所構成：
  • 0 = Disconnect - 不載入。
  • 1 = Connected - 載入。
  • 2 = Bootload - 應用程式啟動時載入。
  • 8 = DemandLoad - 使用者要求時載入。
  • 16 = ConnectFirstTime - 只載入一次 (於下次啟動時)。
其值通常指定為 0x03 (Connected | Bootload)。

實作 IDTExtensibility2 的增益集亦應指定名為
CommandLineSafe
的 DWORD 值，以表示增益集對於不支援使用者介面的作業而言是否安全。0x00 值表示 False，0x01 值則表示 True。

回此頁最上方

如何使用 Visual C# .NET 建置 COM 增益集

如前所述，Office COM 增益集是由 Office 應用程式透過 COM Run-Time 層予以啟動的同處理序 COM 伺服器。因此，使用 .NET 開發 COM 增益集時，必須在 .NET 中實作增益集元件，然後透過 COM Interop 層將元件公開至 COM 用戶端 (即 Office 應用程式)。

如果要使用 Visual C# .NET 建置 COM 增益集，請依照下列步驟執行：
  1. 在 Visual C# .NET 中建立「類別庫」專案。
  2. 針對實作 IDTExtensibility2 的型別程式庫，加入其參考。此項目的主要 Interop 組件以 Extensibility 為名列在其中。
  3. 加入 Microsoft Office 物件程式庫的參考。此項目的主要 Interop 組件以 Office 為名列在其中。
  4. 在類別庫中，建立實作 IDTExtensibility2 的公用類別。
  5. 建置類別庫之後，向 COM Interop 註冊類別庫。如果要執行這項操作，請為類別庫產生強式名稱組件，再向 COM Interop 註冊該組件。使用 Regasm.exe 即可向 COM Interop 註冊 .NET 元件。
  6. 建立登錄項目，讓 Office 應用程式能夠辨認並載入增益集。
您可選擇完成上述所有步驟，也可以建立「分享增益功能」類型的 .NET 專案。第二種方式會啟動「擴充性精靈」，以協助您在 .NET 中建立 COM 增益集。

「擴充性精靈」建立的 Visual C# .NET 類別庫專案中包含實作 IDTExtensibility2 介面的 Connect 類別。其產生的基礎程式碼也實作了 IDTExtensibility 的空成員。這類專案具有 Extensibility 和 Office 組件的參考。專案的建置設定則已選取「註冊 COM Interop」。此外還會產生組件金鑰 (.snk) 檔，並在 Assemblyinfo.vb 中透過 AssemblyKeyfile 屬性 (Attribute) 參照其位置。

除了類別庫專案外，精靈也將產生安裝專案，讓您可用於在其他電腦上部署 COM 增益集。您可以視情況移除此安裝專案。

回此頁最上方

逐步範例

  1. 在 Microsoft Visual Studio .NET 的 [檔案] 功能表上，按一下 [新增]，然後按一下 [專案]。
  2. 在 [新增專案] 對話方塊中，展開 [專案類型] 之下的 [其他專案]，再選取 [擴充性專案]，然後選取 [分享增益功能] 範本。
  3. 輸入 MyCOMAddin 當做增益集的名稱，然後按一下 [確定]。
  4. 當「擴充性精靈」出現時，依照下列步驟執行：
    1. 在第 1 頁選取 [使用 Visual C# 建立增益功能]，然後按一下 [下一步]。
    2. 在第 2 頁選取下列主應用程式，然後按一下 [下一步]：
      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access
    3. 在第 3 頁輸入增益集的名稱和描述，然後按一下 [下一步]。

      注意 增益集的名稱和描述將出現在 Office 應用程式的 [COM 增益集] 對話方塊中。

    4. 在第 4 頁選取所有可用的選項，然後按一下 [下一步]。
    5. 按一下 [完成]。
  5. 在 [專案] 功能表上，按一下 [加入參考]。在元件清單中按一下 [System.Windows.Forms.DLL]，再按一下 [選取]，然後按一下 [確定]。
  6. 在 Connect 類別中，加入下列命名空間清單：
    using System.Reflection;
  7. 在 Connect 類別中，加入下列成員：
    private CommandBarButton MyButton;
  8. 在 Connect 類別中，實作 IDTExtensibility2 的成員，如下列程式碼所示：
    public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom) {
   applicationObject = application;
   addInInstance = addInInst;

   if(connectMode != Extensibility.ext_ConnectMode.ext_cm_Startup)
   {
      OnStartupComplete(ref custom);
   }

}

public void OnDisconnection(Extensibility.ext_DisconnectMode disconnectMode, ref System.Array custom) {
   if(disconnectMode != Extensibility.ext_DisconnectMode.ext_dm_HostShutdown)
   {
      OnBeginShutdown(ref custom);
   }
   applicationObject = null;
}


public void OnAddInsUpdate(ref System.Array custom)
{
}

public void OnStartupComplete(ref System.Array custom)
{
   CommandBars oCommandBars;
   CommandBar oStandardBar;

   try
   {
   oCommandBars = (CommandBars)applicationObject.GetType().InvokeMember("CommandBars", BindingFlags.GetProperty , null, applicationObject ,null);
   }
   catch(Exception)
   {
   // Outlook has the CommandBars collection on the Explorer object.
   object oActiveExplorer;
   oActiveExplorer= applicationObject.GetType().InvokeMember("ActiveExplorer",BindingFlags.GetProperty,null,applicationObject,null);
   oCommandBars= (CommandBars)oActiveExplorer.GetType().InvokeMember("CommandBars",BindingFlags.GetProperty,null,oActiveExplorer,null);
   }

   // Set up a custom button on the "Standard" commandbar.
   try
   {
   oStandardBar = oCommandBars["Standard"];        
   }
   catch(Exception)
   {
   // Access names its main toolbar Database.
   oStandardBar = oCommandBars["Database"];      
   }

   // In case the button was not deleted, use the exiting one.
   try
   {
   MyButton = (CommandBarButton)oStandardBar.Controls["My Custom Button"];
   }
   catch(Exception)
   {
      object omissing = System.Reflection.Missing.Value ;
      MyButton = (CommandBarButton) oStandardBar.Controls.Add(1, omissing , omissing , omissing , omissing);
      MyButton.Caption = "My Custom Button";
      MyButton.Style = MsoButtonStyle.msoButtonCaption;
   }

   // The following items are optional, but recommended. 
   //The Tag property lets you quickly find the control 
   //and helps MSO keep track of it when more than
   //one application window is visible. The property is required
   //by some Office applications and should be provided.
   MyButton.Tag = "My Custom Button";

   // The OnAction property is optional but recommended. 
   //It should be set to the ProgID of the add-in, so that if
   //the add-in is not loaded when a user presses the button,
   //MSO loads the add-in automatically and then raises
   //the Click event for the add-in to handle. 
   MyButton.OnAction = "!<MyCOMAddin.Connect>";

   MyButton.Visible = true;
   MyButton.Click += new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler(this.MyButton_Click);


   object oName = applicationObject.GetType().InvokeMember("Name",BindingFlags.GetProperty,null,applicationObject,null);

   // Display a simple message to show which application you started in.
   System.Windows.Forms.MessageBox.Show("This Addin is loaded by " + oName.ToString()   , "MyCOMAddin");
   oStandardBar = null;
   oCommandBars = null;
}

public void OnBeginShutdown(ref System.Array custom)
{
   object omissing = System.Reflection.Missing.Value ;
   System.Windows.Forms.MessageBox.Show("MyCOMAddin Add-in is unloading.");
   MyButton.Delete(omissing);
   MyButton = null;
}

private void MyButton_Click(CommandBarButton cmdBarbutton,ref bool cancel) {
   System.Windows.Forms.MessageBox.Show("MyButton was Clicked","MyCOMAddin"); }
  9. 建置後測試 COM 增益集。如果要執行這項操作，請依照下列步驟執行：
    1. 在 [建置] 功能表上，按一下 [建置方案]。請注意，建置 COM 增益集會向 COM Interop 註冊 .NET 類別。
    2. 啟動稍早所選取做為增益集主應用程式的其中一個 Office 應用程式 (如 Microsoft Word 或 Microsoft Excel)。
    3. 一旦增益集已啟動，將觸發增益集的 OnStartupComplete 事件，而您會收到訊息。請忽略此訊息方塊。需注意的是，增益集已在一般工具列上新增 [My Custom Button] 自訂按鈕。
    4. 按一下 [My Custom Button]。增益集會處理按鈕的 Click 事件，而您將看到訊息方塊。請忽略此訊息方塊。
    5. 結束 Office 應用程式。
    6. 一旦應用程式結束，將觸發 OnBeginShutDown 事件，而您會收到訊息。請關閉此訊息方塊以結束範例。
回此頁最上方

?考

如需有關撰寫 COM 增益集的詳細資訊，請按一下下面的文件編號，檢視「Microsoft 知識庫」中的文件：
190253? (http://support.microsoft.com/kb/190253/ ) INFO：無法在 VB5 中使用 VB6 設計工具
回此頁最上方
這篇文章中的資訊適用於:
  • Microsoft Visual C# .NET 2003 標準版
  • Microsoft Visual C# .NET 2002 Standard Edition
  • Microsoft Office Excel 2003
  • Microsoft Excel 2002 Standard Edition
  • Microsoft Office Outlook 2003
  • Microsoft Outlook 2002 Standard Edition
  • Microsoft Office PowerPoint 2003
  • Microsoft PowerPoint 2002 Standard Edition
  • Microsoft Office Word 2003
  • Microsoft Word 2002 Standard Edition
回此頁最上方
關鍵字：?
kbautomation kbhowtomaster KB302901
回此頁最上方
Microsoft及(或)其供應商不就任何在本伺服器上發表的文字資料及其相關圖表資訊的恰當性作任何承諾。所有文字資料及其相關圖表均以「現狀」供應，不負任何擔保責任。Microsoft及(或)其供應商謹此聲明，不負任何對與此資訊有關之擔保責任，包括關於適售性、適用於某一特定用途、權利或不侵權的明示或默示擔保責任。Microsoft及(或)其供應商無論如何不對因或與使用本伺服器上資訊或與資訊的實行有關而引起的契約、過失或其他侵權行為之訴訟中的特別的、間接的、衍生性的損害或任何因使用而喪失所導致的之損害、資料或利潤負任何責任。