Comment faire pour générer un complément COM Office à l'aide de Visual C# .NET

Traductions disponibles Traductions disponibles
Numéro d'article: 302901 - Voir les produits auxquels s'applique cet article
Ancien nº de publication de cet article : F302901
Agrandir tout | Réduire tout

Sommaire

Résumé

Microsoft Office XP et Microsoft Office 2003 prennent en charge une nouvelle architecture de conception uniforme pour générer des compléments d'application en vue d'améliorer et de contrôler des applications Office. Il s'agit des compléments COM. Cet article décrit étape par étape les compléments COM Office et explique comment générer 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 une bibliothèque de liens dynamiques (DLL) ActiveX qui implémente l'interface IDTExensibility2 telle qu'elle est décrite dans la bibliothèque de types de 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 est déclenché chaque fois 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 l'Automation. Si OnConnection signale sa réussite, le complément est dit chargé. Si un message d'erreur est renvoyé, l'application hôte renvoie immédiatement sa référence au complément et l'objet est détruit.

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é. Les compléments peuvent être connectés selon les façons suivantes :
    • ext_cm_AfterStartup - Le complément est démarré par l'utilisateur final à partir de la boîte de dialogue des Compléments COM.
    • ext_cm_CommandLine - Le complément est connecté à partir de la ligne de commande. Notez que ceci 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 au moyen de l'Automation. Notez que ceci 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 de l'application hôte.
  • Custom - 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 se décharge de la mémoire. Le complément doit effectuer tout le nettoyage des ressources dans cet événement et restaurer tout changement apporté à l'application hôte.

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é selon les façons suivantes :
    • ext_dm_HostShutdown - Le complément est déconnecté à 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.
  • Custom - 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, dès qu'un complément COM est installé ou supprimé de l'application hôte, cet événement se déclenche.

OnStartupComplete et OnBeginShutdown

Les méthodes OnStartupComplete et OnBeginShutdown sont appelées lorsque l'application hôte quitte ou prend un état dans lequel l'interaction de l'utilisateur doit être évitée car l'application est en train de se charger ou de se décharger de la mémoire. OnStartupComplete est appelée 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.

Comme l'interface utilisateur de l'application hôte est totalement active lorsque ces événements se déclenchent, ils représentent la seule façon d'exécuter certaines actions qui sinon ne seraient pas disponibles à partir de OnConnection et OnDisconnection.

Inscription du complément COM dans le Registre

Outre 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 se servant de son ProgID comme nom de 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 donner un nom d'affichage convivial et une description complète. En outre, le complément doit spécifier son comportement de chargement 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 il est composé 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 - Chargé uniquement lorsque cela est demandé par l'utilisateur.
  • 16 = ConnectFirstTime - Chargé une seule fois (au prochain démarrage).
La valeur généralement spécifiée est 0x03 (Connected | Bootload).

Les compléments qui implémentent IDTExtensibility2 devraient également spécifier une valeur DWORD nommée
CommandLineSafe
pour indiquer s'ils sont sûrs pour des opérations qui ne prennent pas en charge une interface utilisateur. Une valeur égale à 0x00 indique False et une valeur égale à 0x01 indique True.

Comment faire pour générer un complément COM à l'aide de Visual C# .NET

Comme nous l'avons déjà mentionné, un complément COM Office est un serveur COM in-process 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 faut que le composant du complément soit implémenté dans .NET, 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 (Primary Interop Assembly) correspondant est déjà disponible sous le nom Extensibility.
  3. Ajoutez une référence à la Bibliothèque d'objets Microsoft Office. L'assembly PIA (Primary Interop Assembly) correspondant 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. Après la création de la bibliothèque de classes, inscrivez celle-ci dans le Registre pour COM Interop. Pour cela, générez un assembly avec un nom fort pour cette bibliothèque de classes, puis inscrivez-le dans le Registre avec COM Interop. Vous pouvez utiliser Regasm.exe pour inscrire dans le Registre un composant .NET pour COM Interop.
  6. Créez des entrées de Registre pour que les applications Office reconnaissent et chargent le complément.
Vous pouvez choisir d'achever toutes ces étapes ou de créer un projet .NET de type Shared Addin. Dans ce cas, l'Assistant Extensibilité démarre pour vous aider à 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 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 est doté de références aux assemblys d'extensibilité et Office. Inscrire pour COM Interop est sélectionné dans les paramètres de création du projet. Le fichier de clé d'assembly (.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 étape par étape

  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 sur Autres projets sous Types de projets, sélectionnez Projets d'extensibilité, puis sélectionnez le modèle Complément partagé.
  3. Tapez MyCOMAddin comme nom de complément, puis cliquez 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, donnez 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 Complément COM de 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 des composants, cliquez sur Sélectionner, puis sur OK.
  6. Ajoutez ce qui suit à la liste d'espaces de nom de 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. 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. Le fait de générer un complément COM inscrit dans le Registre la classe .NET avec COM Interop.
    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. Après le démarrage du complément, l'événement OnStartupComplete du complément se déclenche et affiche un message. Faites disparaître le message. Notez que le complément a 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 du bouton est géré par le complément et un message s'affiche. Faites disparaître le message.
    5. Quittez 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 des compléments COM, cliquez sur le numéro ci-dessous pour afficher l'article correspondant dans la Base de connaissances Microsoft.
190253 INFO : Les concepteurs VB6 ne fonctionnent pas dans VB5

Propriétés

Numéro d'article: 302901 - Dernière mise à jour: mardi 22 mai 2007 - Version: 8.1
Les informations contenues dans cet article s'appliquent au(x) produit(s) suivant(s):
  • Microsoft Visual C# .NET 2003 Initiation
  • Microsoft Visual C# .NET 2002 Initiation
  • Microsoft Office Excel 2003
  • Microsoft Excel 2002
  • Microsoft Office Outlook 2003
  • Microsoft Outlook 2002 Standard
  • Microsoft Office PowerPoint 2003
  • Microsoft PowerPoint 2002 Standard
  • Microsoft Office Word 2003
  • Microsoft Word 2002 Standard Edition
Mots-clés : 
kbautomation kbhowtomaster KB302901
L'INFORMATION CONTENUE DANS CE DOCUMENT EST FOURNIE PAR MICROSOFT SANS GARANTIE D'AUCUNE SORTE, EXPLICITE OU IMPLICITE. L'UTILISATEUR ASSUME LE RISQUE DE L'UTILISATION DU CONTENU DE CE DOCUMENT. CE DOCUMENT NE PEUT ETRE REVENDU OU CEDE EN ECHANGE D'UN QUELCONQUE PROFIT.

Envoyer des commentaires

 

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