Erstellen eines Office COM-Add-Ins mit Visual C# .NET

SPRACHE AUSWÄHLEN SPRACHE AUSWÄHLEN
Artikel-ID: 302901 - Produkte anzeigen, auf die sich dieser Artikel bezieht
Dieser Artikel wurde zuvor veröffentlicht unter D302901
Dieser Artikel ist eine Übersetzung des folgenden englischsprachigen Artikels der Microsoft Knowledge Base:
302901 How To Build an Office COM Add-in by Using Visual C# .NET
Bitte beachten Sie: Bei diesem Artikel handelt es sich um eine Übersetzung aus dem Englischen. Es ist möglich, dass nachträgliche Änderungen bzw. Ergänzungen im englischen Originalartikel in dieser Übersetzung nicht berücksichtigt sind. Die in diesem Artikel enthaltenen Informationen basieren auf der/den englischsprachigen Produktversion(en). Die Richtigkeit dieser Informationen in Zusammenhang mit anderssprachigen Produktversionen wurde im Rahmen dieser Übersetzung nicht getestet. Microsoft stellt diese Informationen ohne Gewähr für Richtigkeit bzw. Funktionalität zur Verfügung und übernimmt auch keine Gewährleistung bezüglich der Vollständigkeit oder Richtigkeit der Übersetzung.
Alles erweitern | Alles schließen

Auf dieser Seite

Zusammenfassung

Microsoft Office XP und Microsoft Office 2003 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. Dieser schrittweise aufgebaute Artikel erklärt, was Office COM-Add-Ins sind, und beschreibt, wie Sie Office COM-Add-Ins mithilfe von Microsoft Visual C# .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. Wenn 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 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 Arten 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 dieses Ereignis immer dann ausgelöst wird, wenn ein COM-Add-In installiert oder aus der Host-Anwendung entfernt wurde.

OnStartupComplete und OnBeginShutdown

Die beiden Methoden OnStartupComplete und 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 es einen Teilschlüssel mit seiner Programm-ID als Namen im folgenden Registrierungsschlüssel erstellen:
HKEY_CURRENT_USER\Software\Microsoft\Office\Office-Anwendung\Addins\Programm-ID
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
LoadBehavior
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 auf Anforderung des Benutzers 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
CommandLineSafe
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 C# .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 muss bei der Entwicklung eines COM-Add-Ins in Visual C# .NET die Add-In-Komponente in .NET implementiert und den COM-Clients (d. h. den Office-Anwendungen) anschließend über die COM-Interop-Schicht angezeigt werden.

Gehen Sie folgendermaßen vor, um ein COM-Add-In in Visual C# .NET zu erstellen:
  1. Erstellen Sie ein Klassenbibliothekprojekt in Visual C# .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 die entsprechenden 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 C# .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 in Microsoft Visual Studio .NET im Menü Datei auf Neu, und klicken Sie auf Projekt.
  2. Erweitern Sie im Dialogfeld Neues Projekt den Eintrag Andere Projekte unter Projekttypen, wählen Sie die Option Erweiterungsprojekte, und klicken Sie auf die Vorlage Gemeinsames Add-In.
  3. Geben Sie MyCOMAddin als Namen des Add-Ins ein, und klicken Sie auf OK.
  4. Gehen Sie folgendermaßen vor, wenn der Erweiterungs-Assistent angezeigt wird:
    1. Wählen Sie auf Seite 1 die Option Ein Add-In mit Visual C# erstellen, und klicken Sie auf Weiter.
    2. Wählen Sie auf Seite 2 die folgenden Host-Anwendungen aus, und klicken Sie 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 ein, und klicken Sie 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 Seite 4 alle verfügbaren Optionen aus, und klicken Sie auf Weiter.
    5. Klicken Sie auf Fertig stellen.
  5. Klicken Sie im Menü Projekt auf Verweis hinzufügen. Klicken Sie in der Liste der Komponenten auf System.Windows.Forms.DLL, klicken Sie auf Auswählen und anschließend auf OK.
  6. Fügen Sie der Liste der Namespaces in der Klasse Connect den folgenden Code hinzu:
    using System.Reflection;
  7. Fügen Sie der Klasse Connect den folgenden Member hinzu:
    private CommandBarButton MyButton; 
  8. Implementieren Sie den Code für die Members von IDTExtensibility2 in der Klasse Connect 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"); }
    					
  9. Erstellen und testen Sie das COM-Add-In. Gehen Sie hierzu folgendermaßen vor:
    1. Klicken Sie im Menü Erstellen auf Projektmappe 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 OnStartupComplete ausgelöst und ein Meldungsfeld angezeigt. Schließen Sie dieses Meldungsfeld. 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.
    4. Klicken Sie auf My Custom Button. Das Click-Ereignis für die Schaltfläche wird vom Add-In verarbeitet, und es wird ein Meldungsfeld angezeigt. Schließen Sie dieses Meldungsfeld.
    5. Beenden Sie die Office-Anwendung.
    6. Wenn Sie die Anwendung beenden, wird das Ereignis OnBeginShutDown ausgelöst, und es wird eine Meldung angezeigt. Schließen Sie dieses Meldungsfeld, um die Demonstration zu beenden.

Informationsquellen

Weitere Informationen zum Erstellen von COM-Add-Ins finden Sie im folgenden Artikel der Microsoft Knowledge Base:
190253 INFO: VB6-Designer funktionieren nicht in VB5

Eigenschaften

Artikel-ID: 302901 - Geändert am: Montag, 19. März 2007 - Version: 8.1
Die Informationen in diesem Artikel beziehen sich auf:
  • Microsoft Visual C# .NET 2003 Standard Edition
  • 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
Keywords: 
kbautomation kbhowtomaster KB302901
Microsoft stellt Ihnen die in der Knowledge Base angebotenen Artikel und Informationen als Service-Leistung zur Verfügung. Microsoft übernimmt keinerlei Gewährleistung dafür, dass die angebotenen Artikel und Informationen auch in Ihrer Einsatzumgebung die erwünschten Ergebnisse erzielen. Die Entscheidung darüber, ob und in welcher Form Sie die angebotenen Artikel und Informationen nutzen, liegt daher allein bei Ihnen. Mit Ausnahme der gesetzlichen Haftung für Vorsatz ist jede Haftung von Microsoft im Zusammenhang mit Ihrer Nutzung dieser Artikel oder Informationen ausgeschlossen.

Ihr Feedback an uns

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com