Utiliser des Assistants avec des modèles de projet

Article
06/19/2023

Visual Studio fournit l’interface IWizard qui, en cas d’implémentation, vous permet d’exécuter du code personnalisé lorsqu’un utilisateur crée un projet à partir d’un modèle.

La personnalisation du modèle de projet peut être utilisée pour afficher l’interface utilisateur personnalisée qui collecte les entrées utilisateur pour personnaliser le modèle, ajouter des fichiers supplémentaires au modèle ou toute autre action autorisée sur un projet.

Les IWizard méthodes d’interface sont appelées à différents moments pendant la création du projet, en commençant dès qu’un utilisateur clique sur OK dans la boîte de dialogue Nouveau projet . Chaque méthode de l’interface est nommée pour décrire le point auquel elle est appelée. Par exemple, Visual Studio appelle RunStarted immédiatement lorsqu’il commence à créer le projet, ce qui en fait un bon emplacement pour écrire du code personnalisé pour collecter les entrées utilisateur.

Créer un projet de modèle de projet avec un projet VSIX

Vous commencez à créer un modèle personnalisé avec le projet de modèle de projet, qui fait partie du Kit de développement logiciel (SDK) Visual Studio. Dans cette procédure, nous allons utiliser un projet de modèle de projet C#, mais il existe également un projet de modèle de projet Visual Basic. Ensuite, vous ajoutez un projet VSIX à la solution qui contient le projet de modèle de projet.

Créez un projet de modèle de projet C# (dans Visual Studio, sélectionnez Nouveau>>projet et recherchez « modèle de projet »). Nommez-le MyProjectTemplate.

Remarque

Vous serez peut-être invité à installer le Kit de développement logiciel (SDK) Visual Studio. Pour plus d’informations, consultez Installation du Kit de développement logiciel (SDK) Visual Studio.
Ajoutez un nouveau projet VSIX dans la même solution que le projet de modèle de projet (dans Explorateur de solutions, sélectionnez le nœud de solution, cliquez avec le bouton droit, puis sélectionnez Ajouter>un nouveau projet et recherchez « vsix »). Nommez-le MyProjectWizard.
Définissez le projet VSIX comme projet de démarrage. Dans Explorateur de solutions, sélectionnez le nœud du projet VSIX, cliquez avec le bouton droit et sélectionnez Définir comme projet de démarrage.
Ajoutez le projet de modèle en tant que ressource du projet VSIX. Dans Explorateur de solutions, sous le nœud du projet VSIX, recherchez le fichier source.extension.vsixmanifest. Double-cliquez dessus pour l’ouvrir dans l’éditeur de manifeste.
Dans l’éditeur de manifeste, sélectionnez l’onglet Ressources sur le côté gauche de la fenêtre.
Sous l’onglet Ressources , sélectionnez Nouveau. Dans la fenêtre Ajouter un nouvel élément multimédia , pour le champ Type, sélectionnez Microsoft.VisualStudio.ProjectTemplate. Dans le champ Source , sélectionnez Un projet dans la solution actuelle. Dans le champ Projet , sélectionnez MyProjectTemplate. Cliquez ensuite sur OK.
Générez la solution et commencez le débogage. Une seconde instance de Visual Studio apparaît. (Cela peut prendre quelques minutes.)
Dans la deuxième instance de Visual Studio, essayez de créer un projet avec votre nouveau modèle (Nouveau>>projet de fichier, recherchez « myproject »). Le nouveau projet doit apparaître avec une classe nommée Class1. Vous avez maintenant créé un modèle de projet personnalisé ! Arrêtez le débogage maintenant.

Créer un Assistant Modèle personnalisé

Cette procédure montre comment créer un Assistant personnalisé qui ouvre un Windows Form avant la création du projet. Le formulaire permet aux utilisateurs d’ajouter une valeur de paramètre personnalisée ajoutée au code source lors de la création du projet.

Configurez le projet VSIX pour lui permettre de créer un assembly.
Dans Explorateur de solutions, sélectionnez le nœud de projet VSIX. Ci-dessous Explorateur de solutions, la fenêtre Propriétés doit s’afficher. Si ce n’est pas le cas, sélectionnez Afficher>la fenêtre Propriétés, ou appuyez sur F4. Dans la fenêtre Propriétés , sélectionnez les champs suivants pour true:
- Inclure un assembly dans un conteneur VSIX
- Inclure des symboles de débogage dans le déploiement VSIX local
- Inclure des symboles de débogage dans un conteneur VSIX
Ajoutez l’assembly en tant que ressource au projet VSIX. Ouvrez le fichier source.extension.vsixmanifest et sélectionnez l’onglet Ressources . Dans la fenêtre Ajouter un nouvel élément multimédia , pour Type , sélectionnez Microsoft.VisualStudio.Assembly, pour Source sélectionnez Un projet dans la solution actuelle, puis, pour Project , sélectionnez MyProjectWizard.
Ajoutez les références suivantes au projet VSIX. (Dans Explorateur de solutions, sous le nœud du projet VSIX, sélectionnez Références, cliquez avec le bouton droit, puis sélectionnez Ajouter une référence.) Dans la boîte de dialogue Ajouter une référence, sous l’onglet Framework, recherchez l’assembly System.Windows Forms et sélectionnez-le. Recherchez et sélectionnez également les assemblys System et System.Drawing . Sélectionnez maintenant l’onglet Extensions . Recherchez l’assembly EnvDTE et sélectionnez-le. Recherchez également l’assembly Microsoft.VisualStudio.TemplateWizardInterface et sélectionnez-le. Cliquez sur OK.
Ajoutez une classe pour l’implémentation de l’Assistant au projet VSIX. (Dans Explorateur de solutions, cliquez avec le bouton droit sur le nœud du projet VSIX, puis sélectionnez Ajouter, puis Nouvel élément, puis Classe.) Nommez la classe WizardImplementation.

Remplacez le code dans le fichier WizardImplementationClass.cs par le code suivant :

using System;
using System.Collections.Generic;
using Microsoft.VisualStudio.TemplateWizard;
using System.Windows.Forms;
using EnvDTE;

namespace MyProjectWizard
{
    public class WizardImplementation:IWizard
    {
        private UserInputForm inputForm;
        private string customMessage;

        // This method is called before opening any item that
        // has the OpenInEditor attribute.
        public void BeforeOpeningFile(ProjectItem projectItem)
        {
        }

        public void ProjectFinishedGenerating(Project project)
        {
        }

        // This method is only called for item templates,
        // not for project templates.
        public void ProjectItemFinishedGenerating(ProjectItem
            projectItem)
        {
        }

        // This method is called after the project is created.
        public void RunFinished()
        {
        }

        public void RunStarted(object automationObject,
            Dictionary<string, string> replacementsDictionary,
            WizardRunKind runKind, object[] customParams)
        {
            try
            {
                // Display a form to the user. The form collects
                // input for the custom message.
                inputForm = new UserInputForm();
                inputForm.ShowDialog();

                customMessage = UserInputForm.CustomMessage;

                // Add custom parameters.
                replacementsDictionary.Add("$custommessage$",
                    customMessage);
            }
            catch (Exception ex)
            {
                MessageBox.Show(ex.ToString());
            }
        }

        // This method is only called for item templates,
        // not for project templates.
        public bool ShouldAddProjectItem(string filePath)
        {
            return true;
        }
    }
}

UserInputForm référencé dans ce code sera implémenté ultérieurement.

La WizardImplementation classe contient des implémentations de méthode pour chaque membre de IWizard. Dans cet exemple, seule la RunStarted méthode effectue une tâche. Toutes les autres méthodes ne font rien ou ne retournent truerien.

La RunStarted méthode accepte quatre paramètres :

Paramètre Object pouvant être converti en objet racine _DTE , pour vous permettre de personnaliser le projet.
Paramètre Dictionary<TKey,TValue> qui contient une collection de tous les paramètres prédéfinis dans le modèle. Pour plus d’informations sur les paramètres de modèle, consultez Paramètres de modèle.
Paramètre WizardRunKind qui contient des informations sur le type de modèle utilisé.
Tableau Object qui contient un ensemble de paramètres transmis à l’Assistant par Visual Studio.

Cet exemple montre comment ajouter une valeur de paramètre du formulaire d’entrée utilisateur au Dictionary<TKey,TValue> paramètre. Chaque instance du $custommessage$ paramètre dans le projet sera remplacée par le texte entré par l’utilisateur.

Créez maintenant UserInputForm. Dans le fichier WizardImplementation.cs , ajoutez le code suivant après la fin de la WizardImplementation classe.

public partial class UserInputForm : Form
    {
        private static string customMessage;
        private TextBox textBox1;
        private Button button1;

        public UserInputForm()
        {
            this.Size = new System.Drawing.Size(155, 265);

            button1 = new Button();
            button1.Location = new System.Drawing.Point(90, 25);
            button1.Size = new System.Drawing.Size(50, 25);
            button1.Click += button1_Click;
            this.Controls.Add(button1);

            textBox1 = new TextBox();
            textBox1.Location = new System.Drawing.Point(10, 25);
            textBox1.Size = new System.Drawing.Size(70, 20);
            this.Controls.Add(textBox1);
        }
        public static string CustomMessage
        {
            get
            {
                return customMessage;
            }
            set
            {
                customMessage = value;
            }
        }
        private void button1_Click(object sender, EventArgs e)
        {
            customMessage = textBox1.Text;
            this.Close();
        }
    }

Le formulaire d’entrée utilisateur fournit un formulaire simple pour entrer un paramètre personnalisé. Le formulaire contient une zone de texte nommée textBox1 et un bouton nommé button1. Lorsque le bouton est cliqué, le texte de la zone de texte est stocké dans le customMessage paramètre.

Connecter l’Assistant au modèle personnalisé

Pour que votre modèle de projet personnalisé utilise votre Assistant personnalisé, vous devez signer l’assembly de l’Assistant et ajouter des lignes à votre modèle de projet personnalisé pour lui faire savoir où trouver l’implémentation de l’Assistant lorsqu’un nouveau projet est créé.

Signez l’assembly. Dans le Explorateur de solutions, sélectionnez le projet VSIX, cliquez avec le bouton droit et sélectionnez Propriétés du projet.
Dans la fenêtre Propriétés du projet, sélectionnez l’onglet Signature. Dans l’onglet Signature, case activée Signer l’assembly. Dans le champ Choisir un fichier de clé de nom fort, sélectionnez <Nouveau>. Dans la fenêtre Créer une clé de nom fort, dans le champ Nom du fichier clé, tapez key.snk. Annulez case activée le fichier Protéger mon fichier de clé avec un champ de mot de passe.
Dans le Explorateur de solutions, sélectionnez le projet VSIX et recherchez la fenêtre Propriétés.
Définissez le champ Copier la sortie de build sur le champ Répertoire de sortie sur true. Cela permet à l’assembly d’être copié dans le répertoire de sortie lorsque la solution est reconstruite. Il est toujours contenu dans le .vsix fichier. Vous devez voir l’assembly pour connaître sa clé de signature.
Recréez la solution.
Vous pouvez maintenant trouver le fichier key.snk dans le répertoire du projet MyProjectWizard (<votre emplacement> de disque\MyProjectTemplate\MyProjectWizard\key.snk). Copiez le fichier key.snk .
Accédez au répertoire de sortie et recherchez l’assembly (<votre emplacement> de disque\MyProjectTemplate/MyProjectWizard\bin\Debug\MyProjectWizard.dll). Collez le fichier key.snk ici. (Cela n’est pas absolument nécessaire, mais cela facilite les étapes suivantes.)
Ouvrez une fenêtre de commande et accédez au répertoire dans lequel l’assembly a été créé.
Recherchez l’outil de signature sn.exe . Par exemple, sur un système d’exploitation Windows 10 64 bits, un chemin d’accès classique est le suivant :

C :\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools

Si vous ne trouvez pas l’outil, essayez d’exécuter /R . sn.exe dans la fenêtre de commande. Notez le chemin d’accès.
Extrayez la clé publique du fichier key.snk . Dans la fenêtre de commande, tapez

<emplacement de sn.exe>\sn.exe -p key.snk outfile.key.

N’oubliez pas d’entourer le chemin d’accès de sn.exe avec des guillemets s’il existe des espaces dans les noms de répertoires !
Obtenez le jeton de clé publique à partir du fichier outfile :

<emplacement de sn.exe>\sn.exe -t outfile.key.

Encore une fois, n’oubliez pas les guillemets. Vous devriez voir une ligne dans la sortie comme celle-ci

Jeton de clé publique est <un jeton>

Notez cette valeur.
Ajoutez la référence à l’Assistant personnalisé au fichier .vstemplate du modèle de projet. Dans le Explorateur de solutions, recherchez le fichier nommé MyProjectTemplate.vstemplate, puis ouvrez-le. Après la fin de la <section TemplateContent> , ajoutez la section suivante :
```
<WizardExtension>
    <Assembly>MyProjectWizard, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=token</Assembly>
    <FullClassName>MyProjectWizard.WizardImplementation</FullClassName>
</WizardExtension>
```
Où MyProjectWizard est le nom de l’assembly, et le jeton est le jeton que vous avez copié à l’étape précédente.
Enregistrez tous les fichiers dans le projet et régénérez.

Ajouter le paramètre personnalisé au modèle

Dans cet exemple, le projet utilisé comme modèle affiche le message spécifié dans le formulaire d’entrée utilisateur de l’Assistant personnalisé.

Dans le Explorateur de solutions, accédez au projet MyProjectTemplate et ouvrez Class1.cs.
Dans la Main méthode de l’application, ajoutez la ligne de code suivante.
```
Console.WriteLine("$custommessage$");
```
Le paramètre $custommessage$ est remplacé par le texte entré dans le formulaire d’entrée utilisateur lorsqu’un projet est créé à partir du modèle.

Voici le fichier de code complet avant d’être exporté vers un modèle.

using System;
using System.Collections.Generic;
$if$ ($targetframeworkversion$ >= 3.5)using System.Linq;
$endif$using System.Text;

namespace $safeprojectname$
{
    public class Class1
    {
          static void Main(string[] args)
          {
               Console.WriteLine("$custommessage$");
          }
    }
}

Utiliser l’Assistant personnalisé

Vous pouvez maintenant créer un projet à partir de votre modèle et utiliser l’Assistant personnalisé.

Régénérez la solution et démarrez le débogage. Une seconde instance de Visual Studio doit apparaître.
Créez un projet MyProjectTemplate. (Nouveau projet de fichier>>).
Dans la boîte de dialogue Nouveau projet , recherchez « myproject » pour localiser votre modèle, tapez un nom, puis cliquez sur OK.

Le formulaire d’entrée utilisateur de l’Assistant s’ouvre.
Tapez une valeur pour le paramètre personnalisé, puis cliquez sur le bouton.

Le formulaire d’entrée utilisateur de l’Assistant se ferme et un projet est créé à partir du modèle.
Dans Explorateur de solutions, cliquez avec le bouton droit sur le fichier de code source, puis cliquez sur Afficher le code.

Notez qu’il $custommessage$ a été remplacé par le texte entré dans le formulaire d’entrée utilisateur de l’Assistant.