Vytvoření doplňku Modelu COM pro Office pomocí visual C# .NET

Článek
06/20/2023
Platí pro:

Microsoft Office XP, Microsoft Office 2003, Microsoft Office 2007

Souhrn

Microsoft Office XP, Microsoft Office 2003 a Microsoft Office 2007 podporují jednotnou architekturu návrhu pro vytváření doplňků aplikací pro vylepšení a řízení aplikací Office. Tyto doplňky se nazývají doplňky modelu COM (Microsoft Component Object Model). Tento podrobný článek popisuje doplňky modelu Com pro Office a popisuje, jak vytvořit doplněk modelu COM pro Office pomocí microsoft Visual C# .NET.

Rozhraní IDTExensibility2

Doplněk modelu COM je procesový server COM nebo knihovna DLL (ActiveX Dynamic Link Library), která implementuje rozhraní IDTExensibility2, jak je popsáno v knihovně typů návrháře doplňků Microsoftu (Msaddndr.dll). Všechny doplňky modelu COM dědí z tohoto rozhraní a musí implementovat každou z pěti metod.

OnConnection

Událost OnConnection se aktivuje při každém připojení doplňku modelu COM. Doplněk může být připojený při spuštění, koncovým uživatelem nebo službou Automation. Pokud OnConnection událost vrátí úspěšně, doplněk se říká, že se má načíst. Pokud se vrátí chybová zpráva, hostitelská aplikace okamžitě uvolní odkaz na doplněk a objekt se zničí.

Událost OnConnection má následující čtyři parametry:

Aplikace: Odkaz na objekt hostitelské aplikace.
ConnectMode: Konstanta, která určuje způsob připojení doplňku. Doplněk je možné připojit následujícími způsoby:
- ext_cm_AfterStartup: Doplněk spustí koncový uživatel z dialogového okna Doplňky modelu COM.
- ext_cm_CommandLine: Doplněk je připojený z příkazového řádku. Všimněte si, že to neplatí pro vytváření doplňků modelu COM pro aplikace Office.
- ext_cm_External: Doplněk je připojený externí aplikací prostřednictvím služby Automation. Všimněte si, že to neplatí pro vytváření doplňků modelu COM pro aplikace Office.
- ext_cm_Startup: Doplněk spustí hostitel při spuštění aplikace. Toto chování je řízeno nastavením v registru.
AddInInst: Odkaz na objekt COMAddIn, který odkazuje na tento doplněk v kolekci COMAddIns pro hostitelskou aplikaci.
Vlastní: Pole hodnot typu Variant, které mohou obsahovat uživatelsky definovaná data.

OnDisconnection

Událost OnDisconnection se aktivuje, když je doplněk modelu COM odpojený a těsně před uvolněním z paměti. Doplněk by měl v této události provést vyčištění prostředků a obnovit všechny změny provedené v hostitelské aplikaci.

Událost OnDisconnection přebírá následující dva parametry:

RemoveMode: Konstanta, která určuje způsob odpojení doplňku. Doplněk je možné odpojit následujícími způsoby:
- ext_dm_HostShutdown: Doplněk se odpojí, když se hostitelská aplikace zavře.
- ext_dm_UserClosed: Doplněk odpojil koncový uživatel nebo kontroler Automation.
Vlastní: Pole hodnot typu Variant, které mohou obsahovat uživatelsky definovaná data.

OnAddInsUpdate

Událost OnAddInsUpdate se aktivuje, když se změní sada registrovaných doplňků modelu COM. Jinými slovy, kdykoli je doplněk modelu COM nainstalován nebo odebrán z hostitelské aplikace, tato událost se aktivuje.

OnStartupComplete a OnBeginShutdown

Jak OnStartupComplete metoda a OnBeginShutdown metoda jsou volány, když hostitelská aplikace opustila nebo vstupuje do stavu, ve kterém by se měla předejít interakci uživatele, protože aplikace je zaneprázdněn načítání nebo uvolňování sebe z paměti. OnStartupComplete Metoda je volána pouze v případě, že doplněk byl připojen během spuštění a OnBeginShutdown metoda je volána pouze v případě, že hostitel odpojí doplněk během vypnutí.

Vzhledem k tomu, že uživatelské rozhraní hostitelské aplikace je při aktivaci těchto událostí plně aktivní, může být jediným způsobem provedení určitých akcí, které by jinak byly nedostupné z události OnConnection a události OnDisconnection.

Registrace doplňku modelu COM

Kromě běžné registrace modelu COM se doplněk modelu COM musí zaregistrovat ke každé aplikaci Office, ve které běží. Pokud se chcete zaregistrovat u konkrétní aplikace, měl by doplněk vytvořit podklíč s použitím jeho Identifikátoru ProgID jako názvu klíče v následujícím umístění:

HKEY_CURRENT_USER\Software\Microsoft\Office\OfficeApp\Addins\ProgID

Doplněk může zadat hodnoty v tomto umístění klíče pro popisný zobrazovaný název i úplný popis. Kromě toho by měl doplněk určit požadované chování načítání pomocí hodnoty DWORD s názvem LoadBehavior. Tato hodnota určuje způsob načtení doplňku hostitelskou aplikací a skládá se z kombinace následujících hodnot:

0 = Odpojit – nenačte se.
1 = Připojeno – je načteno.
2 = Bootload – načtení při spuštění aplikace.
8 = DemandLoad – načtení pouze v případě, že o to uživatel požádá.
16 = ConnectFirstTime – Načtení pouze jednou (při příštím spuštění)

Zadaná typická hodnota je 0x03 (Připojeno | bootload).

Doplňky, které implementují IDTExtensibility2, by měly také určovat hodnotu DWORD s názvem CommandLineSafe , která určuje, jestli jsou doplňky bezpečné pro operace, které nepodporují uživatelské rozhraní. Hodnota 0x00 označuje false a hodnota 0x01 označuje true.

Vytvoření doplňku modelu COM pomocí jazyka Visual C# .NET

Jak už bylo zmíněno dříve, doplněk modelu COM pro Office je procesový server COM aktivovaný aplikací Office prostřednictvím vrstvy runtime modelu COM. Proto vývoj doplňku modelu COM v .NET vyžaduje, aby byla komponenta doplňku implementována v rozhraní .NET a poté vystavena klientům modelu COM (tj. aplikacím Office) prostřednictvím vrstvy vzájemné spolupráce modelu COM.

Chcete-li vytvořit doplněk modelu COM v jazyce Visual C# .NET, postupujte takto:

V jazyce Visual C# .NET vytvořte projekt knihovny tříd.
Přidejte odkaz na knihovnu typů, která implementuje IDTExtensibility2. Primární definiční sestavení je již k dispozici pod názvem Rozšiřitelnost.
Přidejte odkaz na knihovnu objektů Microsoft Office. Primární definiční sestavení je již k dispozici pod názvem Office.
Vytvořte veřejnou třídu v knihovně tříd, která implementuje IDTExtensibility2.
Po sestavení knihovny tříd zaregistrujte knihovnu pro interoperabilitu modelu COM. Uděláte to tak, že pro tuto knihovnu tříd vygenerujete sestavení se silným názvem a pak ho zaregistrujete pomocí zprostředkovatele komunikace s objekty COM. Pomocí Regasm.exe můžete zaregistrovat komponentu .NET pro interoperabilitu modelu COM.
Vytvořte položky registru, aby aplikace Office mohly doplněk rozpoznat a načíst.

Můžete provést všechny tyto kroky nebo můžete vytvořit projekt .NET typu Sdílený doplněk. Spustí se Průvodce rozšiřitelností, který vám pomůže vytvořit doplněk modelu COM v .NET.

Průvodce rozšiřitelnost vytvoří projekt knihovny tříd Visual C# .NET spolu s třídou Connect, která implementuje rozhraní IDTExtensibility2. Vygeneruje se také kostra kódu, který implementuje prázdné členy IDTExtensibility. Tento projekt obsahuje odkazy na rozšiřitelnost a sestavení Office. Nastavení sestavení projektu má vybranou možnost Zaregistrovat pro zprostředkovatele komunikace s objekty COM. Vygeneruje se soubor klíče sestavení (.snk) a odkazuje se na atribut AssemblyKeyfile v Assemblyinfo.vb.

Spolu s projektem knihovny tříd průvodce vygeneruje projekt instalace, který můžete použít k nasazení doplňku modelu COM na jiných počítačích. V případě potřeby můžete tento projekt odebrat.

Podrobný příklad

V nabídce Soubor v aplikaci Microsoft Visual Studio .NET klepněte na tlačítko Novýa klepněte na tlačítko Projekt.
V dialogovém okně Nový projekt rozbalte položku Jiné projekty v části Typy projektů, vyberte projekty rozšiřitelnosti a pak vyberte šablonu Sdílený doplněk.
Jako název doplňku zadejte MyCOMAddin a klikněte na OK.
Po zobrazení Průvodce rozšiřitelností postupujte takto:
1. Na stránce 1 vyberte vytvořit doplněk pomocí Visual C# a potom klepněte na tlačítko Další.
2. Na stránce 2 vyberte následující hostitelské aplikace a potom klepněte na tlačítko Další:
  - Microsoft Word
  - Microsoft PowerPoint
  - Microsoft Outlook
  - Microsoft Excel
  - Microsoft Access
3. Na stránce 3 zadejte název a popis doplňku a klepněte na tlačítko Další.
  
  Poznámka Název a popis doplňku se zobrazí v dialogovém okně doplňku modelu COM v aplikaci Office.
4. Na stránce 4 vyberte všechny dostupné možnosti a klepněte na tlačítko Další.
5. Klikněte na tlačítko Dokončit.
V nabídce Projekt klikněte na Přidat odkaz. Klikněte na System.Windows.Forms.DLL v seznamu součástí, klikněte na Vybrat a potom klikněte na OK.
Do seznamu oborů názvů ve třídě Connect přidejte následující:
```
using System.Reflection;
```
Přidejte do třídy Connect následujícího člena:
```
private CommandBarButton MyButton;
```

Implementujte kód pro členy IDTExtensibility2 ve třídě Connect následujícím způsobem:

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"); }

Sestavte a otestujte doplněk modelu COM. Postupujte takto:
1. V nabídce Sestavení klikněte na Sestavit řešení. Všimněte si, že sestavení doplňku modelu COM registruje třídu .NET s interoperabilitou modelu COM.
2. Spusťte jednu z aplikací Office, které jste vybrali jako hostitelské aplikace pro doplněk (například Microsoft Word nebo Microsoft Excel).
3. Po spuštění doplňku se aktivuje událost OnStartupComplete doplňku a zobrazí se zpráva. Zavřete okno se zprávou. Všimněte si, že doplněk přidal na standardní panel nástrojů nové vlastní tlačítko s titulkem Moje vlastní tlačítko.
4. Klikněte na tlačítko Vlastní. Událost Click pro tlačítko je zpracována doplňkem a zobrazí se okno se zprávou. Zavřete okno se zprávou.
5. Ukončete aplikaci Office.
6. Když aplikaci ukončíte, událost OnBeginShutDown se aktivuje a zobrazí se zpráva. Zavřete okno se zprávou a ukončete ukázku.