Inscription d'un complément

Mise à jour : novembre 2007

Après création d'un complément, vous devez l'enregistrer auprès de Visual Studio pour qu'il devienne disponible pour activation dans le Gestionnaire de compléments. Dans les versions antérieures de Visual Studio, cette opération s'effectuait à l'aide de clés de Registre. Elle s'effectue désormais à l'aide d'un fichier XML.

Remarque :
Le fichier .Addin est créé automatiquement lorsque vous créez un complément en utilisant l'Assistant Complément. Les informations suivantes s'appliquent uniquement si vous souhaitez créer ou modifier manuellement le fichier d'enregistrement du complément.

Dans Visual Studio .NET 2002 et Visual Studio .NET 2003, vous deviez enregistrer les assemblys des compléments auprès de Windows en tant que composants COM en utilisant l'Outil Assembly Registration Tool (regasm.exe). De plus, vous deviez enregistrer le complément auprès de Visual Studio en utilisant les clés du Registre Windows pour que le complément figure dans le Gestionnaire de compléments.

Depuis Visual Studio 2005, il ne s'agit plus des mêmes étapes. Il n'est plus nécessaire d'enregistrer les assemblys .NET auprès de Windows en utilisant regasm. Au lieu de cela, il vous suffit de placer le fichier .DLL de l'assembly dans un répertoire spécifique (décrit ultérieurement dans cette rubrique) accompagné d'un fichier XML doté d'une extension de fichier .Addin. Ce fichier XML décrit les informations nécessaires à Visual Studio pour afficher le complément dans le Gestionnaire de compléments. Lors de son démarrage, Visual Studio recherche les fichiers .Addin disponibles à l'emplacement des fichiers .Addin (voir ci-dessous). S'il en trouve, il lit le fichier XML et fournit au Gestionnaire de compléments les informations nécessaires au démarrage du complément lorsque l'utilisateur clique dessus.

Cette méthode d'enregistrement simplifié permet des installations de type XCopy pour les compléments en code managé. Si vous placez tous les fichiers au bon endroit, votre complément fonctionnera parfaitement. Par ailleurs, son utilisation du XML commenté pour définir les paramètres d'inscription des compléments permet aux informations d'être plus facilement comprises et modifiées que les clés de Registre.

Le fichier .Addin

Un nouveau fichier XML ayant .Addin pour extension remplace les anciens paramètres du Registre relatifs au complément. Deux copies du fichier .Addin sont créées automatiquement dès la fin de l'exécution de l'Assistant Complément :

Le fichier XML .Addin est composé des sections balisées suivantes :

Les détails de chaque configuration sont les suivants :

Application hôte

La balise <Name> de l'application hôte contient le nom de l'application. Il s'agit du nom affiché dans la barre de titre de l'application ou retournée par DTE.Name. Ainsi, par exemple, la balise contiendrait « Microsoft Visual Studio » pour Visual Studio et « Microsoft Visual Studio Macros » pour l'éditeur de macros.

Un fichier .Addin peut présenter plusieurs valeurs d'application hôte. Chaque valeur doit être placée entre crochets par la balise <Name> au sein de la balise <HostApplication>. En plus de la balise <Name>, chaque balise <HostApplication> doit également inclure le numéro de version de cette application mise entre crochets par les balises <Version>. Par exemple :

   <HostApplication>
      <!-- First Host App name (required). -->
      <Name>Microsoft Visual Studio</Name>
      <Version>9.0</Version>
   </HostApplication>
   <HostApplication>
      <!-- An additional supported program/version. -->
      <Name>Microsoft Visual Studio Macros</Name>
      <Version>9.0</Version>
   </HostApplication>

Vous pouvez également spécifier un astérisque (*) pour représenter la valeur de <Version> pour toutes les versions de Visual Studio. Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de ces balises.

Nom convivial

La balise <FriendlyName>, localisée sous la balise <Addin>, spécifie la chaîne qui s'affiche dans la colonne Compléments disponibles du complément dans le Gestionnaire de compléments. Voici un exemple de son utilisation :

   <FriendlyName>My New Super Addin</FriendlyName>

Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de cette balise.

Description

La balise <Description>, localisée sous la balise <Addin>, spécifie la chaîne qui s'affiche dans la zone Description du complément dans le Gestionnaire de compléments. Voici un exemple de son utilisation :

   <Description>This add-in will change your life!</Description>

Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de cette balise.

À propos de la zone Détails

Si vous sélectionnez l'option pour générer des paramètres pour la boîte de dialogue À propos de lorsque vous créez votre complément, cette balise est ajoutée au fichier .Addin. Cette balise spécifie le texte qui s'affichera pour votre complément dans la boîte de dialogue Visual StudioÀ propos de. Voici un exemple de son utilisation :

   <AboutBoxDetails>For add-in support, call 1-800-xxx-
     xxxx.</AboutBoxDetails>

Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de cette balise.

À propos de l'icône Data

Si vous sélectionnez l'option pour générer des paramètres pour la boîte de dialogue À propos de lorsque vous créez votre complément, cette balise est ajoutée au fichier .Addin. Cette balise contient des données binaires qui spécifient l'icône qui s'affiche pour votre complément dans la boîte de dialogue Visual StudioÀ propos de. Voici un exemple de son utilisation :

<AboutIconData>0000010006 . . . FFFF0000</AboutIconData>

Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de cette balise.

Assembly

La balise <Assembly>, située sous la balise <Addin>, spécifie l'emplacement des fichiers binaires du complément. Cette balise peut avoir pour valeur un chemin local, un chemin d'accès réseau ("fichier"), un nom d'assembly enregistré ("assembly") ou une URL valide ("url"). Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de cette balise.

• Voici un exemple d'emplacement d'un complément de type URL. Dans ce cas, le paramètre src a la valeur url pour indiquer l'emplacement fondé sur le Web de la DLL du complément :

  <Assembly src="url">http://somewebsite.com/MyAddin4.dll</Assembly>
  

• Voici un exemple d'emplacement en chemin local. Dans ce cas, le paramètre src a la valeur file pour indiquer l'emplacement local de la DLL du complément :

  <Assembly src="file">C:\Documents and Settings\jdoe\Application Data\Microsoft\Visual Studio\8.0\AddIns\MyAddin4.dll</Assembly>
  

• Voici un exemple de chemin local. Dans ce cas, le paramètre src a la valeur assembly pour indiquer l'emplacement fondé sur le Web de la DLL du complément :

  <Assembly src="assembly">BookshelfDefineAddin</Assembly>
  

Nom de classe complet

La balise <FullClassName> spécifie le nom complet de la classe utilisée pour se connecter au complément, comprenant l'espace de noms qui contient la classe. Voici un exemple d'utilisation :

    <FullClassName>MyAddin4.Connect</FullClassName>

Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de cette balise.

Comportement

La balise <LoadBehavior> détermine si un complément est chargé automatiquement au démarrage de l'IDE ou s'il est démarré manuellement. La balise <LoadBehavior> est subordonnée à la balise <Addin>. Voici un exemple d'utilisation :

    <LoadBehavior>1</LoadBehavior>

Si l'utilisation de la balise <LoadBehavior> reste facultative, il est recommandé de l'utiliser pour définir explicitement le moment où un complément se charge.

Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de cette balise.

Préchargement

La balise <CommandPreload> spécifie si le complément doit ou non être préchargé. Le préchargement charge le complément au premier démarrage de Visual Studio après placement du fichier .Addin sur le disque. Voici un exemple d'utilisation :

    <CommandPreload>1</CommandPreload>

Cette balise vous permet de spécifier qu'un complément doit être chargé après le démarrage de Visual Studio. Il donne à votre complément l'occasion de créer des éléments d'interface utilisateur nécessaires, tels que des boutons de barre de commandes, ou d'effectuer d'autres tâches d'initialisation, à l'occasion d'une première exécution uniquement, telles que la création de paramètres de complément par défaut. Le complément est alors immédiatement déchargé jusqu'à ce qu'un utilisateur exécute une des commandes créées par le complément, qui charge alors le complément selon les besoins dans toutes les instances successives de l'IDE.

Vous pouvez examiner la méthode OnConnection que vous implémentez pour voir si le type de connexion, spécifié avec le deuxième argument appliqué à OnConnection, est ext_cm_UISetup. Si c'est le cas, vous pouvez exécuter les placements de commande que vous souhaitez en utilisant les méthodes AddNamedCommand ou AddControl.

Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de cette balise.

Compatible avec la ligne de commande

La balise <CommandLineSafe> facultative indique si le complément a été conçu pour éviter d'afficher une interface utilisateur lorsqu'il est démarré par la ligne de commande devenv ; par exemple, lors de l'exécution de générations par le biais d'une ligne de commande ou lors d'opérations similaires. (Pour ce faire, sélectionnez l'option Il ne fournira jamais d'interface utilisateur modale dans l'Assistant Complément.) De plus, l'option spécifie les modes de Visual Studio avec lesquels le complément est compatible : la ligne de commande seule ou l'IDE seul. Voici un exemple d'utilisation :

    <CommandLineSafe>0</CommandLineSafe>

Consultez la section intitulée « Exemple de fichier XML .Addin » plus loin dans cette rubrique pour connaître l'emplacement hiérarchique de cette balise.

Exemple de fichier XML .Addin

Ci-dessous un exemple d'un fichier XML .Addin complet. Il affiche la hiérarchie et les emplacements des balises susmentionnées.

<?xml version="1.0" encoding="UTF-16" standalone="no"?>
<Extensibility 
  xmlns="https://schemas.microsoft.com/AutomationExtensibility">
    <HostApplication>
        <Name>Microsoft Visual Studio Macros</Name>
        <Version>9.0</Version>
    </HostApplication> 
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>9.0</Version>
    </HostApplication>
    <Addin>
        <FriendlyName>My great new add-in.</FriendlyName>
        <Description>This add-in does it all.</Description>
        <AboutBoxDetails>Copyright 2008.</AboutBoxDetails>
        <AboutIconData>0000 . . . FFFF0000</AboutIconData>
        <Assembly>MyNewAddin.dll</Assembly>
        <FullClassName>MyNewAddin.Connect</FullClassName>
        <LoadBehavior>1</LoadBehavior>
        <CommandPreload>1</CommandPreload>
        <CommandLineSafe>0</CommandLineSafe>
    </Addin>
</Extensibility>

Voir aussi

Tâches

Comment : contrôler des compléments avec le Gestionnaire de compléments

Comment : créer un complément

Procédure pas à pas : création d'un Assistant

Concepts

Graphique Modèle d'objet Automation

Référence

Commandes et commutateurs Visual Studio

Autres ressources

Création de compléments et d'Assistants