Inscription d'un complément

Article
06/10/2015

Les compléments Visual Studio sont déconseillés dans Visual Studio 2013. Effectuez la mise à niveau de vos compléments vers des extensions VSPackage. Pour plus d'informations sur les mises à niveau, consultez FAQ : conversion de compléments en extensions VSPackage.

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 .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. Si des fichiers sont trouvés, Visual Studio lit le fichier XML et transmet au Gestionnaire de compléments les informations dont il a besoin pour démarrer le complément quand 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 :

Emplacement du fichier .addin	Emplacement du fichier .Dll	Description
Dossier de projet racine \Documents\Visual Studio 2013\Projects\MyAddin1\MyAddin1\	Chemin local (MyAddin1.dll)	Utilisé pour le déploiement du projet de complément. Inclus dans le projet pour faciliter les modifications. Chemin d'accès local pour un déploiement de style XCopy.
Dossier des compléments \Documents\Visual Studio 2013\Addins\ ou Emplacement des documents partagés\Addins\	Dossier de débogage du projet (Par exemple, \ Documents\Visual Studio 2013 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 build actuelle.

Dossier de projet racine

\Documents\Visual Studio 2013\Projects\MyAddin1\MyAddin1\

Chemin local (MyAddin1.dll)

Utilisé pour le déploiement du projet de complément. Inclus dans le projet pour faciliter les modifications. Chemin d'accès local pour un déploiement de style XCopy.

Dossier des compléments

\Documents\Visual Studio 2013\Addins\

Emplacement des documents partagés\Addins\

Dossier de débogage du projet

(Par exemple, \ Documents\Visual Studio 2013

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 build actuelle.

Pour installer le complément sur un autre ordinateur, le fichier .addin doit se trouver à un emplacement où Visual Studio recherche des compléments. Les emplacements sont répertoriés dans la boîte de dialogue Options, dans le nœud Environnement, dans la page 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 placer avec le fichier .addin.

Notes

L'élément <Assembly> du fichier .addin doit pointer vers le fichier .dll contenant les binaires du complément.

Fichier .addin

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

Section	Description
Application hôte	(Obligatoire.) Spécifie les noms et numéros de version des applications qui peuvent charger le complément.
Complément	(Obligatoire) Contient les éléments qui décrivent le complément.
Page d'options Outils	(Facultatif) Spécifie une page dans la boîte de dialogue Options où le complément peut être configuré. Les nœuds enfants spécifient la catégorie et la sous-catégorie de la page Options, ainsi que son nom d'assembly et son nom de classe complet.

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

Élément	Description
Détails de la zone À propos de	(Facultatif) Spécifie le texte qui sera affiché pour votre complément dans la boîte de dialogue À propos de de Visual Studio.
Données sur l'icône À propos de	(Facultatif) Contient des données binaires spécifiant l'icône qui s'affiche pour votre complément dans la boîte de dialogue À propos de de Visual Studio.
Emplacement de l'icône À propos de	(Facultatif) Spécifie le chemin d'accès absolu ou relatif de l'icône qui s'affiche pour votre complément dans la boîte de dialogue À propos de de Visual Studio.
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.
Compatible avec la ligne de commande	(Facultatif) Spécifie les modes de Visual Studio avec lesquels le complément est compatible ; par exemple la ligne de commande et/ou l'environnement de développement intégré (IDE).
Préchargement de commande	(Facultatif) Spécifie l'état de préchargement du complément c'est-à-dire, si le complément doit créer son interface utilisateur à l'aide d'une méthode comme Commands.AddNamedCommand.
Nom complet de la classe	(Obligatoire.) Spécifie le nom de la classe utilisée pour se connecter au complément.
Comportement au chargement	(Facultatif) Définit si un complément est chargé au démarrage ou manuellement.

Voici les détails de chaque configuration. Pour plus d'informations sur l'emplacement hiérarchique de bon nombre des éléments décrits, consultez « Exemple de fichier XML .Addin » plus bas dans cette rubrique.

Application hôte

L'élément <Name> de 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.

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 placé entre crochets à l'aide des balises <Version>. Par exemple :

   <HostApplication>
      <!-- First Host App name (required). -->
      <Name>Microsoft Visual Studio</Name>
      <Version>12.0</Version>
   </HostApplication>
   <HostApplication>
      <!-- An additional supported program/version. -->
      <Name>Microsoft Visual Studio</Name>
      <Version>11.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 s'affiche dans la colonne Compléments disponibles du 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 s'affiche dans la zone Description du 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 relatifs à la boîte de dialogue À propos de quand vous créez votre complément, cet élément est ajouté au fichier .addin. L'élément spécifie le texte qui s'affiche pour votre complément 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 relatifs à la boîte de dialogue À propos de quand vous créez votre complément, cet élément est ajouté au fichier .addin. Cet élément contient les données binaires spécifiant l'icône qui s'affiche 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 du complément. 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 illustre un emplacement de chemin 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\12.0\AddIns\MyAddin4.dll</Assembly>
```
L'exemple suivant illustre 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 illustre 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 contenant 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 démarré manuellement. L'élément <LoadBehavior> se trouve sous l'élément <Addin>. Par exemple :

    <LoadBehavior>1</LoadBehavior>

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

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 automatiquement chargé au démarrage de l'IDE.
4	Le complément est chargé quand devenv est lancé via une invite de commandes à l'aide d'un commutateur de génération (devenv /build).

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. Votre complément peut ainsi créer des éléments d'interface utilisateur nécessaires, tels que des boutons de barre de commandes, ou effectuer d'autres tâches d'initialisation, à l'occasion d'une première exécution uniquement, comme 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.

Valeur	Description
0	Le complément n'est pas chargé tant que l'utilisateur ne le démarre pas via le Gestionnaire de compléments ou tant qu'il n'est pas configuré pour être chargé au démarrage.
1	Le complément est chargé automatiquement au premier démarrage de Visual Studio, après l'installation du fichier .addin.

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 sur 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 quand il est lancé depuis une invite de commandes, par exemple, quand vous exécutez des générations en 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>

Valeur	Description
0	Spécifie que le complément nest pas compatible avec la ligne de commande et peut afficher une interface utilisateur.
1	Spécifie que le complément est compatible avec la ligne de commande et ne peut pas afficher une interface utilisateur.

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 de 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</Name>
        <Version>12.0</Version>
    </HostApplication> 
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>11.0</Version>
    </HostApplication>
    <Addin>
        <FriendlyName>My great new add-in.</FriendlyName>
        <Description>This add-in does it all.</Description>
        <AboutBoxDetails>Copyright 2013.</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

Partager via