Erstellen eines Office COM-Add-Ins mit Visual Basic .NET

Microsoft Office 2000 und höhere Versionen unterstützen eine neuartige, einheitliche Architektur für die Entwicklung von Anwendungs-Add-Ins, mit deren Hilfe Office-Anwendungen optimiert und gesteuert werden können. Diese Add-Ins werden "COM-Add-Ins" genannt. In diesem Artikel werden COM-Add-Ins für Office Schritt für Schritt beschrieben. Außerdem wird erklärt, wie Sie Office-COM-Add-Ins mithilfe von Microsoft Visual Basic .NET erstellen können.

Die IDTExtensibility2-Schnittstelle

Ein COM-Add-In ist ein prozessinterner COM-Server bzw. eine ActiveX-DLL (Dynamic Link Library), der bzw. die die IDTExensibility2-Schnittstelle wie in der Microsoft Add-In-Designer-Typbibliothek (Msaddndr.dll) beschrieben implementiert. Alle COM-Add-Ins übernehmen Eigenschaften von dieser Schnittstelle und müssen alle fünf Methoden der Schnittstelle implementieren.

OnConnection

Das Ereignis OnConnection wird ausgelöst, wenn das COM-Add-In geladen ist. Das Add-In kann beim Systemstart, durch den Endbenutzer oder durch Automatisierung geladen werden. Wenn das Ereignis OnConnection erfolgreich zurückgegeben wird, ist das Add-In geladen. Falls eine Fehlermeldung zurückgegeben wird, gibt die Host-Anwendung sofort den Verweis auf das Add-In frei, und das Objekt wird zerstört.

In Verbindung mit OnConnection können die folgenden vier Parameter verwendet werden:

• Application (Anwendung) - Ein Verweis auf das Host-Anwendungsobjekt.
• ConnectMode (Verbindungsmodus) - Eine Konstante, die festlegt, wie das Add-In geladen wird. Das Add-In kann auf folgende Arten geladen werden:
  • ext_cm_AfterStartup - Das Add-In wird vom Endbenutzer über das Dialogfeld COM-Add-Ins gestartet.
  • ext_cm_CommandLine - Das Add-In wird über die Befehlszeile geladen. Beachten Sie, dass dies nicht auf das Erstellen von COM-Add-Ins für Office-Anwendungen zutrifft.
  • ext_cm_External - Das Add-In wird mithilfe der Automatisierung über eine externe Anwendung geladen. Beachten Sie, dass dies nicht auf das Erstellen von COM-Add-Ins für Office-Anwendungen zutrifft.
  • ext_cm_Startup - Das Add-In wird beim Starten der Anwendung durch den Host gestartet. Dieses Verhalten wird über eine entsprechende Einstellung in der Registrierung gesteuert.
• AddInInst - Ein Verweis auf das Objekt COMAddIn, das auf dieses Add-In in der Sammlung COMAddIns für die Host-Anwendung verweist.
• Custom - Ein Array von Variant-Typwerten, das benutzerdefinierte Daten enthalten kann.

OnDisconnection

Das Ereignis OnDisconnection wird bei Deaktivierung des COM-Add-Ins kurz vor dem Entladen aus dem Speicher ausgelöst. Das Add-In sollte in diesem Fall die betreffenden Ressourcen freigeben und etwaige Änderungen rückgängig machen, die an der Host-Anwendung vorgenommen wurden.

In Verbindung mit OnDisconnection können die folgenden beiden Parameter verwendet werden:

• RemoveMode - Eine Konstante, die angibt, wie das Add-In deaktiviert wurde. Das Add-In kann auf folgende Weise deaktiviert werden:
  • ext_dm_HostShutdown - Das Add-In wird deaktiviert, wenn die Host-Anwendung geschlossen wird.
  • ext_dm_UserClosed - Das Add-In wird durch den Endbenutzer oder einen Automationscontroller deaktiviert.
• Custom - Ein Array von Variant-Typwerten, das benutzerdefinierte Daten enthalten kann.

OnAddInsUpdate

Das Ereignis OnAddInsUpdate wird ausgelöst, wenn es Änderungen am Satz der registrierten COM-Add-Ins gibt. Dies bedeutet, dass das Ereignis immer dann ausgelöst wird, wenn ein COM-Add-In installiert oder von der Host-Anwendung entfernt wird.

OnStartupComplete und OnBeginShutdown

Sowohl die Methode OnStartupComplete als auch die Methode OnBeginShutdown werden aufgerufen, wenn die Host-Anwendung in einen Zustand gelangt, in dem eine Benutzerinteraktion vermieden werden sollte, weil die Anwendung gerade aus dem Speicher geladen oder entladen wird. OnStartupComplete wird nur aufgerufen, wenn das Add-In während des Starts geladen war. OnBeginShutdown wird nur aufgerufen, wenn der Host das Add-In während des Herunterfahrens des Systems deaktiviert.

Da die Benutzeroberfläche für die Host-Anwendung aktiv ist, wenn diese Ereignisse ausgelöst werden, stellen diese möglicherweise die einzige Möglichkeit dar, bestimmte Aktionen auszuführen, die andernfalls bei OnConnection und OnDisconnection nicht verfügbar wären.

COM-Add-In-Registrierung

Zusätzlich zur herkömmlichen COM-Registrierung muss das COM-Add-In sich bei jeder Office-Anwendung registrieren, in der es ausgeführt wird. Damit das Add-In bei einer bestimmten Anwendung registriert werden kann, muss das Add-In einen Teilschlüssel mit seiner Programm-ID als Namen im folgenden Registrierungsschlüssel erstellen: Für das Add-In können in diesem Registrierungsschlüssel Werte für einen eindeutigen Anzeigenamen und eine vollständige Beschreibung angegeben werden. Außerdem sollte das Add-In sein gewünschtes Ladeverhalten über den DWORD-Wert festlegen. Dieser Wert bestimmt, wie das Add-In von der Host-Anwendung geladen wird. Er setzt sich aus einer Kombination der folgenden Werte zusammen:

• 0 = Disconnect - Nicht geladen.
• 1 = Connected - Geladen.
• 2 = Bootload - Bei Start der Anwendung laden.
• 8 = DemandLoad - Nur nach Anforderung durch den Benutzer laden.
• 16 = ConnectFirstTime - Nur einmal laden (beim nächsten Start).

Der in der Regel angegebene Wert lautet 0x03 (Connected | Bootload).

Add-Ins, die die IDTExtensibility2-Schnittstelle implementieren, sollten außerdem den DWORD-Wert festlegen, um anzugeben, ob die Add-Ins für Vorgänge als sicher zu betrachten sind, die keine Benutzeroberfläche unterstützen. Der Wert 0x00 steht für "False" (Falsch), und der Wert 0x01 steht für "True" (Wahr).

Erstellen eines COM-Add-Ins mit Visual Basic .NET

Wie bereits erwähnt, handelt es sich bei einem Office COM-Add-In um einen prozessinternen COM-Server, der über die COM-Laufzeitebene von einer Office-Anwendung aktiviert wird. Daher ist es bei der Entwicklung eines COM-Add-Ins in Visual Basic .NET erforderlich, die Add-In-Komponente in .NET zu implementieren und dann den COM-Clients (d. h. den Office-Anwendungen) über die COM-Interop-Ebene zur Verfügung zu stellen.

Gehen Sie folgendermaßen vor, um ein COM-Add-In in Visual Basic .NET zu erstellen:

1. Erstellen Sie ein Klassenbibliothekprojekt in Visual Basic .NET.
2. Fügen Sie einen Verweis zur Typbibliothek hinzu, der die IDTExtensibility2-Schnittstelle implementiert. Die primäre Interop-Assembly hierfür ist bereits unter dem Namen Extensibility verfügbar.
3. Fügen Sie der Microsoft Office-Objektbibliothek einen Verweis hinzu. Die primäre Interop-Assembly hierfür ist bereits unter dem Namen Office verfügbar.
4. Erstellen Sie eine öffentliche Klasse in der Klassenbibliothek, die IDTExtensibility2 implementiert.
5. Nachdem die Klassenbibliothek erstellt wurde, registrieren Sie diese für COM-Interop. Generieren Sie zu diesem Zweck eine Assembly mit starkem Namen für diese Klassenbibliothek, und registrieren Sie diese anschließend für COM-Interop. Sie können die Datei "Regasm.exe" zum Registrieren einer .NET-Komponente für COM-Interop verwenden.
6. Erstellen Sie Registrierungseinträge, damit die Office-Anwendungen das Add-In erkennen und laden können.

Sie können entweder alle aufgeführten Schritte ausführen oder ein .NET-Projekt vom Typ Gemeinsames Add-In erstellen. Hierdurch wird der Erweiterungs-Assistent gestartet, der Sie beim Erstellen eines COM-Add-Ins in .NET unterstützt.

Der Erweiterungs-Assistent erstellt ein Visual Basic .NET-Klassenbibliothekprojekt mit einer Connect-Klasse, die die IDTExtensibility2-Schnittstelle implementiert. Das Codegerüst, das die leeren Members von IDTExtensibility implementiert, wird ebenfalls generiert. Dieses Projekt beinhaltet Verweise auf Extensibility- und Office-Assemblies. In den Buildeinstellungen des Projekts ist die Option Für COM-Interop registrieren aktiviert. Die Assembly-Schlüsseldatei (.snk) wird erstellt. Im Attribut AssemblyKeyfile der Datei "Assemblyinfo.vb" wird auf diese Datei verwiesen.

Neben diesem Klassenbibliothekprojekt generiert der Assistent ein Setup-Projekt, mit dem Sie das COM-Add-In für andere Computer bereitstellen können. Sie können dieses Projekt gegebenenfalls auch wieder entfernen.

Beispiel mit schrittweiser Anleitung

1. Klicken Sie im Menü Datei in Microsoft Visual Studio .NET auf Neu, und klicken Sie anschließend auf Projekt.
2. Erweitern Sie im Dialogfeld Neues Projekt den Eintrag Andere Projekte unter Projekttypen, wählen Sie die Option Erweiterungsprojekte, und klicken Sie anschließend auf die Vorlage Gemeinsames Add-In.
3. Geben Sie MyCOMAddin als Namen des Add-Ins ein, und klicken Sie danach auf OK.
4. Gehen Sie wie folgt vor, wenn der Erweiterungs-Assistent angezeigt wird:
   1. Wählen Sie auf Seite 1 die Option Ein Add-In mit Visual Basic erstellen, und klicken Sie auf Weiter.
   2. Wählen Sie auf der Seite 2 die folgenden Host-Anwendungen aus, und klicken Sie anschließend auf Weiter.
      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access
   3. Geben Sie auf der Seite 3 einen Namen und eine Beschreibung für das Add-In ein, und klicken Sie anschließend auf Weiter.
      
      Hinweis: Der Name und die Beschreibung des Add-Ins werden im Dialogfeld COM-Add-In der Office-Anwendung angezeigt.
      
      
   4. Wählen Sie auf der Seite 4 alle verfügbaren Optionen aus, und klicken Sie anschließend auf Weiter.
   5. Klicken Sie auf Fertig stellen.
5. Fügen Sie der Klasse Connect das folgende Member hinzu:

   Dim WithEvents MyButton As CommandBarButton 

6. Implementieren Sie den Code für alle Members von IDTExtensibility2 in der Klasse Connect wie folgt:

        Public Sub OnBeginShutdown(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnBeginShutdown         On Error Resume Next         ' Notify the user you are shutting down, and delete the button.         MsgBox("Our custom Add-in is unloading.")         MyButton.Delete()         MyButton = Nothing      End Sub      Public Sub OnAddInsUpdate(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnAddInsUpdate         '     End Sub      Public Sub OnStartupComplete(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnStartupComplete          Dim oCommandBars As CommandBars         Dim oStandardBar As CommandBar          On Error Resume Next         ' Set up a custom button on the "Standard" command bar.         oCommandBars = applicationObject.CommandBars         If oCommandBars Is Nothing Then             ' Outlook has the CommandBars collection on the Explorer object.             oCommandBars = applicationObject.ActiveExplorer.CommandBars         End If          oStandardBar = oCommandBars.Item("Standard")         If oStandardBar Is Nothing Then             ' Access names its main toolbar Database.              oStandardBar = oCommandBars.Item("Database")          End If          ' In case the button was not deleted, use the exiting one.         MyButton = oStandardBar.Controls.Item("My Custom Button")         If MyButton Is Nothing Then              MyButton = oStandardBar.Controls.Add(1)             With MyButton                 .Caption = "My Custom Button"                 .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.                  .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 clicks the button,                 ' MSO loads the add-in automatically and then raises                 ' the Click event for the add-in to handle.                   .OnAction = "!<MyCOMAddin.Connect>"                  .Visible = True             End With         End If          ' Display a simple message to show which application you started in.         MsgBox("Started in " & applicationObject.Name & ".")           oStandardBar = Nothing         oCommandBars = Nothing       End Sub      Public Sub OnDisconnection(ByVal RemoveMode As Extensibility.ext_DisconnectMode, ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnDisconnection          On Error Resume Next         If RemoveMode <> Extensibility.ext_DisconnectMode.ext_dm_HostShutdown Then _            Call OnBeginShutdown(custom)          applicationObject = Nothing       End Sub      Public Sub OnConnection(ByVal application As Object, ByVal connectMode As Extensibility.ext_ConnectMode, ByVal addInInst As Object, ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnConnection           MsgBox("On Connection In MyAddin")         applicationObject = application         addInInstance = addInInst           ' If you aren't in startup, manually call OnStartupComplete.         If (connectMode <> Extensibility.ext_ConnectMode.ext_cm_Startup) Then _            Call OnStartupComplete(custom)      End Sub       Private Sub MyButton_Click(ByVal Ctrl As Microsoft.Office.Core.CommandBarButton, ByRef CancelDefault As Boolean) Handles MyButton.Click         MsgBox("Our CommandBar button was pressed!")     End Sub 					

7. Erstellen und testen Sie das COM-Add-In. Gehen Sie hierzu folgendermaßen vor:
   1. Klicken Sie im Menü Erstellen auf MyCOMAddin erstellen. Beachten Sie, dass durch das Erstellen des COM-Add-Ins die .NET-Klasse für COM-Interop registriert wird.
   2. Starten Sie eine der Office-Anwendungen, die Sie als Host-Anwendung für Ihr Add-In ausgewählt haben (beispielsweise Microsoft Word oder Microsoft Excel).
   3. Nachdem das Add-In gestartet wurde, wird das Ereignis OnConnection ausgelöst und ein Meldungsfeld angezeigt. Wenn Sie dieses Meldungsfeld schließen, wird das Ereignis OnStartupComplete ausgelöst und ein zweites Meldungsfeld angezeigt. Schließen Sie dieses Meldungsfeld.
   4. Beachten Sie, dass das Add-In eine neue benutzerdefinierte Schaltfläche mit der Beschriftung "My Custom Button" (Meine benutzerdefinierte Schaltfläche) zur Standardsymbolleiste hinzufügt.
   5. Klicken Sie auf My Custom Button. Das Click-Ereignis für die Schaltfläche wird vom Add-In verarbeitet und ein Meldungsfeld wird angezeigt. Schließen Sie dieses Meldungsfeld.
   6. Beenden Sie die Office-Anwendung.
   7. Wenn Sie die Anwendung beenden, wird das Ereignis OnBeginShutDown ausgelöst und ein Meldungsfeld angezeigt. Schließen Sie dieses Meldungsfeld, um die Demonstration zu beenden.

Weitere Informationen zum Erstellen von COM-Add-Ins finden Sie in folgendem Artikel der Microsoft Knowledge Base: Weitere Informationen zur Entwicklung von webbasierten Lösungen für Microsoft Internet Explorer finden Sie auf den folgenden Websites von Microsoft: (c) Microsoft Corporation 2001, Alle Rechte vorbehalten. Beiträge von Ranjit R. Sawant, Microsoft Corporation.