Inscription d'un complément

Article
03/04/2013

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 :

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

Chemin local (MyAddin1.dll)

Utilisé pour le déploiement du projet de complément.Incluse dans le projet pour des modifications facilitées. Chemin d'accès local pour un déploiement de style XCopy.

Dossier des compléments

\Documents\Visual Studio 2010\Addins\

Emplacement des documents partagés\Addins\

Dossier de débogage du projet

(Par exemple, \ Documents\Visual Studio 2010

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 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 :

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 qui spécifient l'icône qui s'affichera 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 chemin d'accès relatif de l'icône qui sera affichée 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 telle que 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.

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.

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é 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.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.

Valeur	Description
0	Le complément n'est pas chargé tant que l'utilisateur ne le démarre pas par le biais du 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 lors du 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 à 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>

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.

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

Partager via