Gewusst wie: Verwenden von Assistenten mit Projektvorlagen

Artikel
08/20/2008

Aktualisiert: November 2007

Visual Studio stellt die IWizard-Schnittstelle bereit, die, falls sie implementiert ist, das Ausführen von benutzerdefiniertem Code beim Erstellen eines Projekts aus einer Vorlage ermöglicht.

Durch das Anpassen von Projektvorlagen können Sie folgende Aufgaben ausführen:

Anzeigen einer benutzerdefinierten Benutzeroberfläche, die Benutzereingaben zur Parametrisierung der Vorlage erfasst
Hinzufügen von Parameterwerten zur Verwendung in der Vorlage
Hinzufügen von zusätzlichen Dateien zur Vorlage
Ausführen praktisch aller im Visual Studio Automatisierungsobjektmodell zulässigen Aktionen für ein Projekt

Die IWizard-Schnittstellenmethoden werden zu verschiedenen Zeitpunkten während der Erstellung des Projekts aufgerufen, wenn ein Benutzer im Dialogfeld Neues Projekt auf OK klickt. Die Namen der einzelnen Methoden der Schnittstelle beschreiben jeweils den Zeitpunkt, zu dem sie aufgerufen werden. Visual Studio ruft RunStarted beispielsweise auf, wenn das Erstellen des Projekts gestartet wird. Daher eignet sich diese Position gut für benutzerdefinierten Code zur Erfassung von Benutzereingaben.

In Code, den Sie für benutzerdefinierte Assistenten schreiben, wird meistens das DTE-Objekt zum Anpassen des Projekts verwendet. Dies ist das wichtigste Objekt im Visual Studio-Automatisierungsobjektmodell. Weitere Informationen über das Automatisierungsobjektmodell finden Sie unter Erweitern der Visual Studio-Umgebung und Referenz zur Automatisierung und Erweiterbarkeit

Erstellen eines benutzerdefinierten Vorlagen-Assistenten

In diesem Thema wird das Erstellen eines benutzerdefinierten Vorlagen-Assistenten veranschaulicht, der vor dem Erstellen des Projekts ein Windows Form öffnet. Das Formular ermöglicht Benutzern das Hinzufügen eines benutzerdefinierten Parameterwerts, der während der Erstellung des Projekts dem Quellcode hinzugefügt wird. Im Folgenden werden die einzelnen Hauptschritte im Detail beschrieben.

So erstellen Sie einen benutzerdefinierten Vorlagen-Assistenten

Erstellen Sie eine Assembly, die die IWizard-Schnittstelle implementiert.
Installieren Sie die Assembly im globalen Assemblycache.
Erstellen Sie ein Projekt, und erstellen Sie mithilfe des Assistenten zum Exportieren von Vorlagen eine Vorlage aus dem Projekt.
Bearbeiten Sie die Vorlage, indem Sie der VSTEMPLATE-Datei ein WizardExtension-Element hinzufügen, um die Vorlage mit der Assembly zu verknüpfen, die IWizard implementiert.
Erstellen Sie mit dem benutzerdefinierten Assistenten ein neues Projekt.

Implementieren von IWizard

Der erste Schritt besteht darin, eine Assembly zu erstellen, die IWizard implementiert. Diese Assembly zeigt mithilfe der RunStarted-Methode ein Windows Form an, das Benutzern das Hinzufügen eines benutzerdefinierten Parameterwerts ermöglicht, der während der Erstellung des Projekts verwendet wird.

Hinweis:
In diesem Beispiel wird Visual C# verwendet, um IWizard zu implementieren. Alternativ können Sie auch Visual J# oder Visual Basic verwenden.

So implementieren Sie IWizard

Erstellen Sie ein neues Klassenbibliotheksprojekt.
Erstellen Sie eine Klasse, die die IWizard-Schnittstelle implementiert. Ein Visual C#-Beispiel für eine vollständig implementierte IWizard-Schnittstelle finden Sie im nachfolgenden Code.

Dieses Beispiel umfasst zwei Codedateien: IWizardImplementation, eine Klasse, die die IWizard-Schnittstelle implementiert, sowie UserInputForm, das Windows Form für Benutzereingaben.

IWizardImplementation-Klasse

Die IWizardImplementation-Klasse enthält Methodenimplementierungen für alle Member von IWizard. In diesem Beispiel führt nur die RunStarted-Methode eine Aufgabe aus. Alle anderen Methoden bleiben entweder ohne Wirkung oder geben true zurück.

Die RunStarted-Methode nimmt vier Parameter an:

Einen Object-Parameter, der in das _DTE-Stammobjekt umgewandelt werden kann, um die Anpassung des Projekts zu ermöglichen.
Einen Dictionary<TKey, TValue>-Parameter, der eine Auflistung aller vordefinierten Parameter in der Vorlage enthält. Weitere Informationen zu Vorlagenparametern finden Sie unter Vorlagenparameter.
Einen WizardRunKind-Parameter, der Informationen zur Art der verwendeten Vorlage enthält.
Ein Object-Array, das einen Satz von Parametern enthält, die von Visual Studio an den Assistenten übergeben werden.

In diesem Beispiel wird dem Dictionary<TKey, TValue>-Parameter ein Parameterwert aus dem Benutzereingabeformular hinzugefügt. Jede Instanz des $custommessage$-Parameters im Projekt wird durch den vom Benutzer eingegebenen Text ersetzt.

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;
        }        
    }
}

Benutzereingabeformular

Das Benutzereingabeformular stellt ein einfaches Formular zur Eingabe eines benutzerdefinierten Parameters bereit. Das Formular enthält ein Textfeld mit dem Namen textBox1 und eine Schaltfläche mit dem Namen button1. Wenn auf die Schaltfläche geklickt wird, wird der Text aus dem Textfeld im customMessage-Parameter gespeichert.

So fügen Sie der Projektmappe ein Windows Form hinzu

Klicken Sie im Menü Projekt auf Neues Element hinzufügen.
Klicken Sie auf Windows Form, benennen Sie die Datei UserInputForm.cs, und klicken Sie auf 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();
        }
    }
}

Installieren der Assembly in den globalen Assemblycache

Die Assembly, die IWizard implementiert, muss mit einem starken Namen signiert und im globalen Assemblycache installiert werden.

So installieren Sie die Assembly im globalen Assemblycache

Signieren Sie die Assembly mit einem starkem Namen. Weitere Informationen hierzu finden Sie unter Gewusst wie: Signieren einer Assembly mit einem starken Namen oder unter Gewusst wie: Signieren von Assemblys (Visual Studio).
Installieren Sie die mit einem starkem Namen signierte Assembly im globalen Assemblycache. Weitere Informationen finden Sie unter Gewusst wie: Installieren einer Assembly in den globalen Assemblycache.

Erstellen eines als Vorlage zu verwendenden Projekts

Das in diesem Beispiel als Vorlage verwendete Projekt ist eine Konsolenanwendung, die die im Benutzereingabeformular des benutzerdefinierten Assistenten angegebene Meldung anzeigt.

So erstellen Sie das Beispielprojekt

Erstellen Sie eine neue Visual C#-Konsolenanwendung.
Fügen Sie der Main-Methode der Anwendung die folgende Codezeile hinzu.
```
Console.WriteLine("$custommessage$");
```
Der $custommessage$-Parameter wird beim Erstellen eines Projekts aus der Vorlage durch den im Benutzereingabeformular eingegebenen Text ersetzt.
Klicken Sie im Menü Datei auf Vorlage exportieren.
Klicken Sie im Assistenten zum Exportieren von Vorlagen auf Projektvorlage, wählen Sie das zutreffende Projekt aus, und klicken Sie auf Weiter.
Geben Sie im Assistenten zum Exportieren von Vorlagen eine Beschreibung der Vorlage ein, aktivieren Sie das Kontrollkästchen Vorlage automatisch in Visual Studio importieren, und klicken Sie auf Fertig stellen.

Die Vorlage wird nun im Dialogfeld Neues Projekt angezeigt, sie verwendet jedoch nicht den benutzerdefinierten Assistenten.

Im folgenden Beispiel wird die vollständige Codedatei vor dem Exportieren in eine Vorlage dargestellt.

using System;
using System.Collections.Generic;
using System.Text;

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

Ändern der Vorlage

Nachdem die Vorlage erstellt wurde und im Dialogfeld Neues Projekt angezeigt wird, müssen Sie sie ändern, damit sie die in den vorhergehenden Schritten erstellte Assembly verwendet.

So fügen Sie der Vorlage den benutzerdefinierten Assistenten hinzu

Suchen Sie die ZIP-Datei, die die Vorlage enthält.
1. Klicken Sie im Menü Extras auf Optionen.
2. Klicken Sie auf Projekte und Projektmappen.
3. Lesen Sie das Textfeld Speicherort von Visual Studio-Benutzerprojektvorlagen. Weitere Informationen finden Sie unter Allgemein, Projekte und Projektmappen, Dialogfeld "Optionen".
Dieses Verzeichnis lautet standardmäßig Eigene Dateien\Visual Studio 2008\Templates\ProjectTemplates.
Extrahieren Sie die ZIP-Datei.
Öffnen Sie die VSTEMPLATE-Datei in Visual Studio.
Fügen Sie hinter dem TemplateContent-Element ein WizardExtension-Element (Visual Studio-Vorlagen)-Element mit dem starken Namen der benutzerdefinierten Assistentenassembly hinzu. Weitere Informationen zum Suchen des starken Namens der Assembly finden Sie unter Gewusst wie: Anzeigen der Inhalte des globalen Assemblycaches und Gewusst wie: Verweisen auf eine Assembly mit starkem Namen

Im folgenden Beispiel wird ein WizardExtension-Element veranschaulicht.
```
<WizardExtension>
    <Assembly>CustomWizard, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=fa3902f409bb6a3b</Assembly>
    <FullClassName>CustomWizard.IWizardImplementation</FullClassName>
</WizardExtension>
```

Verwenden des benutzerdefinierten Assistenten

Nun können Sie ein Projekt aus der Vorlage erstellen und den benutzerdefinierten Assistenten verwenden.

So verwenden Sie den benutzerdefinierten Assistenten

Klicken Sie im Menü Datei auf Neues Projekt.
Suchen Sie im Dialogfeld Neues Projekt nach der Vorlage, geben Sie einen Namen ein, und klicken Sie auf OK.

Das Benutzereingabeformular des Assistenten wird geöffnet.
Geben Sie einen Wert für den benutzerdefinierten Parameter ein, und klicken Sie auf die Schaltfläche.

Das Benutzereingabeformular des Assistenten wird geschlossen, und aus der Vorlage wird ein Projekt erstellt.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Quellcodedatei, und wählen Sie Code anzeigen aus.

Beachten Sie, dass $custommessage$ durch den im Benutzereingabeformular des Assistenten eingegebenen Text ersetzt wurde.

Siehe auch

Referenz

WizardExtension-Element (Visual Studio-Vorlagen)

IWizard

Weitere Ressourcen

Erweiterte Verfahren für Vorlagen

Freigeben über