Tutorial: Erstellen einer Elementvorlage

  • Artikel

Mit .NET können Sie Vorlagen erstellen und bereitstellen, die Projekte, Dateien und Ressourcen generieren. Dieses Tutorial ist der erste Teil einer Reihe, in der Sie erfahren, wie Sie Vorlagen für die Verwendung mit dem Befehl dotnet new erstellen, installieren und deinstallieren.

Sie können die fertige Vorlage im GitHub-Repository mit .NET-Beispielen anzeigen.

Tipp

Elementvorlagen werden im Dialogfeld Hinzufügen>Neues Element von Visual Studio nicht angezeigt.

In diesem Teil der Reihe wird Folgendes vermittelt:

  • Erstellen Sie eine Klasse für eine Elementvorlage.
  • Erstellen Sie den Konfigurationsordner und die Konfigurationsdatei der Vorlage.
  • Installieren Sie eine Vorlage unter Verwendung eines Dateipfads.
  • Testen Sie eine Elementvorlage.
  • Deinstallieren Sie eine Elementvorlage.

Voraussetzungen

  • .NET SDK 7.0.100 oder höhere Versionen.

    Der Referenzartikel enthält grundlegende Informationen zu Vorlagen und zu deren Erstellung. Einige dieser Informationen werden hier wiederholt.

  • Öffnen Sie ein Terminal, und navigieren Sie zu einem Ordner, in dem Sie die Vorlagen speichern und testen werden.

Wichtig

Dieser Artikel wurde für .NET 7 geschrieben. Er gilt jedoch auch für .NET 6 und frühere Versionen, mit einem Unterschied: Die dotnet new-Syntax ist anders. Die Unterbefehle list, search, install und uninstall sollten jeweils die Optionen --list, --search, --install und --uninstall sein.

Der Befehl dotnet new install in .NET 7 wird z. B. zu dotnet new --install in .NET 6. Verwenden Sie den Befehl dotnet new --help, um eine Liste aller Optionen und Unterbefehle anzuzeigen.

Erstellen der erforderlichen Ordner

In dieser Reihe werden ein Arbeitsordner als Vorlagenquelle und ein Testordner zum Testen Ihrer Vorlagen verwendet. Der Arbeitsordner und der Testordner müssen sich im gleichen übergeordneten Ordner befinden.

Erstellen Sie zunächst den übergeordneten Ordner. Er kann einen beliebigen Namen haben. Erstellen Sie dann zwei Unterordner mit dem Namen working und test. Erstellen Sie im Ordner working einen Unterordner mit dem Namen content.

Die Ordnerstruktur sollte wie folgt aussehen.

parent_folder
├───test
└───working
    └───content

Erstellen einer Elementvorlage

Eine Elementvorlage ist eine spezielle Art von Vorlage, die eine oder mehrere Dateien enthält. Diese Vorlagentypen sind nützlich, wenn Sie bereits über ein Projekt verfügen und eine andere Datei generieren möchten, z. B. eine Konfigurations- oder Codedatei. In diesem Beispiel wird eine Klasse erstellt, die dem Zeichenfolgentyp eine Erweiterungsmethode hinzufügt.

Navigieren Sie in Ihrem Terminal zum Ordner working\content, und erstellen Sie einen neuen Unterordner mit dem Namen extensions.

working
└───content
    └───extensions

Navigieren Sie zum Ordner extensions und erstellen Sie eine neue Datei namens StringExtensions.cs. Öffnen Sie die -Datei in einem Text-Editor. Diese Klasse stellt eine Erweiterungsmethode namens Reverse bereit, die den Inhalt einer Zeichenfolge umkehrt. Fügen Sie den folgenden Code ein, und speichern Sie die Datei:

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

Nachdem der Inhalt der Vorlage fertiggestellt worden ist, besteht der nächste Schritt nun darin, die Vorlagenkonfiguration zu erstellen.

Erstellen der Vorlagenkonfiguration

In diesem Teil des Tutorials befindet sich Ihr Vorlagenordner unter working\content\extensions.

Vorlagen werden von .NET erkannt, da sie über einen speziellen Ordner und eine Konfigurationsdatei verfügen, die sich im Stammverzeichnis Ihres Vorlagenordners befindet.

Erstellen Sie zunächst einen neuen Unterordner namens .template.config, und öffnen Sie ihn. Erstellen Sie anschließend eine neue Datei namens template.json. Ihre Ordnerstruktur sollte wie folgt aussehen:

working
└───content
    └───extensions
        └───.template.config
                template.json

Öffnen Sie die Datei template.json mit Ihrem bevorzugten Text-Editor, fügen Sie den folgenden JSON-Code ein, und speichern Sie die Datei.

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Me",
    "classifications": [ "Common", "Code" ],
    "identity": "ExampleTemplate.StringExtensions",
    "name": "Example templates: string extensions",
    "shortName": "stringext",
    "tags": {
      "language": "C#",
      "type": "item"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

Diese Konfigurationsdatei enthält alle Einstellungen für Ihre Vorlage. Neben Grundeinstellungen wie name und shortName enthält die Datei auch einen auf item festgelegten Wert vom Typ tags/type. Dadurch wird die Vorlage als „Elementvorlage“ kategorisiert. Sie können eine beliebige Art von Vorlage erstellen. Die Werte item und project sind allgemeine Namen, die von .NET empfohlen werden, damit Benutzer problemlos nach der gesuchten Vorlagenart filtern können.

Das Element classifications stellt die Spalte Tags dar, die angezeigt wird, wenn Sie dotnet new ausführen und eine Vorlagenliste abrufen. Benutzer können auch anhand von Klassifizierungstags suchen. Die Eigenschaft tags in der JSON-Vorlage-Datei darf nicht mit der classifications-Tagliste verwechselt werden. Es handelt sich um zwei verschiedene Konzepte, die leider gleich benannt wurden. Das vollständige Schema für die JSON-Vorlage-Datei befindet sich im JSON-Schemaspeicher und wird unter Referenz für JSON-Vorlage beschrieben. Weitere Informationen zur Datei template.json finden Sie im Wiki zur Erstellung von .NET-Vorlagen.

Der symbols-Teil dieses JSON-Objekts wird verwendet, um die Parameter zu definieren, die in der Vorlage verwendet werden können. In diesem Fall ist ein Parameter definiert: ClassName. Der definierte Parameter enthält die folgenden Einstellungen:

  • type: Dies ist eine obligatorische Einstellung, die auf parameter festgelegt werden muss.
  • description: Die Beschreibung des Parameters, der in der Vorlagenhilfe ausgegeben wird.
  • datatype: Der Datentyp des Parameterwerts, wenn der Parameter verwendet wird.
  • replaces: Gibt einen Textwert an, der in allen Vorlagendateien durch den Wert des Parameters ersetzt werden soll.
  • fileRename: Ähnlich wie replaces gibt diese Einstellung einen Textwert an, der in den Namen aller Vorlagendateien durch den Wert des Parameters ersetzt wird.
  • defaultValue: Der Standardwert dieses Parameters, wenn der Parameter nicht vom Benutzer angegeben wird.

Wenn die Vorlage verwendet wird, kann der Benutzer einen Wert für den ClassName-Parameter angeben. Dieser Wert ersetzt alle Vorkommen von StringExtensions. Wenn kein Wert angegeben wird, wird defaultValue verwendet. In dieser Vorlage tritt StringExtensions zweimal auf: in der Datei StringExtensions.cs und in der Klasse StringExtensions. Da der defaultValue des Parameters StringExtensions lautet, bleiben der Dateiname und der Klassenname unverändert, wenn der Parameter bei Verwendung der Vorlage nicht angegeben wird. Wenn beispielsweise der Wert dotnet new stringext -ClassName MyExts wird, wird die Datei in MyExts.cs und die Klasse in MyExts umbenannt.

Verwenden Sie den -?-Parameter mit dem Vorlagennamen, um anzuzeigen, welche Parameter für eine Vorlage verfügbar sind:

dotnet new stringext -?

Die folgende Ausgabe wird erzeugt:

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

Nachdem Sie nun über eine gültige Datei vom Typ .template.config/template.json verfügen, ist die Vorlage installationsbereit. Navigieren Sie in Ihrem Terminal zum Ordner extensions, und führen Sie den folgenden Befehl aus, um die Vorlage aus dem aktuellen Ordner zu installieren:

  • Unter Windows:dotnet new install .\
  • Unter Linux oder macOS:dotnet new install ./

Dieser Befehl gibt eine Liste mit den installierten Vorlagen aus. Darin sollte nun auch Ihre Vorlage enthalten sein.

The following template packages will be installed:
   <root path>\working\content\extensions

Success: <root path>\working\content\extensions installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code

Testen der Elementvorlage

Testen Sie als Nächstes Ihre installierte Elementvorlage.

  1. Navigieren Sie zum Ordner test.

  2. Erstellen Sie mit dotnet new console eine neue Konsolenanwendung, die ein funktionierendes Projekt generiert, das Sie mit dem -Befehl dotnet run problemlos testen können.

    dotnet new console

    Sie erhalten eine Ausgabe ähnlich der folgenden.

    The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on C:\test\test.csproj...
  Restore completed in 54.82 ms for C:\test\test.csproj.

Restore succeeded.

  3. Führen Sie das Projekt mithilfe des folgenden Befehls aus.

    dotnet run

    Sie erhalten die folgende Ausgabe.

    Hello, World!

  4. Führen Sie dotnet new stringext aus, um die Datei StringExtensions.cs aus der Vorlage zu generieren.

    dotnet new stringext

    Sie erhalten die folgende Ausgabe.

    The template "Example templates: string extensions" was created successfully.

  5. Ändern Sie den Code in Program.cs, um die Zeichenfolge "Hello, World!" mit der von der Vorlage bereitgestellten Erweiterungsmethode umzukehren.

    Console.WriteLine("Hello, World!".Reverse());

    Führen Sie das Programm erneut aus. Sie können erkennen, dass das Ergebnis nun umgekehrt ist.

    dotnet run

    Sie erhalten die folgende Ausgabe.

    !dlroW ,olleH

Herzlichen Glückwunsch! Sie haben eine Elementvorlage mit .NET erstellt und bereitgestellt. Zur Vorbereitung auf den nächsten Teil der Tutorialreihe muss die von Ihnen erstellte Vorlage deinstalliert werden. Löschen Sie außerdem auch alle Dateien und Ordner im Ordner test. Dadurch erhalten Sie wieder einen bereinigten Grundzustand, mit dem Sie bereit für den nächsten Teil dieser Tutorialreihe sind.

Deinstallieren der Vorlage

Navigieren Sie in Ihrem Terminal zum Ordner extensions, und führen Sie den folgenden Befehl aus, um die Vorlagen im aktuellen Ordner zu deinstallieren:

  • Unter Windows:dotnet new uninstall .\
  • Unter Linux oder macOS:dotnet new uninstall ./

Dieser Befehl gibt eine Liste der Vorlagen aus, die deinstalliert wurden. Ihre Vorlage sollte in dieser Liste enthalten sein.

Success: <root path>\working\content\extensions was uninstalled.

Sie können jederzeit dotnet new uninstall verwenden, um eine Liste der installierten Vorlagenpakete anzuzeigen, einschließlich des Befehls zum Deinstallieren jedes Vorlagenpakets.

Nächste Schritte

In diesem Tutorial haben Sie eine Elementvorlage erstellt. Im nächsten Teil dieser Tutorialreihe erfahren Sie, wie Sie eine Projektvorlage erstellen.

Tutorial: Erstellen einer Projektvorlage