FAQ : conversion de compléments en extensions VSPackage

Article
06/10/2015

Les compléments sont désormais déconseillés. Pour créer une extension Visual Studio, vous devez créer un VSPackage. Si vous disposez déjà d'un complément, il peut éventuellement encore fonctionner. Toutefois, si vous comptez le distribuer, vous devez le convertir en un VSPackage. Vous trouverez ici des réponses à certaines questions fréquemment posées concernant la conversion de complément Visual Studio en une extension VSPackage.

Important

Dans de nombreux cas, vous pouvez simplement transférer le code de votre complément vers un projet VSPackage.Vous pouvez obtenir l'objet automation DTE en appelant GetService dans la méthode Initialize.

DTE2 dte = (DTE2)GetService(typeof(DTE));

Pour plus d'informations, consultez Comment puis-je exécuter le code de mon complément dans un VSPackage ? ci-dessous.

Quel logiciel utiliser pour développer des extensions VSPackage ?

Vous devez installer le Kit de développement logiciel (SDK) Microsoft Visual Studio 2013 en plus de l'édition Professional, Premium ou Ultimate de Visual Studio 2013. Vous pouvez le télécharger depuis la page Kit de développement logiciel (SDK) Microsoft Visual Studio 2013 du site web du Centre de téléchargement Microsoft. Nous vous recommandons d'installer le Kit de développement logiciel (SDK) avant d'installer Visual Studio 2013 Update 2.

Où se trouve la documentation VSPackage ?

Commencez par Étendre la présentation de Visual Studio. Vous trouverez d'autres articles sur le développement VSPackage sous cet article.

Puis-je convertir mon projet de complément en un projet VSPackage ?

Vous ne pouvez pas convertir un projet de complément en un projet VSPackage car les deux utilisent des mécanismes différents. Le modèle de projet VSPackage comporte de nombreuses lignes de code qui permettent de le mettre en place et de l'exécuter en tant qu'extension VSPackage relativement facilement.

Comment démarrer le développement d'extensions VSPackage ?

Le modèle de projet des extensions VSPackage comporte les éléments dont vous avez besoin. Voici comment vous constituez un VSPackage doté d'une commande de menu :

Créez un projet de package Visual Studio, puis nommez-le TestVSPackage. (Fichier, Nouveau, Projet, ou tapez le projet dans la fenêtre Lancement rapide). Dans la boîte de dialogue Nouveau projet, développez Autres types de projets, Extensibilité, puis sélectionnez Package Visual Studio. Nommez le projet TestVSPackage et spécifiez son emplacement.
L'Assistant Package Visual Studio apparaît. Dans la page Sélectionner un langage de programmation, sélectionnez C# comme langage. Conservez l'option Générer une nouvelle clé sélectionnée. Dans la page Options VSPackage, sélectionnez Commande de menu. Choisissez le bouton Terminer.
Appuyez sur la touche F5 pour exécuter le projet en mode débogage.

Une seconde instance de Visual Studio apparaît. Celle-ci est appelée instance expérimentale. Ses paramètres peuvent différer de ceux de l'instance de Visual Studio qui vous sert à écrire du code. À la première exécution de l'instance expérimentale, vous êtes invité à vous connecter à VS en ligne et à spécifier vos thème et profil.

Dans le menu Outils (de l'instance expérimentale), vous devez voir un bouton nommé Mon nom de commande. Quand vous choisissez ce bouton, un message doit apparaître : Dans TestVSPackagePackage.MenuItemCallback().

Comment exécuter le code de mon complément dans un VSPackage ?

Un code de complément s'exécute généralement de l'une des deux façons suivantes :

déclenché par une commande de menu (le code se trouve dans la méthode IDTCommandTarget.Exec) ;
automatiquement au démarrage (le code se trouve dans le gestionnaire d'événements OnConnection.).

Vous pouvez procéder de la même façon dans un VSPackage. Voici comment ajouter du code de complément dans une méthode de rappel :

Créez un VSPackage comportant une commande de menu. (Consultez Comment démarrer le développement d'extensions VSPackage ?.)
Ouvrez le fichier contenant la définition du VSPackage. (Dans un projet C#, il s'agit de Package.cs de <nom de votre projet>.)
Ajoutez les instructions using suivantes au fichier :
```
using EnvDTE;
using EnvDTE80;
```
Recherchez la méthode MenuItemCallback. Ajoutez un appel à GetService pour obtenir l'objet DTE2 :
```
DTE2 dte = (DTE2)GetService(typeof(DTE));
```

Ajoutez le code de votre complément qui se trouve dans sa méthode IDTCommandTarget.Exec. Par exemple, voici du code qui permet d'ajouter un nouveau volet à la fenêtre Sortie et imprime du « texte » dans le nouveau volet.

private void MenuItemCallback(object sender, EventArgs e)
{
    DTE2 dte = (DTE2) GetService(typeof(DTE));
    OutputWindow outputWindow = dte.ToolWindows.OutputWindow;

    OutputWindowPane outputWindowPane = outputWindow.OutputWindowPanes.Add("A New Pane");
    outputWindowPane.OutputString("Some Text");
}

Générez et exécutez ce projet. Appuyez sur F5 ou sélectionnez Démarrer dans la barre d'outils Débogage. Dans l'instance expérimentale de Visual Studio, le menu Outils doit avoir un bouton nommé Mon nom de commande. Quand vous choisissez ce bouton, le mot Texte doit s'afficher dans un volet de fenêtre Sortie. (Vous devrez peut-être ouvrir la fenêtre Sortie.)

Votre code peut également s'exécuter au démarrage. Toutefois, cette approche est généralement déconseillée dans le cas des extensions VSPackage. Si un nombre trop élevé d'extensions sont chargées au démarrage de Visual Studio, le démarrage peut durer plus longtemps. Une meilleure pratique consiste à charger automatiquement le VSPackage uniquement quand une condition spécifique est satisfaite (comme l'ouverture d'une solution).

Cette procédure montre comment exécuter du code de complément dans un VSPackage qui est automatiquement chargé à l'ouverture d'une solution :

Pour charger automatiquement un VSPackage

Créez un complément de package Visual Studio. (Pour connaître les étapes à suivre, consultez Comment démarrer le développement d'extensions VSPackage ?. Nommez le projet TestAutoload et spécifiez son emplacement.
L'Assistant Package Visual Studio apparaît. Dans la page Sélectionner un langage de programmation, sélectionnez C# comme langage. Conservez l'option Générer une nouvelle clé sélectionnée. Choisissez Terminer.
Ouvrez TestAutoloadPackage.cs. Recherchez la ligne où la classe de package est déclarée :
```
public sealed class <name of your package>Package : Package
```
Un ensemble d'attributs se trouve au-dessus de cette ligne. Ajoutez cet attribut :
```
[ProvideAutoLoad(UIContextGuids80.SolutionExists)]
```
Définissez un point d'arrêt dans la méthode Initialize() et démarrez le débogage (F5).
Dans l'instance expérimentale, ouvrez un projet. Le VSPackage doit se charger et votre point d'arrêt doit être atteint.

Vous pouvez spécifier d'autres contextes dans lesquels charger votre VSPackage en utilisant les champs de UIContextGuids80. Pour plus d'informations, consultez Comment : chargez automatiquement un VSPackage.

Comment obtenir l'objet DTE ?

Si votre complément n'affiche pas des éléments d'interface utilisateur, tels que des commandes de menu, des boutons de barre d'outils ou des fenêtres Outil, vous devez pouvoir utiliser votre code tel quel, tant que vous obtenez l'objet d'automation DTE du VSPackage. Voici comment :

Pour obtenir l'objet DTE d'un VSPackage

Dans une solution VSPackage, recherchez le fichier Package.cs de <nom de projet>. Il s'agit de la classe dérivée de Package ; elle peut vous permettre d'interagir avec Visual Studio. Dans ce cas, vous utilisez sa méthode GetService pour obtenir l'objet DTE2.
Ajoutez ces instructions using :
```
using EnvDTE;
using EnvDTE80;
```
Recherchez la méthode Initialize. Cette méthode gère la commande que vous avez spécifiée dans l'Assistant Package. Ajoutez un appel à GetService pour obtenir l'objet DTE :
```
DTE dte = (DTE)GetService(typeof(DTE));
```

Une fois obtenu l'objet d'automation DTE, vous pouvez ajouter le reste votre code de complément au projet. Si vous avez besoin de l'objet DTE2, vous pouvez procéder de la même façon.

Les extensions VSPackage utilisent le fichier .vsct pour créer la plupart des commandes de menu, les barres d'outils et autres éléments d'interface utilisateur. Le modèle de projet VSPackage vous permet de créer une commande dans le menu Outils. Pour plus d'informations, consultez Procédure pas - à - pas : Créer une commande de menu à l'aide de le modèle de package Visual Studio.

Pour plus d'informations sur les fichiers .vsct, consultez Comment les VSPackages ajoutent des éléments de l'interface utilisateur à l'IDE. Pour obtenir des procédures pas à pas décrivant l'utilisation du fichier .vsct pour ajouter des éléments de menu, de barre d'outils et des boutons de barre d'outils, consultez Procédures pas - à - pas pour les commandes, de menus, et les barres d'outils.

Comment ajouter des fenêtres Outil personnalisées à la façon d'un VSPackage ?

Le modèle de projet VSPackage vous permet de créer une fenêtre Outil. Pour plus d'informations, consultez fenêtres Outil et les articles suivants, en particulier Comment : créez une fenêtre Outil.

Comment gérer des fenêtres Visual Studio à la façon d'un VSPackage ?

Si votre complément gère des fenêtres Visual Studio, le code de complément doit fonctionner dans un VSPackage. Par exemple, cette procédure illustre l'ajout de code qui gère la Liste des tâches à la méthode MenuItemCallback du VSPackage.

Pour insérer du code de gestion de fenêtres à partir d'un complément dans un VSPackage

Créez un VSPackage ayant une commande de menu, comme dans la section Comment démarrer le développement d'extensions VSPackage ?.
Ouvrez le fichier contenant la définition du VSPackage. (Dans un projet C#, il s'agit de Package.cs de <nom de votre projet>.)
Ajoutez ces instructions using :
```
using EnvDTE;
using EnvDTE80;
```
Recherchez la méthode MenuItemCallback. Ajoutez un appel à GetService pour obtenir l'objet DTE2 :
```
DTE2 dte = (DTE2)GetService(typeof(DTE));
```

Ajoutez le code à partir de votre complément. Par exemple, voici du code qui permet d'ajouter de nouvelles tâches à la Liste des tâches, de répertorier leur nombre et de supprimer une tâche.

private void MenuItemCallback(object sender, EventArgs e) 
{
    DTE2 dte = (DTE2) GetService(typeof(DTE)); 

    TaskList tl = (TaskList)dte.ToolWindows.TaskList; 
    askItem tlItem; 

    // Add a couple of tasks to the Task List. 
    tlItem = tl.TaskItems.Add(" ", " ", "Test task 1.",  
        vsTaskPriority.vsTaskPriorityHigh, vsTaskIcon.vsTaskIconUser, 
        true, "", 10, true, true);
    tlItem = tl.TaskItems.Add(" ", " ", "Test task 2.", 
        vsTaskPriority.vsTaskPriorityLow, vsTaskIcon.vsTaskIconComment, true, "", 20, true,true);

    // List the total number of task list items after adding the new task items.
    System.Windows.Forms.MessageBox.Show("Task Item 1 description: "+tl.TaskItems.Item(2).Description);
    System.Windows.Forms.MessageBox.Show("Total number of task items: "+tl.TaskItems.Count); 

    // Remove the second task item. The items list in reverse numeric order. 
    System.Windows.Forms.MessageBox.Show("Deleting the second task item");
    tl.TaskItems.Item(2).Delete();
    System.Windows.Forms.MessageBox.Show("Total number of task items: "+tl.TaskItems.Count); 
}

Comment gérer des projets et des solutions dans un VSPackage ?

Si votre complément gère des projets et des solutions, le code de complément doit fonctionner dans un VSPackage. Par exemple, cette procédure décrit l'ajout de code qui permet d'obtenir le projet de démarrage.

Créez un VSPackage ayant une commande de menu, comme dans la section Comment démarrer le développement d'extensions VSPackage ?.
Ouvrez le fichier contenant la définition du VSPackage. (Dans un projet C#, il s'agit de Package.cs de <nom de votre projet>.)
Ajoutez ces instructions using :
```
using EnvDTE;
using EnvDTE80;
```
Recherchez la méthode MenuItemCallback. Ajoutez un appel à GetService pour obtenir l'objet DTE2 :
```
DTE2 dte = (DTE2)GetService(typeof(DTE));
```

Ajoutez le code à partir de votre complément. Par exemple, le code suivant vous permet d'obtenir le nom du projet de démarrage dans une solution. (Une solution comprenant plusieurs projets doit être ouverte quand ce package est exécuté.)

private void MenuItemCallback(object sender, EventArgs e)
{
    DTE2 dte = (DTE2) GetService(typeof(DTE)); 

    SolutionBuild2 sb = (SolutionBuild2)dte.Solution.SolutionBuild; 
    Project startupProj; 
    string msg = "";

    foreach (String item in (Array)sb.StartupProjects) 
    {
        msg += item; 
    }
    System.Windows.Forms.MessageBox.Show("Solution startup Project: "+msg); 
    startupProj = dte.Solution.Item(msg); 
    System.Windows.Forms.MessageBox.Show("Full name of solution's startup project: "+"/n"+startupProj.FullName); 
}

Comment définir des raccourcis clavier dans un VSPackage ?

Vous utilisez l'élément <KeyBindings> du ficher .vsct. Dans l'exemple suivant, le raccourci clavier de la commande idCommand1 est Alt+A, et celui de la commande idCommand2 est Alt+Ctrl+A. Notez la syntaxe des noms de touches.

<KeyBindings>
    <KeyBinding guid="MyProjectCmdSet" id="idCommand1" editor="guidVSStd97" key1="A" mod1="ALT" />
    <KeyBinding guid="MyProjectCmdSet" id="idCommand2" editor="guidVSStd97" key1="A" mod1="CONTROL" mod2="ALT" />
</KeyBindings>

Comment gérer des événements d'automation dans un VSPackage ?

Vous gérez des événements d'automation dans un VSPackage de la même façon que dans votre complément. Le code suivant illustre la gestion de l'événement OnItemRenamed. (Cet exemple suppose que vous avez déjà obtenu l'objet DTE.)

Events2 dteEvents = (Events2)dte.Events;
dteEvents.ProjectItemsEvents.ItemRenamed += listener1.OnItemRenamed; 
. . .
public void OnItemRenamed(EnvDTE.ProjectItem projItem, string oldName) 
{
    string s = "[Event] Renamed " + oldName + " to " + Path.GetFileName(projItem.get_FileNames(1) + " in project " + projItem.ContainingProject.Name; 
}