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

Résumé

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

Interface IDTExensibility2

Un complément COM est un serveur COM in-process, ou bibliothèque de liens dynamiques ActiveX (DLL), qui implémente l’interface IDTExensibility2 comme décrit 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 chaque fois que le complément COM est connecté. Le complément peut être connecté au démarrage, par l’utilisateur final ou via Automation. Si l’événement OnConnection est retourné avec succès, le complément est dit chargé. Si un message d’erreur est retourné, 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 : référence à l’objet d’application hôte.

  • ConnectMode : constante qui spécifie comment le complément est connecté. Le complément peut être connecté de la manière suivante :

    • 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 : référence à l’objet COMAddIn qui fait référence à ce complément dans la collection COMAddIns pour l’application hôte.

  • Personnalisé : tableau de valeurs de type Variant pouvant contenir des données définies par l’utilisateur.

Ondisconnection

L’événement OnDisconnection se déclenche lorsque le complément COM est déconnecté et juste avant son déchargement de la mémoire. Le complément doit effectuer tout nettoyage des ressources dans cet événement et restaurer toutes les modifications apportées à l’application hôte.

L’événement OnDisconnection prend les deux paramètres suivants :

  • RemoveMode : constante qui spécifie comment le complément a été déconnecté. Le complément peut être déconnecté des manières suivantes :

    • ext_dm_HostShutdown : le complément est déconnecté lorsque l’application hôte se ferme.
    • ext_dm_UserClosed : le complément est déconnecté par l’utilisateur final ou un contrôleur Automation.
  • Personnalisé : tableau de valeurs de type Variant pouvant contenir des données définies par l’utilisateur.

OnAddInsUpdate

L’événement OnAddInsUpdate se déclenche lorsque l’ensemble des 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 méthode OnStartupComplete et la méthode OnBeginShutdown sont appelées lorsque l’application hôte a quitté ou entre dans un état dans lequel l’interaction utilisateur doit être évitée, car l’application est occupée à se charger ou à 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 pendant l’arrêt.

Étant donné que l’interface utilisateur de l’application hôte est entièrement active lorsque ces événements se déclenchent, elles peuvent être la seule façon d’effectuer certaines actions qui autrement seraient indisponibles à partir de l’événement OnConnection et de l’événement OnDisconnection.

Inscription du complément COM

En plus de l’inscription COM normale, un complément COM doit s’inscrire auprès de chaque application Office dans laquelle il s’exécute. Pour s’inscrire auprès d’une application particulière, le complément doit créer une sous-clé, en utilisant son ProgID comme nom de la clé, à l’emplacement suivant :

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

Le complément peut fournir des valeurs à cet emplacement clé pour un nom d’affichage convivial et une description complète. En outre, le complément doit spécifier son comportement de charge souhaité à l’aide d’une valeur DWORD nommée LoadBehavior. Cette valeur détermine la façon dont le complément est chargé par l’application hôte et se compose d’une combinaison des valeurs suivantes :

  • 0 = Déconnexion : n’est pas chargé.
  • 1 = Connecté - Est chargé.
  • 2 = Chargement de démarrage - Charger au démarrage de l’application.
  • 8 = Chargement de la demande - Charger uniquement lorsque l’utilisateur le demande.
  • 16 = ConnectFirstTime - Charger une seule fois (au démarrage suivant).

La valeur standard spécifiée est 0x03 (Connected | Chargement de démarrage).

Les compléments qui implémentent IDTExtensibility2 doivent é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 0x00 indique False et une valeur de 0x01 indique True.

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

Comme mentionné précédemment, un complément COM Office est un serveur COM in-process qui est activé par une application Office via la couche runtime COM. Par conséquent, le développement d’un complément COM dans .NET nécessite que le composant de complément soit implémenté dans .NET, puis exposé aux clients COM (autrement dit, les applications Office) via la couche d’interopérabilité COM.

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 d’interopérabilité principal pour cela est déjà disponible sous le nom Extensibility.
  3. Ajoutez une référence à la bibliothèque d’objets Microsoft Office. L’assembly d’interopérabilité principal pour cela est déjà disponible sous le nom Office.
  4. Créez une classe publique dans la bibliothèque de classes qui implémente IDTExtensibility2.
  5. Une fois la bibliothèque de classes générée, inscrivez-la pour COM Interop. Pour ce faire, générez un assembly nommé fort pour cette bibliothèque de classes, puis inscrivez-le auprès de COM Interop. Vous pouvez utiliser Regasm.exe pour inscrire un composant .NET pour COM Interop.
  6. Créez des entrées de Registre afin que les applications Office puissent reconnaître et charger le complément.

Vous pouvez choisir d’effectuer toutes ces étapes, ou vous pouvez créer un projet .NET de type Shared Addin. Cela démarre l’Assistant Extensibilité, qui vous aide à créer un complément COM dans .NET.

L’Assistant Extensibility crée un projet de bibliothèque de classes Visual C# .NET avec une classe Connect 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 à l’extensibilité et aux assemblys Office. Les paramètres de build du projet ont été sélectionnés pour s’inscrire à COM Interop. Le fichier de clé d’assembly (.snk) est généré et référencé dans l’attribut AssemblyKeyfile dans Assemblyinfo.vb.

En plus du 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 de Microsoft Visual Studio .NET, cliquez sur Nouveau, puis sur Projet.

  2. Dans la boîte de dialogue Nouveau projet, développez Autres projets sous Types de projets, sélectionnez Projets d’extensibilité, puis sélectionnez le modèle de complément partagé.

  3. Tapez MyCOMAddin comme nom du complément, puis cliquez sur OK.

  4. Lorsque l’Assistant Extensibilité s’affiche, procédez comme suit :

    1. Dans la page 1, sélectionnez Créer un complément à l’aide de Visual C#, puis cliquez sur Suivant.

    2. Dans 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, fournissez un nom et une description pour le complément, puis cliquez sur Suivant.

      Note Le nom et la description du complément apparaissent dans la boîte de dialogue Complément COM dans l’application Office.

    4. À 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 System.Windows.Forms.DLL dans la liste des composants, cliquez sur Sélectionner, puis sur OK.

  6. Ajoutez ce qui suit à 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 d’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. Générez et testez le complément COM. Pour cela, procédez comme suit :

    1. Dans le menu Générer, cliquez sur Générer la solution. Notez que la création du complément COM inscrit la classe .NET avec l’interopérabilité COM.
    2. Démarrez l’une des applications Office que vous avez sélectionnées comme applications hôtes pour votre complément (par exemple, Microsoft Word ou Microsoft Excel).
    3. Une fois le complément démarré, l’événement OnStartupComplete du complément est déclenché et vous recevez un message. Ignorer la zone de message. Notez que le complément a ajouté un nouveau bouton personnalisé avec la légende « Mon bouton personnalisé » à 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 vous recevez une boîte de message. Ignorer la zone de message.
    5. Quittez l’application Office.
    6. Lorsque vous quittez l’application, l’événement OnBeginShutDown se déclenche et vous recevez un message. Ignorer la boîte de message pour mettre fin à la démonstration.