Comment : utiliser des Assistants avec des modèles de projet
Visual Studio fournit l'interface IWizard qui, implémentée, vous permet d'exécuter un 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 effectuer les opérations suivantes :
afficher une interface utilisateur personnalisée qui collecte les entrées d'utilisateur pour paramétrer le modèle ;
ajouter des valeurs de paramètre à utiliser dans le modèle ;
ajouter des fichiers supplémentaires au modèle ;
exécuter pratiquement n'importe quelle action autorisée par le modèle objet Automation de Visual Studio sur un projet.
Les méthodes de l'interface IWizard sont appelées à différents moments au fil de 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 moment auquel elle est appelée. Par exemple, Visual Studio appelle immédiatement RunStarted dès qu'il commence à créer le projet, ce qui en fait un bon emplacement pour positionner un code personnalisé servant à collecter des entrées d'utilisateur.
Pour personnaliser le projet, la majeure partie du code que vous écrivez pour des Assistants personnalisés fait appel à l'objet DTE, qui constitue l'objet principal dans le modèle objet Automation de Visual Studio. Pour plus d'informations sur le modèle objet Automation, consultez Extension de l'environnement Visual Studio et Guide de référence de l'extensibilité et de l'automation.
Création d'un Assistant de modèle personnalisé
Cette rubrique indique comment créer un Assistant personnalisé qui ouvre un Windows Form avant que le projet soit créé. Ce formulaire permet à l'utilisateur d'ajouter une valeur de paramètre personnalisée qui sera à son tour ajoutée au code source pendant la création du projet. Les étapes principales, expliquées individuellement en détails, sont les suivantes :
Pour créer un Assistant de modèle personnalisé
Créez un assembly qui implémente l'interface IWizard.
Installez l'assembly dans le Global Assembly Cache.
Créez un projet et utilisez l'Assistant Exportation de modèle pour créer un modèle à partir du projet.
Modifiez le modèle en ajoutant un élément WizardExtension dans le fichier .vstemplate pour lier le modèle à l'assembly qui implémente IWizard.
Créer un projet à l'aide de l'Assistant personnalisé.
Implémentation d'IWizard
La première étape du processus consiste à créer un assembly qui implémente IWizard. Cet assembly utilise la méthode RunStarted pour afficher un Windows Form qui permet à l'utilisateur d'ajouter une valeur de paramètre personnalisée, qui sera utilisée pendant la création du projet.
Notes
Cet exemple utilise Visual C# pour implémenter IWizard, bien que vous puissiez également utiliser Visual Basic.
Pour implémenter IWizard
Créez un projet Bibliothèque de classes.
Définissez une classe qui implémente l'interface IWizard. Consultez le code ci-dessous pour un exemple Visual C# d'une interface IWizard intégralement implémentée.
Cet exemple contient deux fichiers de code : IWizardImplementation, une classe qui implémente l'interface IWizard, et UserInputForm, le Windows Form destiné aux entrées d'utilisateur.
Classe IWizardImplementation
La classe IWizardImplementation contient des implémentations de méthodes pour chaque membre de IWizard. Dans cet exemple, seule la méthode RunStarted réalise une tâche. Les autres méthodes ne font rien ou retournent true.
La méthode RunStarted accepte quatre paramètres :
Un paramètre Object, dont un cast en objet _DTE racine peut être effectué, pour vous permettre de personnaliser le projet.
Un 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.
Un paramètre WizardRunKind qui contient des informations sur le type de modèle utilisé.
Un tableau Object qui contient un jeu de paramètres passé à l'Assistant par Visual Studio.
Cet exemple ajoute une valeur de paramètre issue du formulaire des entrées d'utilisateur au paramètre Dictionary<TKey, TValue>. Chaque instance du paramètre $custommessage$ dans le projet est remplacée par le texte saisi par l'utilisateur.
using System;
using System.Collections.Generic;
using Microsoft.VisualStudio.TemplateWizard;
using System.Windows.Forms;
using EnvDTE;
namespace CustomWizard
{
public class IWizardImplementation: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 = inputForm.get_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;
}
}
}
Formulaire des entrées d'utilisateur
Le formulaire des entrées d'utilisateur constitue un support 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 activé, le texte présent dans la zone de texte est enregistré dans le paramètre customMessage.
Pour ajouter un Windows Form à la solution
Dans le menu Projet, cliquez sur Ajouter un nouvel élément.
Cliquez sur Windows Form, nommez le fichier UserInputForm.cs, puis cliquez sur OK.
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
namespace CustomWizard
{
public partial class UserInputForm : Form
{
private string customMessage;
public UserInputForm()
{
InitializeComponent();
}
public string get_CustomMessage()
{
return customMessage;
}
private void button1_Click(object sender, EventArgs e)
{
customMessage = textBox1.Text;
this.Dispose();
}
}
}
Installation de l'assembly dans le Global Assembly Cache
L'assembly qui implémente IWizard doit être signé avec un nom fort et installé dans le Global Assembly Cache.
Pour installer l'assembly dans le Global Assembly Cache
Signez l'assembly avec un nom fort. Pour plus d'informations, consultez Comment : signer un assembly avec un nom fort ou Comment : signer un assembly (Visual Studio) ;
Installez l'assembly avec nom fort dans le Global Assembly Cache. Pour plus d'informations, consultez Comment : installer un assembly dans le Global Assembly Cache.
Création d'un projet à utiliser comme modèle
Dans cet exemple, le projet utilisé en tant que modèle consiste en une application console qui affiche le message spécifié dans le formulaire des entrées d'utilisateur de l'Assistant personnalisé.
Pour créer l'exemple de projet
Créez une application console Visual C#.
Dans la méthode Main de l'application, ajoutez la ligne de code suivante :
Console.WriteLine("$custommessage$");Le paramètre $custommessage$ est remplacé par le texte saisi dans le formulaire des entrées d'utilisateur lorsqu'un projet est créé à partir du modèle.
Dans le menu Fichier, cliquez sur Exporter le modèle.
Dans l'Assistant Exportation de modèle, cliquez sur Modèle de projet, sélectionnez le projet approprié, puis cliquez sur Suivant.
Dans l'Assistant Exportation de modèle, entrez des informations descriptives relatives au modèle, activez la case à cocher Importer automatiquement le modèle dans Visual Studio, puis cliquez sur Terminer.
Le modèle s'affiche à présent dans la boîte de dialogue Nouveau projet, mais n'utilise pas l'Assistant personnalisé.
L'exemple suivant présente le fichier du code intégral avant son exportation vers un modèle.
using System;
using System.Collections.Generic;
using System.Text;
namespace TemplateProject
{
class WriteMessage
{
static void Main(string[] args)
{
Console.WriteLine("$custommessage$");
}
}
}
Modification du modèle
Maintenant que le modèle est créé et qu'il s'affiche dans la boîte de dialogue Nouveau projet, vous devez le modifier afin qu'il utilise l'assembly que vous avez créé au cours des étapes précédentes.
Pour ajouter l'Assistant personnalisé au modèle
Localisez le fichier .zip qui contient le modèle.
Dans le menu Outils, cliquez sur Options.
Cliquez sur Projets et solutions.
Lisez le contenu de la zone de texte Emplacement des modèles de projet pour l'utilisateur de Visual Studio. Pour plus d'informations, consultez Général, Projets et solutions, boîte de dialogue Options.
Par défaut, cet emplacement est Mes Documents\Visual Studio 2010\Templates\ProjectTemplates.
Extrayez le fichier .zip.
Ouvrez le fichier .vstemplate dans Visual Studio.
Après l'élément TemplateContent, ajoutez un élément WizardExtension, élément (modèles Visual Studio) avec le nom fort de votre assembly d'Assistant personnalisé. Pour plus d'informations sur la recherche du nom fort de votre assembly, consultez Comment : visualiser le contenu du Global Assembly Cache et Comment : référencer un assembly avec nom fort.
L'exemple suivant présente un élément WizardExtension.
<WizardExtension> <Assembly>CustomWizard, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=fa3902f409bb6a3b</Assembly> <FullClassName>CustomWizard.IWizardImplementation</FullClassName> </WizardExtension>
Utilisation de l'Assistant personnalisé
Vous pouvez à présent créer un projet à partir de votre modèle et utiliser l'Assistant personnalisé.
Pour utiliser l'Assistant personnalisé
Dans le menu Fichier, cliquez sur Nouveau projet.
Dans la boîte de dialogue Nouveau projet, localisez votre modèle, tapez un nom et cliquez sur OK.
Le formulaire des entrées d'utilisateur de l'Assistant s'affiche.
Tapez une valeur pour le paramètre personnalisé, puis cliquez sur le bouton.
Le formulaire des entrées d'utilisateur de l'Assistant se ferme ; un projet est créé à partir du modèle.
Dans l'Explorateur de solutions, cliquez avec le bouton droit sur le fichier du code source, puis cliquez sur Afficher le code.
Remarquez que $custommessage$ a été remplacé par le texte entré dans le formulaire des entrées d'utilisateur de l'Assistant.
Voir aussi
Référence
WizardExtension, élément (modèles Visual Studio)