Verwenden von Assistenten mit Projektvorlagen

Artikel
10/10/2023

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.

Die Anpassung der Projektvorlage kann verwendet werden, um benutzerdefinierte Benutzeroberfläche anzuzeigen, die Benutzereingaben sammelt, um die Vorlage anzupassen, der Vorlage zusätzliche Dateien hinzuzufügen oder eine andere aktion, die für ein Projekt zulässig ist.

Die IWizard Schnittstellenmethoden werden zu verschiedenen Zeiten aufgerufen, während das Projekt erstellt wird, beginnend, sobald 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 z. B. sofort auf, wenn es mit der Erstellung des Projekts beginnt, wodurch es zu einem guten Speicherort für das Schreiben von benutzerdefiniertem Code zum Sammeln von Benutzereingaben wird.

Erstellen eines Projektvorlagenprojekts mit einem VSIX-Projekt

Sie beginnen mit dem Erstellen einer benutzerdefinierten Vorlage mit dem Projektvorlagenprojekt, das Teil des Visual Studio SDK ist. In diesem Verfahren verwenden wir ein C#-Projektvorlagenprojekt, aber es gibt auch ein Visual Basic-Projektvorlagenprojekt. Anschließend fügen Sie der Projektmappe, die das Projektvorlagenprojekt enthält, ein VSIX-Projekt hinzu.

Erstellen Sie ein C#-Projektvorlagenprojekt (wählen Sie in Visual Studio "Neues>Projekt">aus, und suchen Sie nach "Projektvorlage"). Nennen Sie es "MyProjectTemplate".

Hinweis

Möglicherweise werden Sie aufgefordert, das Visual Studio SDK zu installieren. Weitere Informationen finden Sie unter Installieren des Visual Studio SDK.
Fügen Sie ein neues VSIX-Projekt in derselben Projektmappe wie das Projektvorlagenprojekt hinzu (wählen Sie in Projektmappen-Explorer den Projektmappenknoten aus, klicken Sie mit der rechten Maustaste, und wählen Sie "Neues Projekt hinzufügen>" aus, und suchen Sie nach "vsix"). Nennen Sie es MyProjectWizard.
Legen Sie das VSIX-Projekt als Startprojekt fest. Wählen Sie in Projektmappen-Explorer den VSIX-Projektknoten aus, klicken Sie mit der rechten Maustaste, und wählen Sie "Als Startprojekt festlegen" aus.
Fügen Sie das Vorlagenprojekt als Objekt des VSIX-Projekts hinzu. Suchen Sie in Projektmappen-Explorer unter dem VSIX-Projektknoten die Datei "source.extension.vsixmanifest". Doppelklicken Sie darauf, um sie im Manifest-Editor zu öffnen.
Wählen Sie im Manifest-Editor die Registerkarte "Objekte " auf der linken Seite des Fensters aus.
Wählen Sie auf der Registerkarte "Objekte" die Option "Neu" aus. Wählen Sie im Fenster "Neue Ressource hinzufügen" für das Feld "Typ" die Option "Microsoft.VisualStudio.ProjectTemplate" aus. Wählen Sie im Feld "Quelle" die Option "Ein Projekt in der aktuellen Projektmappe" aus. Wählen Sie im Feld "Projekt" die Option "MyProjectTemplate" aus. Klicken Sie dann auf OK.
Erstellen Sie die Projektmappe, und beginnen Sie mit dem Debuggen. Eine zweite Instanz von Visual Studio wird geöffnet. (Dies kann einige Minuten dauern.)
Versuchen Sie in der zweiten Instanz von Visual Studio, ein neues Projekt mit der neuen Vorlage zu erstellen (Datei>neues>Projekt, suchen Sie nach "myproject"). Das neue Projekt sollte mit einer Klasse namens "Class1" angezeigt werden. Sie haben jetzt eine benutzerdefinierte Projektvorlage erstellt! Beenden Sie das Debuggen jetzt.

Erstellen eines assistenten für benutzerdefinierte Vorlagen

Dieses Verfahren zeigt, wie Sie einen benutzerdefinierten Assistenten erstellen, der ein Windows Form öffnet, bevor das Projekt erstellt wird. Mit dem Formular können Benutzer während der Projekterstellung einen benutzerdefinierten Parameterwert hinzufügen, der dem Quellcode hinzugefügt wird.

Richten Sie das VSIX-Projekt ein, damit es eine Assembly erstellen kann.
Wählen Sie in Projektmappen-Explorer den VSIX-Projektknoten aus. Unter Projektmappen-Explorer sollte das Eigenschaftenfenster angezeigt werden. Wenn Sie dies nicht tun, wählen Sie "Eigenschaftenfenster anzeigen>" aus, oder drücken Sie F4. Wählen Sie im Eigenschaftenfenster die folgenden Felder aus, um :true
- Assembly in VSIX-Container einschließen
- Debugsymbole in die lokale VSIX-Bereitstellung einschließen
- Debugsymbole in VSIX-Container einschließen
Fügen Sie die Assembly als Ressource zum VSIX-Projekt hinzu. Öffnen Sie die Datei "source.extension.vsixmanifest", und wählen Sie die Registerkarte "Objekte" aus. Wählen Sie im Fenster "Neue Ressource hinzufügen" für "Typ" "Microsoft.VisualStudio.Assembly" für "Quelle" in der aktuellen Projektmappe ein Projekt und für Project"MyProjectWizard" aus.
Fügen Sie die folgenden Verweise auf das VSIX-Projekt hinzu. (In Projektmappen-Explorer wählen Sie unter dem VSIX-Projektknoten Verweise aus, klicken Sie mit der rechten Maustaste, und wählen Sie "Verweis hinzufügen" aus.) Suchen Sie im Dialogfeld "Verweis hinzufügen" auf der Registerkarte "Framework" die Assembly "System.Windows Forms", und wählen Sie sie aus. Suchen Und wählen Sie auch die Assemblys "System" und "System.Drawing" aus. Wählen Sie nun die Registerkarte "Erweiterungen " aus. Suchen Sie die EnvDTE-Assembly , und wählen Sie sie aus. Suchen Sie auch die Assembly "Microsoft.VisualStudio.TemplateWizardInterface" , und wählen Sie sie aus. Klicken Sie auf OK.
Fügen Sie dem VSIX-Projekt eine Klasse für die Assistentenimplementierung hinzu. (In Projektmappen-Explorer klicken Sie mit der rechten Maustaste auf den VSIX-Projektknoten, und wählen Sie "Hinzufügen" und dann "Neues Element" und dann "Klasse" aus.) Nennen Sie die Klasse WizardImplementation.

Ersetzen Sie den Code in der Datei "WizardImplementationClass.cs " durch den folgenden Code:

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

Das userInputForm , auf das in diesem Code verwiesen wird, wird später implementiert.

Die WizardImplementation-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 eine Reihe 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.

Erstellen Sie jetzt userInputForm. Fügen Sie in der Datei "WizardImplementation.cs " den folgenden Code nach dem Ende der WizardImplementation Klasse hinzu.

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

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.

Verbinden des Assistenten zur benutzerdefinierten Vorlage

Damit Ihre benutzerdefinierte Projektvorlage Ihren benutzerdefinierten Assistenten verwenden kann, müssen Sie die Assistentenassembly signieren und Ihrer benutzerdefinierten Projektvorlage einige Zeilen hinzufügen, um sie darüber zu informieren, wo die Assistentenimplementierung beim Erstellen eines neuen Projekts zu finden ist.

Signieren Sie die Assembly. Wählen Sie im Projektmappen-Explorer das VSIX-Projekt aus, klicken Sie mit der rechten Maustaste, und wählen Sie "Projekteigenschaften" aus.
Wählen Sie im Fenster "Projekteigenschaften" die Registerkarte "Signieren" aus. Aktivieren Sie auf der Registerkarte "Signieren" die Assembly. Wählen Sie im Feld "Schlüsseldatei mit starkem Namen" die Option "Neu"> aus<. Geben Sie im Fenster "Schlüsselschlüssel erstellen" im Feld "Schlüsseldateiname " den Namen "key.snk" ein. Deaktivieren Sie das Kontrollkästchen "Meine Schlüsseldatei schützen" mit einem Kennwortfeld .
Wählen Sie im Projektmappen-Explorer das VSIX-Projekt aus, und suchen Sie das Fenster "Eigenschaften".
Legen Sie die Ausgabe des Kopierbuilds auf das Ausgabeverzeichnisfeld auf "true" fest. Dadurch kann die Assembly in das Ausgabeverzeichnis kopiert werden, wenn die Lösung neu erstellt wird. Sie ist weiterhin in der .vsix Datei enthalten. Sie müssen die Assembly anzeigen, um den Signaturschlüssel zu ermitteln.
Erstellen Sie die Lösung neu.
Sie finden nun die Datei "key.snk" im Projektverzeichnis "MyProjectWizard" (<Ihrem Datenträgerspeicherort>\MyProjectTemplate\MyProjectWizard\key.snk). Kopieren Sie die Datei "key.snk ".
Wechseln Sie zum Ausgabeverzeichnis, und suchen Sie die Assembly (<Speicherort des Datenträgers>\MyProjectTemplate/MyProjectWizard\bin\Debug\MyProjectWizard.dll). Fügen Sie die Datei "key.snk " hier ein. (Dies ist nicht unbedingt erforderlich, aber es erleichtert die folgenden Schritte.)
Öffnen Sie ein Befehlsfenster, und ändern Sie es in das Verzeichnis, in dem die Assembly erstellt wurde.
Suchen Sie das sn.exe Signiertool. Bei einem Windows 10 64-Bit-Betriebssystem würde beispielsweise ein typischer Pfad wie folgt aussehen:

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

Wenn Sie das Tool nicht finden können, versuchen Sie, in dem /R . sn.exe im Befehlsfenster auszuführen. Notieren Sie sich den Pfad.
Extrahieren Sie den öffentlichen Schlüssel aus der Datei "key.snk ". Geben Sie im Befehlsfenster

<Speicherort von sn.exe>\sn.exe -p key.snk outfile.key.

Vergessen Sie nicht, den Pfad von sn.exe mit Anführungszeichen einzuschließen, wenn Leerzeichen in den Verzeichnisnamen vorhanden sind!
Rufen Sie das öffentliche Schlüsseltoken aus der Outfile-Datei ab:

<Speicherort von sn.exe>\sn.exe -t outfile.key.

Vergessen Sie auch hier nicht die Anführungszeichen. In der Ausgabe sollte wie folgt eine Zeile angezeigt werden.

Öffentliches Schlüsseltoken ist <Token>

Notieren Sie sich diesen Wert.
Fügen Sie den Verweis auf den benutzerdefinierten Assistenten zur VSTEMPLATE-Datei der Projektvorlage hinzu. Suchen Sie in der Projektmappen-Explorer die Datei "MyProjectTemplate.vstemplate", und öffnen Sie sie. Fügen Sie nach dem Ende des <TemplateContent-Abschnitts> den folgenden Abschnitt hinzu:
```
<WizardExtension>
    <Assembly>MyProjectWizard, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=token</Assembly>
    <FullClassName>MyProjectWizard.WizardImplementation</FullClassName>
</WizardExtension>
```
Dabei ist MyProjectWizard der Name der Assembly, und das Token ist das Token , das Sie im vorherigen Schritt kopiert haben.
Speichern Sie alle Dateien im Projekt, und erstellen Sie sie neu.

Hinzufügen des benutzerdefinierten Parameters zur Vorlage

In diesem Beispiel zeigt das als Vorlage verwendete Projekt die im Benutzereingabeformular des benutzerdefinierten Assistenten angegebene Meldung an.

Wechseln Sie im Projektmappen-Explorer zum MyProjectTemplate-Projekt, und öffnen Sie "Class1.cs".
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.

Dies ist die vollständige Codedatei, bevor sie in eine Vorlage exportiert wurde.

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$");
          }
    }
}

Verwenden des benutzerdefinierten Assistenten

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

Erstellen Sie die Lösung neu, und starten Sie das Debuggen. Eine zweite Instanz von Visual Studio sollte angezeigt werden.
Erstellen Sie ein neues MyProjectTemplate-Projekt. (Datei>neues>Projekt).
Suchen Sie im Dialogfeld "Neues Projekt " nach "myproject", um Ihre Vorlage zu suchen, 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 in Projektmappen-Explorer mit der rechten Maustaste auf die Quellcodedatei, und klicken Sie dann auf "Code anzeigen".

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