Inscription d'un complément

Après avoir créé un complément, vous devez l'inscrire auprès de Visual Studio avant de l'activer dans le Gestionnaire de compléments.Pour cela, vous devez utiliser un fichier XML avec l'extension de fichier .addin.

Ce fichier .addin contient 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.S'il en trouve, il lit le fichier XML et transmet au Gestionnaire de compléments les informations dont il a besoin pour démarrer le complément lorsqu'un utilisateur clique dessus.

Le fichier .addin est créé automatiquement lors de la création d'un complément à l'aide de l'Assistant Complément.Vous pouvez également créer manuellement un fichier .addin à l'aide des informations de cette rubrique.

Emplacements des fichiers

Deux copies du fichier .addin sont créées automatiquement par l'Assistant Complément, comme suit :

Pour installer le complément sur un autre ordinateur, le fichier .addin doit se trouver dans un emplacement où Visual Studio recherche des compléments.Ces derniers sont répertoriés dans la boîte de dialogue d' Options , dans le nœud d' Environnement , dans la page de Sécurité des compléments .Pour plus d'informations, consultez Sécurité des compléments.

Le fichier .DLL qui contient le complément peut être installé n'importe où sur l'ordinateur client.Toutefois, nous vous recommandons de le ranger avec le fichier .addin.

[!REMARQUE]

L'élément <Assembly> du fichier .addin doit pointer vers le fichier .DLL qui contient les binaires pour le complément.

Le fichier .Addin

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

Les éléments suivants sont des éléments enfants de la section <Addin> :

Les détails de chaque configuration sont les suivants :Pour plus d'informations sur l'emplacement hiérarchique de beaucoup des éléments décrits, consultez la rubrique « Exemple de fichier XML .Addin » plus bas dans cet article.

Application hôte

L'élément <Name> dans la section Host Application contient le nom de l'application.Il s'agit du nom affiché sur la barre de titre de l'application ou retourné par DTE.Name.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 mise entre crochets à l'aide des balises <Name> dans l'élément <HostApplication>.En plus de contenir un élément <Name>, chaque élément <HostApplication> doit également inclure le numéro de version de l'application mis entre crochets à l'aide des balises <Version>.Par exemple :

   <HostApplication>
      <!-- First Host App name (required). -->
      <Name>Microsoft Visual Studio</Name>
      <Version>10.0</Version>
   </HostApplication>
   <HostApplication>
      <!-- An additional supported program/version. -->
      <Name>Microsoft Visual Studio Macros</Name>
      <Version>10.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.

Nom convivial

L'élément <FriendlyName>, situé sous l'élément <Addin>, spécifie la chaîne qui sera affichée dans la colonne Compléments disponibles dans le Gestionnaire de compléments.Par exemple :

   <FriendlyName>My New Super Addin</FriendlyName>

Description

L'élément <Description>, situé sous l'élément <Addin>, spécifie la chaîne qui sera affichée dans la boîte de dialogue Description dans le Gestionnaire de compléments.Par exemple :

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

Détails de la zone À propos de

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, cet élément est ajouté au fichier .addin.Cet élément spécifie le texte qui sera affiché dans la boîte de dialogue À propos de de Visual Studio.Par exemple :

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

Données sur l'icône À propos de

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, cet élément est ajouté au fichier .addin.Cet élément contient des données binaires qui spécifient l'icône qui sera affichée dans la boîte de dialogue À propos de de Visual Studio.Par exemple :

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

Assembly

L'élément <Assembly>, situé sous l'élément <Addin>, spécifie l'emplacement des fichiers binaires de compléments.Cet élément peut avoir pour valeur un chemin d'accès relatif, un chemin d'accès absolu (« fichier »), un nom d'assembly inscrit (« assembly ») ou une URL (« url »).

• L'exemple suivant montre un emplacement de chemin d'accès absolu.Dans ce cas, le paramètre src a la valeur file pour indiquer l'emplacement de la DLL du complément.

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

• L'exemple suivant montre un emplacement inscrit.Dans ce cas, le paramètre src a la valeur assembly pour indiquer une DLL de complément inscrite.

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

• L'exemple suivant montre un emplacement d'URL.Dans ce cas, le paramètre src a la valeur url pour indiquer l'emplacement Web de la DLL du complément.

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

Nom complet de la classe

L'élément <FullClassName> spécifie le nom complet de la classe utilisée pour se connecter au complément.Il comprend l'espace de noms qui contient la classe.Par exemple :

    <FullClassName>MyAddin4.Connect</FullClassName>

Comportement au chargement

L'élément <LoadBehavior> définit si un complément doit être chargé automatiquement au démarrage de l'IDE ou manuellement.L'élément <LoadBehavior> est situé sous l'élément <Addin>.Par exemple :

    <LoadBehavior>1</LoadBehavior>

Bien que l'utilisation de <LoadBehavior> soit facultative, nous vous recommandons de l'utiliser pour définir explicitement quand doivent être chargés les compléments.

Préchargement de commande

L'élément <CommandPreload> spécifie si le complément doit être préchargé.Le préchargement permet de charger le complément la première fois que Visual Studio est lancé, après l'installation du fichier .addin.Par exemple :

    <CommandPreload>1</CommandPreload>

Cet élément vous permet de spécifier qu'un complément doit être chargé après le démarrage de Visual Studio.Cela permet à votre complément 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 déchargé jusqu'à ce qu'un utilisateur exécute l'une des commandes créées par le complément.Par la suite, le complément est chargé si nécessaire.

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

Compatible avec la ligne de commande

L'élément facultatif <CommandLineSafe> indique si le complément a été conçu pour éviter d'afficher une interface utilisateur lorsqu'il est lancé depuis une invite de commandes, par exemple, lorsque vous exécutez des générations à partir de la ligne de commande ou d'autres opérations du même type.(pour cela, sélectionnez 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 ; par exemple la ligne de commande seule ou l'IDE seul.Par exemple :

    <CommandLineSafe>0</CommandLineSafe>

Page d'options Outils

L'élément facultatif <ToolsOptionsPage> spécifie une page Options pour que les utilisateurs puissent configurer le complément.Les nœuds enfants spécifient la catégorie et la sous-catégorie dans lesquelles s'affiche la page Options ainsi que son nom d'assembly et son nom de classe complet.L'exemple suivant montre la hiérarchie de cet élément :

  <ToolsOptionsPage>
    <Category Name="Text Editor">
      <SubCategory Name="General">
        <Assembly>"MyFilePath\MyAddInOptionPage.dll"</Assembly>
        <FullClassName>"MyNamespace.MyAddInOptionPage"</FullClassName>
      </SubCategory>
    </Category>
  </ToolsOptionsPage>

Exemple de fichier XML .Addin

L'exemple suivant montre un fichier XML .addin complet.Il montre la hiérarchie et les emplacements des éléments décrits dans cette rubrique.

<?xml version="1.0" encoding="UTF-16" standalone="no"?>
<Extensibility 
  xmlns="https://schemas.microsoft.com/AutomationExtensibility">
    <HostApplication>
        <Name>Microsoft Visual Studio Macros</Name>
        <Version>10.0</Version>
    </HostApplication> 
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>10.0</Version>
    </HostApplication>
    <Addin>
        <FriendlyName>My great new add-in.</FriendlyName>
        <Description>This add-in does it all.</Description>
        <AboutBoxDetails>Copyright 2010.</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

Référence

Commandes et commutateurs Visual Studio

Concepts

Graphique Modèle d'objet Automation

Autres ressources

Création de compléments et d'Assistants