Comment créer un complément COM Office à l’aide de Visual C# .NET

Pour obtenir une version Microsoft Visual Basic .NET de cet article, reportez-vous à la section 302896 .

Pour obtenir une version Microsoft Visual Basic 6.0 de cet article, reportez-vous à la section 238228 .

Pour obtenir une version Microsoft Visual C++ 6.0 de cet article, reportez-vous à la section 230689 .

DANS CETTE TÂCHE.

Résumé

Microsoft Office XP, Microsoft Office 2003 et Microsoft Office 2007 prend en charge une architecture de conception uniforme pour la création d’application des compléments afin d’améliorer et de contrôler les applications Office. Ces compléments sont appelés compléments Microsoft COM Component Object Model (). Cet article traite des compléments COM Office et explique comment créer un complément COM Office à l’aide de Microsoft Visual C# .NET.

L’interface IDTExensibility2

Un complément COM est un serveur COM in-process ou une bibliothèque de liens dynamiques ActiveX (DLL) qui implémente l’interface IDTExensibility2 comme indiqué dans la bibliothèque de types Microsoft Add-in Designer (Msaddndr.dll). Tous les compléments COM héritent de cette interface et doivent implémenter chacune de ses cinq méthodes.

OnConnection

L’événement OnConnection se déclenche dès que le complément COM est connecté. Le complément peut être connecté au démarrage, par l’utilisateur final, ou par le biais de Automation. Si l’événement OnConnection est retournée avec succès, le complément est dit chargé. Si un message d’erreur est renvoyé, l’application hôte libère immédiatement sa référence au complément et l’objet est détruit.

L’événement OnConnection prend les quatre paramètres suivants :
  • Application: une référence à l’objet d’application hôte.
  • ConnectMode: une constante qui spécifie comment le complément est connecté. Le complément peut être connecté dans l’une des manières suivantes :
    • ext_cm_AfterStartup: le complément est démarré par l’utilisateur final à partir de la boîte de dialogue compléments COM .
    • ext_cm_CommandLine: le complément est connecté à partir de la ligne de commande. Notez que cela ne s’applique pas à la création de compléments COM pour les applications Office.
    • ext_cm_External: le complément est connecté par une application externe via Automation. Notez que cela ne s’applique pas à la création de compléments COM pour les applications Office.
    • ext_cm_Startup: le complément est démarré par l’hôte au démarrage de l’application. Ce comportement est contrôlé par un paramètre dans le Registre.
  • AddInInst: une référence à l’objet COMAddIn qui fait référence à ce complément dans la collection COMAddIns pour l’application hôte.
  • Personnalisé: un tableau de valeurs de type Variant qui peut contenir des données définies par l’utilisateur.

OnDisconnection

L’événement OnDisconnection se déclenche quand le complément COM est déconnecté et juste avant qu’il soit déchargé de la mémoire. Le complément doit effectuer tout nettoyage des ressources dans cet événement et restaurer tout changement apporté à l’application hôte.

L’événement OnDisconnection prend les deux paramètres suivants :
  • RemoveMode: une constante qui spécifie comment le complément a été déconnecté. Le complément peut être déconnecté de la manière suivante :
    • ext_dm_HostShutdown: le complément est déconnecté lors de la fermeture de l’application hôte.
    • ext_dm_UserClosed: le complément est déconnecté par l’utilisateur final ou un contrôleur Automation.
  • Personnalisé: un tableau de valeurs de type Variant qui peut contenir des données définies par l’utilisateur.

OnAddInsUpdate

L’événement OnAddInsUpdate se déclenche lorsque le jeu de compléments COM inscrits change. En d’autres termes, chaque fois qu’un complément COM est installé ou supprimé de l’application hôte, cet événement se déclenche.

OnStartupComplete et OnBeginShutdown

À la fois la méthode OnStartupComplete et la méthode OnBeginShutdown sont appelées lorsque l’application hôte quitte ou est un état dans laquelle l’utilisateur interaction doit être évitée car l’application est en cours de chargement ou de se décharger de la mémoire. La méthode OnStartupComplete est appelée uniquement si le complément a été connecté au démarrage, et la méthode OnBeginShutdown est appelée uniquement si l’hôte déconnecte le complément lors de l’arrêt.

Étant donné que l’interface utilisateur de l’application hôte est totalement active lorsque ces événements se déclenchent, ils peuvent être le seul moyen d’effectuer certaines actions qui sinon ne seraient pas disponibles à partir de l’événement OnConnection et l’événement OnDisconnection .

Enregistrement du complément COM

Outre l’inscription COM normale, un complément COM doit s’enregistrer auprès de chaque application Office dans laquelle il s’exécute. Pour s’inscrire dans une application particulière, le complément doit créer une sous-clé, en utilisant son ProgID comme nom pour la clé, sous l’emplacement suivant :
HKEY_CURRENT_USER\Software\Microsoft\Office\<OfficeApp>\Addins\<ProgID>
Le complément peut fournir des valeurs à cet emplacement de clé pour un nom d’affichage convivial et une description complète. En outre, le complément doit spécifier son comportement au chargement à l’aide d’une valeur DWORD appelée LoadBehavior. Cette valeur détermine comment le complément est chargé par l’application hôte et se compose d’une combinaison des valeurs suivantes :
  • 0 = Disconnect - n’est pas chargé.
  • 1 = Connected - est chargé.
  • 2 = bootload - chargé au démarrage de l’application.
  • 8 = demandLoad - chargement sur demande par l’utilisateur.
  • 16 = ConnectFirstTime - chargé une seule fois (au prochain démarrage).
La valeur généralement indiquée est 0 x 03 (Connected | Bootload).


Les compléments qui implémentent IDTExtensibility2 devraient également spécifier une valeur DWORD appelée CommandLineSafe pour indiquer si les compléments sont sécurisés pour les opérations qui ne prennent pas en charge une interface utilisateur. Une valeur de 0 x 00 indique False et une valeur de 0 x 01 indique True.


Comment créer un complément COM à l’aide de Visual C# .NET

Comme déjà mentionné, un complément COM Office est un serveur COM in-process qui est activé par une application Office via la couche d’exécution COM.. Par conséquent, pour développer un complément COM dans .NET, il requiert que le composant du complément être implémenté dans .NET et puis exposé aux clients COM (c'est-à-dire aux applications Office) via la couche COM interop.

Pour créer un complément COM dans Visual C# .NET, procédez comme suit :
  1. Dans Visual C# .NET, créez un projet de bibliothèque de classes.
  2. Ajoutez une référence à la bibliothèque de types qui implémente IDTExtensibility2. L’assembly PIA pour cela est déjà disponible sous le nom d’extensibilité.
  3. Ajoutez une référence à la bibliothèque d’objets Microsoft Office. L’assembly PIA pour cela est déjà disponible sous le nom de Office.
  4. Créez une classe publique dans la bibliothèque de classes qui implémente IDTExtensibility2.
  5. Après la classe de bibliothèque est générée, inscrire la bibliothèque pour COM interop. Pour ce faire, générez un nom fort assembly pour cette bibliothèque de classes, puis inscrivez-le avec COM interop. Vous pouvez utiliser Regasm.exe pour inscrire un composant .NET pour COM interop.
  6. Créer des entrées du Registre afin que les applications Office reconnaissent et chargent le complément.
Vous pouvez choisir d’effectuer toutes ces étapes, ou vous pouvez créer un projet .NET de type Shared Addin. Cette opération démarre l’Assistant extensibilité qui vous aide à créer un complément COM dans .NET.

L’Assistant Extensibilité crée un projet de bibliothèque de classes Visual C# .NET et une classe de connexion qui implémente l’interface IDTExtensibility2 . Le code squelette qui implémente les membres vides d'
IDTExtensibility est également généré. Ce projet comporte des références aux assemblys d’extensibilité et Office. Les paramètres de génération du projet ont inscrire pour COM Interop sélectionnée. Le fichier d’assembly clé (.snk) est généré et référencé dans l’attribut AssemblyKeyfile dans Assemblyinfo.vb.

Avec le projet de bibliothèque de classes, l’Assistant génère un projet d’installation que vous pouvez utiliser pour déployer le complément COM sur d’autres ordinateurs. Vous pouvez supprimer ce projet si vous le souhaitez.

Exemple pas à pas

  1. Dans le menu fichier dans Microsoft Visual Studio .NET, cliquez sur Nouveau, puis cliquez sur projet.
  2. Dans la boîte de dialogue Nouveau projet , développez Autres projets , sous Types de projets, sélectionnez Projets d’extensibilitéet puis sélectionnez le modèle de complément partagé .
  3. Tapez MyCOMAddin comme nom de la macro complémentaire, puis sur OK.
  4. Lorsque l’Assistant Extensibilité s’affiche, procédez comme suit :
    1. Sur la page 1, sélectionnez créer un complément à l’aide de Visual C#, puis cliquez sur suivant.
    2. Sur la page 2, sélectionnez les applications hôtes suivantes, puis cliquez sur suivant:
      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access
    3. Sur la page 3, fournir un nom et une description pour le complément, puis cliquez sur suivant.

      Remarque Le nom et la description du complément s’affichent dans la boîte de dialogue macro complémentaire COM dans l’application Office.

    4. Sur la page 4, sélectionnez toutes les options disponibles, puis cliquez sur suivant.
    5. Cliquez sur Terminer.
  5. Dans le menu projet, cliquez sur Ajouter une référence. Cliquez sur System.Windows.Forms.DLL dans la liste composants, cliquez sur Sélectionner, puis cliquez sur OK.
  6. Ajoutez le code suivant à la liste des espaces de noms dans la classe Connect :
    using System.Reflection;
  7. Ajoutez le membre suivant à la classe Connect :
    private CommandBarButton MyButton; 
  8. Implémentez le code pour les membres de IDTExtensibility2 dans la classe Connect , comme suit :
    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. Créez et testez le complément COM. Pour ce faire, procédez comme suit :
    1. Dans le menu Générer , cliquez sur Générer la Solution. Notez que créer le complément COM inscrit la classe .NET avec COM interop.
    2. Démarrez une des applications Office que vous avez sélectionné comme applications hôtes pour votre complément (par exemple, Microsoft Word ou Microsoft Excel).
    3. Après le démarrage du complément, l’événement OnStartupComplete du complément se déclenche et vous recevez un message. Faire disparaître la boîte de message. Notez que le complément ajouté un nouveau bouton personnalisé avec la légende « Mon bouton personnalisé » dans la barre d’outils standard.
    4. Cliquez sur Mon bouton personnalisé. L’événement Click pour le bouton est géré par le complément et que vous recevez une boîte de message. Faire disparaître la boîte de message.
    5. Fermez l’application Office.
    6. Lorsque vous quittez l’application, l’événement OnBeginShutDown se déclenche et vous recevez un message. Faites disparaître le message pour terminer la démonstration.

Références

Pour plus d’informations sur l’écriture de compléments COM, cliquez sur le numéro ci-dessous pour afficher l’article correspondant dans la Base de connaissances Microsoft :

190253 Infos : les concepteurs VB6 ne fonctionnent pas dans VB5

Propriétés

ID d'article : 302901 - Dernière mise à jour : 26 janv. 2017 - Révision : 2

Commentaires