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.
.gif "Remarque") 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 :
Emplacement du fichier .Addin |
Emplacement du fichier .DLL |
Description |
|---|---|---|
Dossier du complément (par exemple, \Documents and Settings\All Users\Documents partagés\Visual Studio 2008\Addins) - ou - \Documents and Settings\<nom utilisateur>\Mes documents\Visual Studio 2008\Addins) |
Dossier de débogage du projet (par exemple, \Mes Documents\Visual Studio Projects\MyAddin1\MyAddin1\bin) |
Utilisé pour exécuter le complément dans l'environnement de débogage. Doit toujours pointer sur le chemin de sortie de la configuration de génération actuelle. |
Dossier de projet racine (for example, \Mes Documents\Visual Studio\Projects\MyAddin1) |
Chemin local (MyAddin1.dll) |
Utilisé pour le déploiement du projet de complément. Il est intégré au projet pour faciliter la modification et s'installe avec le chemin local pour un déploiement de style XCopy. |
Le fichier XML .Addin est composé des sections balisées suivantes :
Paramètre |
Description |
|---|---|
Application hôte |
(Obligatoire.) Spécifie les noms et numéros de version des applications qui peuvent charger le complément. |
Assembly |
(Obligatoire.) Spécifie l'emplacement des fichiers binaires du complément. Ce champ peut avoir pour valeur un chemin local, un chemin d'accès réseau ou une URL valide. |
Nom complet de la classe |
(Obligatoire.) Spécifie le nom de la classe utilisée pour se connecter au complément. |
Comportement |
(Facultatif) Définit si un complément est chargé au démarrage ou manuellement. |
Préchargement de la commande |
(Facultatif) Spécifie l'état de préchargement du complément, c'est-à-dire s'il doit ou non créer son interface utilisateur en utilisant une méthode, telle que Commands.AddNamedCommand. |
Compatible avec la ligne de commande |
(Facultatif) Spécifie les modes de Visual Studio avec lesquels le complément est compatible : la ligne de commande et/ou l'environnement de développement intégré (IDE). |
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.
Valeur |
Description |
|---|---|
0 |
Le complément n'est pas chargé au démarrage de l'IDE et doit être démarré manuellement. |
1 |
Le complément est chargé automatiquement au démarrage de l'IDE. |
4 |
Le complément est chargé lorsque devenv est lancé depuis la ligne de commande avec un commutateur build (devenv /build). |
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.
Valeur |
Description |
|---|---|
0 |
Le complément ne se charge pas tant que l'utilisateur ne le démarre par le biais du Gestionnaire de compléments ou tant qu'il n'est pas configuré pour se charger au démarrage. |
1 |
Le complément est automatiquement chargé au premier démarrage de Visual Studio après placement du fichier XML .Addin sur le disque. |
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>
Valeur |
Description |
|---|---|
0 |
Spécifie que le complément comporte une interface utilisateur et peut l'afficher. |
1 |
Spécifie que le complément comporte une interface utilisateur et n'affiche pas celle-ci. |
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
Procédure pas à pas : création d'un Assistant
Concepts
Graphique Modèle d'objet Automation
Référence
Commandes et commutateurs Visual Studio