Freigeben über

Anleitung: Erstellen einer Elementvorlage

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

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

Tipp

Elementvorlagen werden im Dialogfeld"Neues Element>" von Visual Studio nicht angezeigt.

In diesem Teil der Serie erfahren Sie, wie Sie:

  • Erstellen Sie eine Klasse für eine Elementvorlage.
  • Erstellen Sie den Vorlagenkonfigurationsordner und die Datei.
  • Installieren Sie eine Vorlage aus einem Dateipfad.
  • Testen Sie eine Elementvorlage.
  • Deinstallieren Sie eine Elementvorlage.

Voraussetzungen

  • .NET 9 oder eine höhere Version.

  • Der Referenzartikel erklärt die Grundlagen von Vorlagen und deren Zusammenstellung. Einige dieser Informationen werden hier wiederholt.

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

Erstellen der erforderlichen Ordner

Diese Reihe verwendet einen "Arbeitsordner", in dem ihre Vorlagenquelle enthalten ist, und einen "Testordner", der zum Testen Ihrer Vorlagen verwendet wird. Der Arbeitsordner und der Testordner sollten sich unter demselben übergeordneten Ordner befinden.

Zuerst erstellen Sie einen übergeordneten Ordner; der Name spielt dabei keine Rolle. Erstellen Sie dann zwei Unterordner mit dem Namen "Arbeiten und Testen". Erstellen Sie innerhalb des Arbeitsordners einen Unterordner mit dem Namen "Inhalt".

Die Ordnerstruktur sollte wie folgt aussehen.

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

Erstellen einer Elementvorlage

Eine Elementvorlage ist ein bestimmter Vorlagentyp, der mindestens eine Datei 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 Konfigurationsdatei oder Codedatei. In diesem Beispiel erstellen Sie eine Klasse, 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 "Erweiterungen".

working
└───content
    └───extensions

Navigieren Sie zum Ordner "Erweiterungen ", und erstellen Sie eine neue Datei mit dem Namen StringExtensions.cs. Öffnen Sie die Datei in einem Text-Editor. Diese Klasse stellt eine Erweiterungsmethode bereit Reverse , 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 fertig ist, erstellen Sie die Vorlagenkonfiguration.

Erstellen Sie die Vorlagenkonfiguration

In diesem Teil des Lernprogramms 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 im Stammverzeichnis Des Vorlagenordners vorhanden ist.

Erstellen Sie zunächst einen neuen Unterordner mit dem Namen .template.config, und geben Sie ihn ein. Erstellen Sie dann eine neue Datei mit dem Namen template.json. Die Ordnerstruktur sollte wie folgt aussehen:

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

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

{
    "$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. Sie können die grundlegenden Einstellungen sehen, wie name und shortName, aber es gibt auch einen tags/type-Wert, der auf item gesetzt ist. Dadurch wird Ihre Vorlage als "Element"-Vorlage kategorisiert. Es gibt keine Einschränkung beim Typ der Vorlage, die Sie erstellen. Die item und project Werte sind allgemeine Namen, die .NET empfiehlt, damit Benutzer den Typ der Vorlage, nach der sie suchen, problemlos filtern können.

Das classifications Element stellt die Tags-Spalte dar, die Sie sehen, wenn Sie dotnet new ausführen und eine Liste mit Vorlagen erhalten. Benutzer können auch basierend auf Klassifizierungstags suchen. Verwechseln Sie die tags Eigenschaft in der template.json Datei nicht mit der classifications Tagsliste. Es handelt sich um zwei verschiedene Konzepte, die leider gleich genannt werden. Das vollständige Schema für die template.json-Datei finden Sie im JSON Schema Store und wird unter Reference for template.jsonbeschrieben. Weitere Informationen zur template.json-Datei finden Sie im Dotnet-Vorlagenwiki.

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 und muss auf parameter konfiguriert werden.
  • description - Die Beschreibung des Parameters, der in der Vorlagenhilfe gedruckt wird.
  • datatype - Der Typ der Daten 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 dies 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, und dieser Wert ersetzt alle Vorkommen von StringExtensions. Wenn kein Wert angegeben wird, wird der defaultValue Wert verwendet. Für diese Vorlage gibt es zwei Vorkommen von StringExtensions: der Datei StringExtensions.cs und der Klasse StringExtensions. Da der defaultValue Parameter lautet StringExtensions, bleiben der Dateiname und der Klassenname unverändert, wenn der Parameter bei Verwendung der Vorlage nicht angegeben wird. Wenn beispielsweise dotnet new stringext -ClassName MyExtsein Wert angegeben wird, wird die Datei MyExts.cs umbenannt, und die Klasse wird in MyExts umbenannt.

Um zu sehen, welche Parameter für eine Vorlage verfügbar sind, verwenden Sie den -? Parameter mit dem Vorlagennamen:

dotnet new stringext -?

Dies erzeugt die folgende Ausgabe:

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 .template.config/template.json Datei verfügen, kann Ihre Vorlage installiert werden. Navigieren Sie in Ihrem Terminal zum Ordner "Erweiterungen ", und führen Sie den folgenden Befehl aus, um die Vorlage im aktuellen Ordner zu installieren:

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

Mit diesem Befehl wird die Liste der installierten Vorlagen ausgegeben, die Ihre enthalten sollten.

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

Nachdem Sie nun eine Elementvorlage installiert haben, testen Sie sie.

  1. Navigieren Sie zum Testordner .

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

    dotnet new console

    Sie erhalten eine Ausgabe, die der folgenden ähnlich ist.

    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 mit dem folgenden Befehl aus.

    dotnet run

    Sie erhalten die folgende Ausgabe.

    Hello, World!

  4. Führen Sie den Befehl aus dotnet new stringext , um die StringExtensions.cs Datei 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 "Hello, World!" Zeichenfolge mit der von der Vorlage bereitgestellten Erweiterungsmethode umzukehren.

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

    Führen Sie das Programm erneut aus, und sehen Sie, dass das Ergebnis umgekehrt ist.

    dotnet run

    Sie erhalten die folgende Ausgabe.

    !dlroW ,olleH

Glückwunsch! Sie haben eine Elementvorlage mit .NET erstellt und bereitgestellt. Deinstallieren Sie in Vorbereitung auf den nächsten Teil dieser Lernprogrammreihe die von Ihnen erstellte Vorlage. Löschen Sie auch alle Dateien und Ordner im Testordner . Dies bringt Sie zurück in einen sauberen Zustand, sodass Sie bereit sind für den nächsten Teil dieser Tutorial-Serie.

Deinstallieren der Vorlage

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

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

Dieser Befehl gibt eine Liste der Vorlagen aus, die deinstalliert wurden und Ihre Vorlage enthalten sollten.

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

Zu jeder Zeit können Sie mit dotnet new uninstall eine Liste der installierten Vorlagenpakete aufrufen, einschließlich des jeweiligen Befehls zum Deinstallieren jedes Vorlagenpakets.

Nächste Schritte

In dieser Anleitung haben Sie eine Elementvorlage erstellt. Um zu erfahren, wie Sie eine Projektvorlage erstellen, fahren Sie mit dieser Lernprogrammreihe fort.

Erstellen einer Projektvorlage

  • Last updated on