HOW TO：使用 Visual C# .NET 產生 Office COM 增益集

轉：http://support.microsoft.com/kb/302901/zh-cn概要

Microsoft Office XP 和 Microsoft Office 2003 都支援一種新的統一的設計結構，這種結構用於產生應用程式增益集以增強和控制 Office 應用程式。這些增益集叫做 COM 增益集。本文逐步討論了 Office COM 增益集，並介紹了如何使用 Microsoft Visual C# .NET 產生 Office COM 增益集。

回到頂端

IDTExensibility2 介面

COM 增益集是一種進程內 COM 伺服器或 ActiveX 動態連結程式庫 (DLL)，它實現如 Microsoft 增益集設計器類型庫 (Msaddndr.dll) 中所描述的 IDTExensibility2 介面。所有 COM 增益集都從此介面繼承而來，而且都必須實現其五個方法中的每一個方法。

OnConnection

每當串連 COM 增益集時，都會激發 OnConnection 事件。增益集可以在啟動時串連、由終端使用者串連或者通過自動化來串連。如果 OnConnection 成功地返回，就表明已載入了增益集。如果返回錯誤訊息，那麼宿主應用程式就立即釋放其對該增益集的引用，而且該對象將被銷毀。

OnConnection 使用下列四個參數：

•	Application — 一個對宿主應用程式物件的引用。
•	ConnectMode — 一個指定增益集串連方式的常量。增益集可以採取下列幾種方式串連： • ext_cm_AfterStartup — 增益集由終端使用者從 COM 增益集 對話方塊啟動。 • ext_cm_CommandLine — 增益集從命令列串連。注意，此方式不適用於產生 Office 應用程式的 COM 增益集。 • ext_cm_External — 增益集由外部應用程式通過自動化串連。請注意，此方式不適用於產生 Office 應用程式的 COM 增益集。 • ext_cm_Startup — 增益集由宿主在應用程式啟動時啟動。此行為由註冊表中的設定來控制。
•	AddInInst — 一個對 COMAddIn 對象的引用，它引用宿主應用程式的 COMAddIns 集合中的此增益集。
•	Custom — 一個包含 Variant 類型值的數組，它可以儲存使用者定義的資料。

OnDisconnection

當 COM 增益集中斷連線並且在它從記憶體中卸載之前，將激發 OnDisconnection 事件。增益集應在此事件中執行所有資源清理操作，並還原對宿主應用程式所做的任何更改。

OnDisconnection 使用下列兩個參數：

•	RemoveMode — 一個指定增益集中斷連線的方式的常量。增益集可以採用下列方式中斷連線： • ext_dm_HostShutdown —增益集在宿主應用程式關閉時中斷連線。 • ext_dm_UserClosed — 增益集由終端使用者或自動化控制器中斷連線。
•	Custom — 一個包含 Variant 類型值的數組，它可以儲存使用者定義的資料。

OnAddInsUpdate

當註冊的 COM 增益集集發生變化時，將激發 OnAddInsUpdate 事件。換言之，每當安裝 COM 增益集或者從宿主應用程式中刪除 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 運行時層啟用的進程內 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 屬性中進行引用。

除類庫項目外，該嚮導還將產生一個安裝項目，該項目可用於在其他電腦上部署 COM 增益集。在需要時可以刪除此項目。

回到頂端

分步樣本

1.	在 Microsoft Visual Studio .NET 的檔案菜單上，單擊建立，然後單擊項目。
2.	在建立項目對話方塊中，展開項目類型下的其他項目，選擇擴充性項目，然後選擇共用的增益集模板。
3.	鍵入 MyCOMAddin 作為該增益集的名稱，然後單擊確定。
4.	“擴充性嚮導”出現後，請按照下列步驟操作： a. 在第 1 頁，選擇使用 Visual C# 建立增益集，然後單擊下一步。 b. 在第 2 頁，選擇下面的宿主應用程式，然後單擊下一步： • Microsoft Word • Microsoft PowerPoint • Microsoft Outlook • Microsoft Excel • Microsoft Access c. 在第 3 頁上，輸入該增益集的名稱和描述，然後單擊下一步。 注意：該增益集的名稱和描述出現在 Office 應用程式的 COM 增益集對話方塊中。 d. 在第 4 頁，選擇所有可用的選項，然後單擊下一步。 e. 單擊完成。
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 增益集。為此，請按照下列步驟操作： a. 在產生菜單上，單擊產生解決方案。請注意，產生 COM 增益集的過程中實際上就向 COM interop 註冊了 .NET 類。 b. 啟動一個您選作增益集的宿主應用程式的 Office 應用程式（例如，Microsoft Word 或 Microsoft Excel）。 c. 增益集啟動之後，將激發其 OnStartupComplete 事件，您會收到一個訊息框。請關閉該訊息框。請注意，增益集向標準工具列中添加了一個新的標題為“My Custom Button”（我的自訂按鈕）的自訂按鈕。 d. 單擊 My Custom Button（我的自訂按鈕）。該按鈕的 Click 事件將由增益集來處理，而且您會收到一個訊息框。請關閉該訊息框。 e. 退出該 Office 應用程式。 f. 退出該應用程式時，將激發 OnBeginShutDown 事件，您會收到一個訊息框。關閉該訊息框以結束示範。