So erstellen Sie ein Office COM-Add-In mit Visual C# .NET

Artikel
06/20/2023
Gilt für::

Microsoft Office XP, Microsoft Office 2003, Microsoft Office 2007

Zusammenfassung

Microsoft Office XP, Microsoft Office 2003 und Microsoft Office 2007 unterstützen eine einheitliche Entwurfsarchitektur zum Erstellen von Anwendungs-Add-Ins zur Verbesserung und Steuerung von Office-Anwendungen. Diese Add-Ins werden als Com-Add-Ins (Microsoft Component Object Model) bezeichnet. In diesem Schritt-für-Schritt-Artikel werden Office COM-Add-Ins und die Erstellung eines Office COM-Add-Ins mithilfe von Microsoft Visual C# .NET beschrieben.

Die IDTExensibility2-Schnittstelle

Ein COM-Add-In ist ein IN-Process-COM-Server oder eine ActiveX Dynamic Link Library (DLL), die die IDTExensibility2-Schnittstelle implementiert, wie in der Typbibliothek des Microsoft-Add-In-Designers (Msaddndr.dll) beschrieben. Alle COM-Add-Ins erben von dieser Schnittstelle und müssen jede ihrer fünf Methoden implementieren.

Onconnection

Das OnConnection-Ereignis wird ausgelöst, wenn das COM-Add-In verbunden ist. Das Add-In kann beim Start, vom Endbenutzer oder über die Automatisierung verbunden sein. Wenn das OnConnection-Ereignis erfolgreich zurückgegeben wird, wird das Add-In als geladen bezeichnet. Wenn eine Fehlermeldung zurückgegeben wird, gibt die Hostanwendung sofort ihren Verweis auf das Add-In frei, und das Objekt wird zerstört.

Das OnConnection-Ereignis verwendet die folgenden vier Parameter:

Anwendung: Ein Verweis auf das Hostanwendungsobjekt.
ConnectMode: Eine Konstante, die angibt, wie das Add-In verbunden ist. Das Add-In kann auf folgende Weise verbunden werden:
- ext_cm_AfterStartup: Das Add-In wird vom Endbenutzer über das Dialogfeld COM-Add-Ins gestartet.
- ext_cm_CommandLine: Das Add-In ist über die Befehlszeile verbunden. Beachten Sie, dass dies nicht für das Erstellen von COM-Add-Ins für Office-Anwendungen gilt.
- ext_cm_External: Das Add-In wird über die Automatisierung durch eine externe Anwendung verbunden. Beachten Sie, dass dies nicht für das Erstellen von COM-Add-Ins für Office-Anwendungen gilt.
- ext_cm_Startup: Das Add-In wird vom Host beim Starten der Anwendung gestartet. Dieses Verhalten wird durch eine Einstellung in der Registrierung gesteuert.
AddInInst: Ein Verweis auf das COMAddIn-Objekt, das in der COMAddIns-Auflistung für die Hostanwendung auf dieses Add-In verweist.
Benutzerdefiniert: Ein Array von Variant-Typwerten, die benutzerdefinierte Daten enthalten können.

Ondisconnection

Das OnDisconnection-Ereignis wird ausgelöst, wenn das COM-Add-In getrennt wird und kurz bevor es aus dem Speicher entladen wird. Das Add-In sollte in diesem Ereignis alle Ressourcen bereinigen und alle an der Hostanwendung vorgenommenen Änderungen wiederherstellen.

Das OnDisconnection-Ereignis verwendet die folgenden beiden Parameter:

RemoveMode: Eine Konstante, die angibt, wie das Add-In getrennt wurde. Das Add-In kann auf folgende Weise getrennt werden:
- ext_dm_HostShutdown: Das Add-In wird beim Schließen der Hostanwendung getrennt.
- ext_dm_UserClosed: Das Add-In wird vom Endbenutzer oder einem Automatisierungscontroller getrennt.
Benutzerdefiniert: Ein Array von Variant-Typwerten, die benutzerdefinierte Daten enthalten können.

OnAddInsUpdate

Das OnAddInsUpdate-Ereignis wird ausgelöst, wenn sich der Satz registrierter COM-Add-Ins ändert. Mit anderen Worten: Wenn ein COM-Add-In installiert oder aus der Hostanwendung entfernt wird, wird dieses Ereignis ausgelöst.

OnStartupComplete und OnBeginShutdown

Sowohl die OnStartupComplete-Methode als auch die OnBeginShutdown-Methode werden aufgerufen, wenn die Hostanwendung verlassen hat oder in einen Zustand eintritt, in dem Benutzerinteraktionen vermieden werden sollten, da die Anwendung damit beschäftigt ist, sich selbst aus dem Speicher zu laden oder zu entladen. Die OnStartupComplete-Methode wird nur aufgerufen, wenn das Add-In beim Start verbunden war, und die OnBeginShutdown-Methode wird nur aufgerufen, wenn der Host das Add-In beim Herunterfahren trennt.

Da die Benutzeroberfläche für die Hostanwendung vollständig aktiv ist, wenn diese Ereignisse ausgelöst werden, können sie möglicherweise die einzige Möglichkeit sein, bestimmte Aktionen auszuführen, die andernfalls aus dem OnConnection-Ereignis und dem OnDisconnection-Ereignis nicht verfügbar wären.

COM-Add-In-Registrierung

Zusätzlich zur normalen COM-Registrierung muss sich ein COM-Add-In bei jeder Office-Anwendung registrieren, in der es ausgeführt wird. Um sich bei einer bestimmten Anwendung zu registrieren, sollte das Add-In einen Unterschlüssel unter Verwendung seiner ProgID als Namen für den Schlüssel unter dem folgenden Speicherort erstellen:

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

Das Add-In kann werte an dieser Schlüsselposition sowohl für einen Anzeigenamen als auch für eine vollständige Beschreibung bereitstellen. Darüber hinaus sollte das Add-In das gewünschte Ladeverhalten mithilfe eines DWORD-Werts mit dem Namen "LoadBehavior" angeben. Dieser Wert bestimmt, wie das Add-In von der Hostanwendung geladen wird und besteht aus einer Kombination der folgenden Werte:

0 = Trennen - Ist nicht geladen.
1 = Verbunden - Wird geladen.
2 = Startladevorgang – Beim Starten der Anwendung laden.
8 = DemandLoad - Nur laden, wenn vom Benutzer angefordert.
16 = ConnectFirstTime – Nur einmal laden (beim nächsten Start).

Der angegebene typische Wert ist 0x03 (Verbundene | Bootload).

Add-Ins, die IDTExtensibility2 implementieren, sollten auch einen DWORD-Wert namens CommandLineSafe angeben, um anzugeben, ob die Add-Ins für Vorgänge sicher sind, die keine Benutzeroberfläche unterstützen. Der Wert 0x00 gibt "False" an, und der Wert "0x01" gibt "True" an.

Erstellen eines COM-Add-Ins mithilfe von Visual C# .NET

Wie bereits erwähnt, ist ein Office COM-Add-In ein prozessbasierter COM-Server, der von einer Office-Anwendung über die COM-Laufzeitebene aktiviert wird. Daher erfordert die Entwicklung eines COM-Add-Ins in .NET, dass die Add-In-Komponente in .NET implementiert und dann über die COM-Interoperabilitätsebene für die COM-Clients (d. h. die Office-Anwendungen) verfügbar gemacht wird.

Führen Sie die folgenden Schritte aus, um ein COM-Add-In in Visual C# .NET zu erstellen:

Erstellen Sie in Visual C# .NET ein Klassenbibliotheksprojekt.
Fügen Sie einen Verweis auf die Typbibliothek hinzu, die IDTExtensibility2 implementiert. Die primäre Interopassembly dafür ist bereits unter dem Namen Erweiterbarkeit verfügbar.
Fügen Sie einen Verweis auf die Microsoft Office-Objektbibliothek hinzu. Die primäre Interopassembly dafür ist bereits unter dem Namen Office verfügbar.
Erstellen Sie eine öffentliche Klasse in der Klassenbibliothek, die IDTExtensibility2 implementiert.
Nachdem die Klassenbibliothek erstellt wurde, registrieren Sie die Bibliothek für die COM-Interoperabilität. Generieren Sie dazu eine assembly mit starkem Namen für diese Klassenbibliothek, und registrieren Sie sie dann mit COM-Interoperabilität. Sie können Regasm.exe verwenden, um eine .NET-Komponente für die COM-Interoperabilität zu registrieren.
Erstellen Sie Registrierungseinträge, damit Office-Anwendungen das Add-In erkennen und laden können.

Sie können alle diese Schritte ausführen oder ein .NET-Projekt vom Typ "Freigegebenes Add-In" erstellen. Dadurch wird der Erweiterungs-Assistent gestartet, mit dem Sie ein COM-Add-In in .NET erstellen können.

Der Erweiterbarkeits-Assistent erstellt ein Visual C# .NET-Klassenbibliotheksprojekt zusammen mit einer Connect-Klasse, die die IDTExtensibility2-Schnittstelle implementiert. Der Skelettcode, der die leeren Elemente von IDTExtensibility implementiert, wird ebenfalls generiert. Dieses Projekt enthält Verweise auf Erweiterbarkeits- und Office-Assemblys. Für die Buildeinstellungen des Projekts ist "Für COM-Interoperabilität registrieren" ausgewählt. Die Assemblyschlüsseldatei (.snk) wird generiert und im AssemblyKeyfile-Attribut in "Assemblyinfo.vb" referenziert.

Zusammen mit dem Klassenbibliotheksprojekt generiert der Assistent ein Setupprojekt, das Sie zum Bereitstellen des COM-Add-Ins auf anderen Computern verwenden können. Sie können dieses Projekt bei Bedarf entfernen.

Schritt-für-Schritt-Beispiel

Klicken Sie im Menü "Datei" in Microsoft Visual Studio .NET auf "Neu" und dann auf "Projekt".
Erweitern Sie im Dialogfeld "Neues Projekt" unter "Projekttypen" die Option "Andere Projekte", wählen Sie "Erweiterbarkeitsprojekte" und dann die Vorlage "Freigegebenes Add-In" aus.
Geben Sie "MyCOMAddin" als Namen des Add-Ins ein, und klicken Sie dann auf "OK".
Wenn der Erweiterbarkeits-Assistent angezeigt wird, führen Sie die folgenden Schritte aus:
1. Wählen Sie auf Seite 1 "Add-In mit Visual C# erstellen" aus, und klicken Sie dann auf "Weiter".
2. Wählen Sie auf Seite 2 die folgenden Hostanwendungen aus, und klicken Sie dann auf "Weiter":
  - Microsoft Word
  - Microsoft PowerPoint
  - Microsoft Outlook
  - Microsoft Excel
  - Microsoft Access
3. Geben Sie auf Seite 3 einen Namen und eine Beschreibung für das Add-In an, und klicken Sie dann auf "Weiter".
  
  Hinweis Der Name und die Beschreibung des Add-Ins werden im Dialogfeld "COM-Add-In" in der Office-Anwendung angezeigt.
4. Wählen Sie auf Seite 4 alle verfügbaren Optionen aus, und klicken Sie dann auf "Weiter".
5. Klicken Sie auf Fertig stellen.
On the Project menu, click Add Reference. Klicken Sie in der Komponentenliste auf System.Windows.Forms.DLL, klicken Sie auf "Auswählen" und dann auf "OK".
Fügen Sie der Liste der Namespaces in der Connect-Klasse Folgendes hinzu:
```
using System.Reflection;
```
Fügen Sie der Connect-Klasse das folgende Mitglied hinzu:
```
private CommandBarButton MyButton;
```

Implementieren Sie den Code für die Member von IDTExtensibility2 in der Connect-Klasse wie folgt:

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

Erstellen und testen Sie das COM-Add-In. Gehen Sie dazu wie folgt vor:
1. On the Build menu, click Build Solution. Beachten Sie, dass beim Erstellen des COM-Add-Ins die .NET-Klasse mit der COM-Interoperabilität registriert wird.
2. Starten Sie eine der Office-Anwendungen, die Sie als Hostanwendungen für Ihr Add-In ausgewählt haben (z. B. Microsoft Word oder Microsoft Excel).
3. Nachdem das Add-In gestartet wurde, wird das OnStartupComplete-Ereignis des Add-Ins ausgelöst, und Sie erhalten eine Meldung. Schließen Sie das Meldungsfeld. Beachten Sie, dass das Add-In eine neue benutzerdefinierte Schaltfläche mit der Beschriftung "Meine benutzerdefinierte Schaltfläche" zur Standardsymbolleiste hinzugefügt hat.
4. Klicken Sie auf "Meine benutzerdefinierte Schaltfläche". Das Click-Ereignis für die Schaltfläche wird vom Add-In behandelt, und Sie erhalten ein Meldungsfeld. Schließen Sie das Meldungsfeld.
5. Beenden Sie die Office-Anwendung.
6. Wenn Sie die Anwendung beenden, wird das OnBeginShutDown-Ereignis ausgelöst, und Sie erhalten eine Nachricht. Schließen Sie das Meldungsfeld, um die Demonstration zu beenden.