Benutzerdefinierte Vorlagen für dotnet new

  • Artikel

Das .NET SDK enthält viele Vorlagen, die sofort einsatzbereit sind. Der Befehl dotnet new bietet nicht nur eine Möglichkeit, eine Vorlage zu verwenden, sondern auch, um Vorlagen zu installieren und zu deinstallieren. Sie können Ihre eigenen benutzerdefinierten Vorlagen für jeden Projekttyp (App, Dienst, Tool, Klassenbibliothek usw.) erstellen. Sie könne sogar eine Vorlage erstellen, die mindestens eine unabhängige Datei ausgibt, wie z.B. eine Konfigurationsdatei.

Sie können benutzerdefinierte Vorlagen aus NuGet-Paketen in jedem NuGet-Feed installieren, indem Sie direkt auf eine NuGet-Datei des Typs .nupkg verweisen, oder indem Sie ein Dateisystemverzeichnis angeben, das die Vorlage enthält. Das Vorlagenmodul bietet Features, mit denen Sie Werte ersetzen, Dateien ein- oder ausschließen und benutzerdefinierte Verarbeitungsvorgänge ausführen können, wenn Ihre Vorlage verwendet wird.

Die Vorlagen-Engine ist Open Source, und das Onlinecoderepository befindet sich unter dotnet/templating auf GitHub. Unter dotnet new search finden Sie weitere Vorlagen, einschließlich Vorlagen von Drittanbietern. Weitere Informationen zum Erstellen und Verwenden von benutzerdefinierten Vorlagen finden Sie unter How to create your own templates for dotnet new (Erstellen Ihrer eigenen Vorlage für dotnet new) und im GitHub-Repositorywiki dotnet/templating.

Hinweis

Vorlagenbeispiele finden Sie im dotnet/templating-GitHub-Repository.

Eine exemplarische Vorgehensweise zum Erstellen einer Vorlage finden Sie im Tutorial Create a custom template for dotnet new (in englischer Sprache).

.NET-Standardvorlagen

Wenn Sie das .NET SDK installieren, erhalten Sie mehr als zwölf integrierte Vorlagen zum Erstellen von Projekten und Dateien, einschließlich Konsolenanwendungen, Klassenbibliotheken, Komponententestprojekten, ASP.NET Core-Apps (einschließlich Angular- und React-Projekten) und Konfigurationsdateien. Führen Sie den Befehl dotnet new list aus, um die integrierten Vorlagen aufzulisten:

dotnet new list

Konfiguration

Eine Vorlage besteht aus den folgenden Teilen:

  • Quelldateien und -ordner
  • Konfigurationsdatei (template.json)

Quelldateien und -ordner

Die Quelldateien und -ordner enthalten die Dateien und Ordner, von denen Sie möchten, dass sie vom Vorlagenmodul verwendet werden, wenn der dotnet new <TEMPLATE>-Befehl ausgeführt wird. Die Vorlagen-Engine wurde so entwickelt, dass sie ausführbare Projekte als Quellcode verwendet, um Projekte zu erzeugen. Dies hat mehrere Vorteile:

  • Sie müssen für die Vorlagen-Engine keine besonderen Token in den Quellcode Ihres Projekts einfügen.
  • Die Codedateien sind keine besonderen Dateien. Sie werden auch nicht modifiziert, um mit der Vorlagen-Engine zu funktionieren. Die Tools, die Sie normalerweise mit Projekten verwenden, funktionieren auch mit Vorlageninhalt.
  • Das Erstellen, Ausführen und Debuggen Ihrer Projekte erfolgt wie bei Ihren anderen Projekten.
  • Sie können eine Vorlage schnell anhand eines vorhandenen Projekts erstellen, indem Sie einfach die Konfigurationsdatei ./.template.config/template.json dem Projekt hinzufügen.

In der Vorlage gespeicherte Dateien und Ordner sind nicht auf formelle .NET-Projekttypen beschränkt. Quelldateien und -ordner können aus jedem beliebigen Inhalt bestehen, den Sie erstellen möchten, wenn die Vorlage verwendet wird, auch wenn das Vorlagenmodul nur eine Datei ausgibt.

Dateien, die anhand der Vorlage generiert werden, können basierend auf der Logik und den Einstellungen, die Sie in der Konfigurationsdatei template.json angegeben haben, geändert werden. Der Benutzer kann diese Einstellungen überschreiben, indem er Optionen an den Befehl dotnet new <TEMPLATE> übergibt. Ein häufiges Beispiel für benutzerdefinierte Logik ist die Bereitstellung eines Namens für eine Klasse oder Variable in der Codedatei, die von einer Vorlage bereitgestellt wird.

template.json

Die Datei template.json wird in den Ordner template.config im Stammverzeichnis der Vorlage platziert. Die Datei bietet der Vorlagen-Engine Konfigurationsinformationen. Die Mindestkonfiguration erfordert die in der folgenden Tabelle aufgelisteten Member, was zum Erstellen einer funktionsfähigen Vorlage ausreicht.

Member Typ Beschreibung
$schema URI Das JSON-Schema für die Datei template.json. Editor, die JSON-Schemas unterstützen, ermöglichen Features zum Bearbeiten von JSON-Dateien, wenn das Schema angegeben ist. Visual Studio-Code erfordert z.B., dass dieser Member IntelliSense aktiviert. Verwenden Sie den Wert http://json.schemastore.org/template.
author string Der Autor der Vorlage.
classifications array(string) Null (0) oder mehr Merkmale der Vorlage, die ein Benutzer verwenden kann, um die Vorlage zu finden. Die Klassifizierungen werden auch in der Spalte Tags angezeigt, wenn diese in einer Liste von Vorlagen angezeigt wird, die mit dem dotnet new list-Befehl erzeugt wurden.
identity string Ein eindeutiger Namen für diese Vorlage
name string Der Name der Vorlage, der Benutzern angezeigt wird
shortName string Ein Standardkurzname zum Auswählen der Vorlage, die für Umgebungen gilt, in denen der Vorlagenname vom Benutzer angegeben wird und nicht über eine grafische Benutzeroberfläche. Die Kurzform kann z.B. nützlich sein, wenn Sie Vorlagen aus einer Eingabeaufforderung mit CLI-Befehlen verwenden.
sourceName Zeichenfolge Der Name in der Quellstruktur, der durch den vom Benutzer festgelegten Namen ersetzt werden soll. Die Vorlagen-Engine sucht nach den Instanzen von sourceName in der Konfigurationsdatei und ersetzt diese in Dateinamen und Dateiinhalten. Der Wert, der ersetzt werden soll, kann mithilfe der Optionen -n oder --name beim Ausführen einer Vorlage angegeben werden. Wird kein Name angegeben, wird das aktuelle Verzeichnis verwendet.
preferNameDirectory Boolean Hiermit wird angegeben, ob ein Verzeichnis für die Vorlage erstellt werden soll, wenn der Name angegeben, aber kein Ausgabeverzeichnis festgelegt ist (anstatt den Inhalt direkt im aktuellen Verzeichnis zu erstellen). Der Standardwert ist „FALSE“.

Das vollständige Schema für die Datei template.json finden Sie im JSON-Schemaspeicher. Weitere Informationen zur Datei template.json finden Sie im Wiki zur Erstellung von .NET-Vorlagen. Ausführlichere Beispiele und Informationen dazu, wie Sie Ihre Vorlagen in Visual Studio sichtbar machen, finden Sie in den von Sayed Hashimi erstellten Ressourcen.

Beispiel

Dies ist beispielsweise ein Vorlagenordner, der zwei Inhaltsdateien enthält: console.cs und readme.txt. Zudem ist der erforderliche Ordner namens .template.config enthalten, der die Datei template.json enthält.

└───mytemplate
    │   console.cs
    │   readme.txt
    │
    └───.template.config
            template.json

Die Datei template.json sieht wie folgt aus:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Travis Chau",
  "classifications": [ "Common", "Console" ],
  "identity": "AdatumCorporation.ConsoleTemplate.CSharp",
  "name": "Adatum Corporation Console Application",
  "shortName": "adatumconsole"
}

Der Ordner mytemplate ist ein installierbares Vorlagenpaket. Sobald das Paket installiert ist, kann shortName mit dem Befehl dotnet new verwendet werden. Beispielsweise würde dotnet new adatumconsole die Dateien console.cs und readme.txt im aktuellen Ordner ausgeben.

Vorlagenlokalisierung

Die .NET-Vorlagen können lokalisiert werden. Wenn eine Vorlage für die Sprache lokalisiert ist, die dem aktuellen Gebietsschema entspricht, werden die Elemente in derselben Sprache wie die CLI angezeigt. Die Lokalisierung ist beim Erstellen neuer Vorlagen optional.

Dies sind die lokalisierbaren Elemente einer Vorlage:

  • Name
  • Autor
  • Beschreibung
  • Symbole
    • Beschreibung
    • Anzeigename
    • Beschreibungen und Anzeigename von Optionen für Auswahlparameter
  • Nachfolgende Aktionen
    • Beschreibung
    • Manuelle Anweisungen

Lokalisierungsdateien weisen das JSON-Format auf, und es sollte nur eine Datei pro Sprachkultur vorhanden sein. Die Namenskonvention lautet templatestrings.<lang code>.json, wobei lang code einer der CultureInfo-Optionen entspricht. Alle Lokalisierungsdateien sollten sich innerhalb des .template-config\localize-Ordners befinden.

Die JSON-Lokalisierungsdatei besteht aus Schlüsselwertpaaren:

  • Der Schlüssel ist der Verweis auf ein zu lokalisierendes Element von template.json. Wenn das Element ein untergeordnetes Element ist, verwenden Sie den vollständigen Pfad mit einem /-Trennzeichen.
  • Der Wert ist die Lokalisierungszeichenfolge des Elements, das vom Schlüssel angegeben wird.

Weitere Informationen zum Lokalisieren von Vorlagen finden Sie auf der Lokalisierungsseite des dotnet-Wikis für die Vorlagenerstellung.

Beispiel

Dies ist beispielsweise eine template.json-Datei mit einigen lokalisierbaren Feldern:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Microsoft",
  "classifications": "Config",
  "name": "EditorConfig file",
  "description": "Creates an .editorconfig file for configuring code style preferences.",
  "symbols": {
    "Empty": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "displayName": "Empty",
      "description": "Creates empty .editorconfig instead of the defaults for .NET."
    }
  }
}

Einige Felder sollen in brasilianisches Portugiesisch lokalisiert werden. Der Dateiname lautet templatestrings.pt-BR.json, um mit der Sprachkultur übereinzustimmen, und sieht wie folgt aus:

{
  "author": "Microsoft",
  "name": "Arquivo EditorConfig",
  "description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.",
  "symbols/Empty/displayName": "Vazio",
  "symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET."
}

Packen einer Vorlage in ein NuGet-Paket (nupkg-Datei)

Eine benutzerdefinierte Vorlage wird mit dem Befehl dotnet pack und CSPROJ-Datei gepackt. Alternativ kann NuGet mit dem Befehl nuget pack zusammen mit einer NUSPEC-Datei verwendet werden. NuGet setzt jedoch .NET Framework unter Windows und Mono unter Linux und macOS voraus.

Die CSPROJ-Datei unterscheidet sich geringfügig von einer herkömmlichen Codeprojektdatei des Typs .csproj. Beachten Sie die folgenden Einstellungen:

  1. Die Einstellung <PackageType> wird hinzugefügt und auf Template festgelegt.
  2. Die Einstellung <PackageVersion> wird hinzugefügt und auf eine gültige NuGet-Versionsnummer festgelegt.
  3. Die Einstellung <PackageId> wird hinzugefügt und auf einen eindeutigen Bezeichner festgelegt. Dieser Bezeichner dient zur Deinstallation des Vorlagenpakets und wird von NuGet-Feeds verwendet, um Ihr Vorlagenpaket zu registrieren.
  4. Allgemeine Metadateneinstellungen müssen festgelegt werden: <Title>, <Authors>, <Description> und <PackageTags>.
  5. Die Einstellung <TargetFramework> muss festgelegt werden, auch wenn die vom Vorlagenprozess generierte Binärdatei nicht verwendet wird. Im folgenden Beispiel wird sie auf netstandard2.0 festgelegt.

Ein Vorlagenpaket in Form eines NuGet-Paket des Typs .nupkg. erfordert, dass alle Vorlagen im Paket im Ordner content gespeichert werden. Es gibt noch einige weitere Einstellungen, die einer CSPROJ-Datei hinzugefügt werden müssen, um sicherzustellen, dass die generierte NUPKG-Datei als Vorlagenpaket installiert werden kann:

  1. Die Einstellung <IncludeContentInPack> wird auf true festgelegt, um jede Datei, die das Projekt als Inhalt einstuft, in das NuGet-Paket aufzunehmen.
  2. Die Einstellung <IncludeBuildOutput> wird auf false festgelegt, um alle vom Compiler erzeugten Binärdateien aus dem NuGet-Paket auszuschließen.
  3. Die Einstellung <ContentTargetFolders> wird auf content festgelegt. Dadurch wird sichergestellt, dass die als Inhalt festgelegten Dateien im Ordner content im NuGet-Paket gespeichert werden. Dieser Ordner im NuGet-Paket wird vom .NET-Vorlagensystem analysiert.

Eine einfache Möglichkeit, alle Codedateien von der Kompilierung durch Ihr Vorlagenprojekt auszuschließen, besteht darin, das Element <Compile Remove="**\*" /> in Ihrer Projektdatei innerhalb eines Elements des Typs <ItemGroup> zu verwenden.

Eine einfache Möglichkeit, Ihr Vorlagenpaket zu strukturieren, besteht darin, alle Vorlagen in einzelnen Ordnern und dann jeden Vorlagenordner innerhalb eines Ordners des Typs templates abzulegen, der sich im gleichen Verzeichnis wie Ihre CSPROJ-Datei befindet. Auf diese Weise können Sie ein einzelnes Projektelement verwenden, um alle Dateien und Ordner als Inhalt in die Vorlagen aufzunehmen. Erstellen Sie innerhalb eines <ItemGroup>-Elements ein <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />-Element.

Dies ist eine CSPROJ-Beispieldatei, die alle diese Vorgaben einhält. Der untergeordnete Ordner templates wird im Paketordner content gepackt, wobei alle Codedateien von der Kompilierung ausgeschlossen werden.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0</PackageVersion>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;contoso</PackageTags>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

Das folgende Beispiel veranschaulicht die Datei- und Ordnerstruktur bei Verwendung einer CSPROJ-Datei zum Erstellen eines Vorlagenpakets. Die Datei MyDotnetTemplates.csproj und der Ordner templates befinden sich beide im Stammverzeichnis eines Verzeichnisses namens project_folder. Der Ordner templates enthält zwei Vorlagen: mytemplate1 und mytemplate2. Jede Vorlage weist Inhaltsdateien und den Ordner .template.config mit der Konfigurationsdatei template.json auf.

project_folder
│   MyDotnetTemplates.csproj
│
└───templates
    ├───mytemplate1
    │   │   console.cs
    │   │   readme.txt
    │   │
    │   └───.template.config
    │           template.json
    │
    └───mytemplate2
        │   otherfile.cs
        │
        └───.template.config
                template.json

Hinweis

Um sicherzustellen, dass das Vorlagenpaket im Ergebnis von dotnet new search angezeigt wird, legen Sie den NuGet-Pakettyp auf Template fest.

Installieren eines Vorlagenpakets

Verwenden Sie den Befehl dotnet new install, um ein Vorlagenpaket zu installieren.

So installieren Sie ein Vorlagenpaket aus einem NuGet-Paket, das auf nuget.org gespeichert ist

Verwenden Sie die NuGet-Paket-ID, um ein Vorlagenpaket zu installieren.

dotnet new install <NUGET_PACKAGE_ID>

Installieren eines Vorlagenpakets über eine benutzerdefinierte NuGet-Quelle

Stellen Sie eine benutzerdefinierte NuGet-Quelle bereit (z. B. https://api.my-custom-nuget.com/v3/index.json).

dotnet new --install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>

So installieren Sie ein Vorlagenpaket aus einer lokalen NUPKG-Datei

Geben Sie den Pfad zu einer NuGet-Paketdatei des Typs .nupkg an.

dotnet new install <PATH_TO_NUPKG_FILE>

So installieren Sie ein Vorlagenpaket aus einem Dateisystemverzeichnis

Vorlagen können über einen Vorlagenordner wie den mytemplate1-Ordner aus dem obigen Beispiel installiert werden. Geben Sie den Ordnerpfad des Ordners .template.config an. Der Pfad zum Vorlagenverzeichnis muss kein absoluter Pfad sein.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Abrufen einer Liste der installierten Vorlagenpakete

Der Befehl „uninstall“ listet ohne weitere Parameter alle installierten Vorlagenpakete und enthaltenen Vorlagen auf.

dotnet new uninstall

Dieser Befehl gibt etwas Ähnliches wie die folgende Ausgabe zurück:

Currently installed items:
   Microsoft.Azure.WebJobs.ProjectTemplates
      Version: 4.0.1942
      Details:
         Author: Microsoft
         NuGetSource: https://api.nuget.org/v3/index.json
      Templates:
         Azure Functions (func) C#
         Azure Functions (func) F#
      Uninstall Command:
         dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...

Die direkt nach Currently installed items: aufgeführten Elemente sind die Bezeichner, die bei der Deinstallation eines Vorlagenpakets verwendet werden. Im vorherigen Beispiel wird Microsoft.Azure.WebJobs.ProjectTemplates aufgelistet. Wenn das Vorlagenpaket unter Verwendung eines Dateisystempfads installiert wurde, ist dieser Bezeichner der Ordnerpfad des Ordners .template.config. In der Liste werden nur die über dotnet new install installierten Vorlagenpakete angezeigt. Die Vorlagenpakete, die in das .NET SDK integriert sind, werden nicht angezeigt.

Deinstallieren eines Vorlagenpakets

Verwenden Sie den Befehl dotnet new uninstall, um ein Vorlagenpaket zu deinstallieren.

Wenn das Paket entweder über einen NuGet-Feed oder direkt über eine NUPKG-Datei installiert wurde, geben Sie den Bezeichner an.

dotnet new uninstall <NUGET_PACKAGE_ID>

Wenn das Paket durch Angabe eines Pfads zum Ordner .template.config installiert wurde, verwenden Sie diesen Pfad, um das Paket zu deinstallieren. Sie finden den absoluten Pfad des Vorlagenpakets in der Ausgabe des Befehls dotnet new uninstall. Weitere Informationen finden Sie im Abschnitt Abrufen einer Liste installierter Vorlagen.

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Erstellen einer Projekt mit einer benutzerdefinierten Vorlage

Nachdem eine Vorlage installiert wurde, verwenden Sie die Vorlage, indem Sie den dotnet new <TEMPLATE>-Befehl ausführen, wie Sie es auch mit jeder anderen vorinstallierten Vorlage machen würden. Sie können zudem Optionen für den dotnet new-Befehl festlegen, einschließlich vorlagenspezifischer Optionen, die Sie in den Vorlageneinstellungen vorgenommen haben. Geben Sie die Kurzform des Namens der Vorlage für den Befehl an:

dotnet new <TEMPLATE>

Siehe auch