Benutzerdefinierte Vorlagen für dotnet new

Das .NET SDK enthält bereits viele bereits installierte Und einsatzbereite Vorlagen. Der dotnet new Befehl ist nicht nur die Möglichkeit, eine Vorlage zu verwenden, sondern auch, wie Vorlagen installiert und deinstalliert werden. Sie können eigene benutzerdefinierte Vorlagen für jeden Projekttyp erstellen, z. B. eine App, einen Dienst, ein Tool oder eine Klassenbibliothek. Sie können sogar eine Vorlage erstellen, die eine oder mehrere unabhängige Dateien ausgibt, z. B. eine Konfigurationsdatei.

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

Das Vorlagenmodul ist Open Source, und das Onlinecode-Repository befindet sich auf dotnet/templating auf GitHub. Weitere Vorlagen, einschließlich Vorlagen von Drittanbietern, finden Sie unter dotnet new search. Weitere Informationen zum Erstellen und Verwenden von benutzerdefinierten Vorlagen finden Sie unter How to create your own templates for dotnet new and the dotnet/templating GitHub repo Wiki.

Hinweis

Vorlagenbeispiele sind im GitHub-Repository dotnet/templating verfügbar.

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. Um die integrierten Vorlagen aufzulisten, führen Sie den Befehl dotnet new list aus:

dotnet new list

Konfiguration

Eine Vorlage besteht aus den folgenden Teilen:

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

Quelldateien und Ordner

Die Quelldateien und Ordner enthalten alle Dateien und Ordner, die das Vorlagenmodul verwenden soll, wenn der dotnet new <TEMPLATE> Befehl ausgeführt wird. Die Vorlagen-Engine wurde entwickelt, um lauffähige Projekte als Quellcode zur Erstellung von Projekten zu verwenden. Dies hat mehrere Vorteile:

Das Vorlagenmodul erfordert nicht, dass Sie spezielle Token in den Quellcode Ihres Projekts einfügen.
Die Codedateien sind weder spezielle Dateien noch in irgendeiner Weise geändert, um mit der Template-Engine zu arbeiten. Daher funktionieren die Tools, die Sie normalerweise beim Arbeiten mit Projekten verwenden, auch mit Vorlageninhalten.
Sie erstellen, ausführen und debuggen Ihre Vorlagenprojekte genau wie für alle anderen Projekte.
Sie können schnell eine Vorlage aus einem vorhandenen Projekt erstellen, indem Sie dem Projekt einfach eine ./.template.config/template.json-Konfigurationsdatei hinzufügen.

Dateien und Ordner, die in der Vorlage gespeichert sind, sind nicht auf formale .NET-Projekttypen beschränkt. Quelldateien und Ordner können aus allen Inhalten bestehen, die Sie erstellen möchten, wenn die Vorlage verwendet wird, auch wenn das Vorlagenmodul nur eine Datei als Ausgabe erzeugt.

Von der Vorlage generierte Dateien können basierend auf Logik und Einstellungen geändert werden, die Sie in der konfigurationsdateitemplate.json angegeben haben. Der Benutzer kann diese Einstellungen überschreiben, indem Optionen an den dotnet new <TEMPLATE> Befehl übergeben werden. Ein gängiges Beispiel für eine benutzerdefinierte Logik stellt einen Namen für eine Klasse oder Variable in der Codedatei bereit, die von einer Vorlage bereitgestellt wird.

template.json

Die template.json Datei wird in einem .template.config Ordner im Stammverzeichnis der Vorlage platziert. Die Datei stellt dem Vorlagenmodul Konfigurationsinformationen bereit. Für die Mindestkonfiguration müssen die in der folgenden Tabelle angezeigten Elemente verwendet werden, die zum Erstellen einer funktionalen Vorlage ausreichen.

Mitglied	Typ	BESCHREIBUNG
`$schema`	URI (Uniform Resource Identifier)	Das JSON-Schema für die template.json-Datei . Editoren, die JSON-Schemas unterstützen, ermöglichen JSON-Bearbeitungsfeatures, wenn das Schema angegeben wird. Beispielsweise erfordert Visual Studio Code, dass dieser Member IntelliSense aktiviert. Verwenden Sie einen Wert von `http://json.schemastore.org/template`.
`author`	Schnur	Der Autor der Vorlage.
`classifications`	array(string)	Null oder mehr Merkmale der Vorlage, die ein Benutzer beim Suchen nach der Vorlage verwenden kann. Die Klassifizierungen werden auch in der Spalte "Kategorien " angezeigt, wenn sie in einer Liste mit Vorlagen angezeigt wird, die mit dem `dotnet new list` Befehl erstellt wurden.
`identity`	Schnur	Ein eindeutiger Name für diese Vorlage.
`name`	Schnur	Der Name für die Vorlage, die benutzern angezeigt werden soll.
`shortName`	Schnur	Ein Standard-Kurznamen zur Auswahl der Vorlage, die in Umgebungen gilt, in denen der Vorlagenname vom Benutzer angegeben wird und nicht über eine GUI ausgewählt wird. Beispielsweise ist der Kurzname nützlich, wenn Vorlagen aus einer Eingabeaufforderung mit CLI-Befehlen verwendet werden.
`sourceName`	Schnur	Der Name in der Quellstruktur, der durch den vom Benutzer festgelegten Namen ersetzt werden soll. Die Template-Engine sucht nach jedem Vorkommen des im Konfigurationsfile erwähnten `sourceName` und ersetzt es in Dateinamen und Dateiinhalten. Der zu ersetzende Wert kann während der Ausführung einer Vorlage mithilfe der Optionen `-n` oder `--name` angegeben werden. Wenn kein Name angegeben ist, wird das aktuelle Verzeichnis verwendet.
`preferNameDirectory`	Boolescher Typ (Boolean)	Gibt an, ob ein Verzeichnis für die Vorlage erstellt werden soll, wenn der Name angegeben ist, 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 template.json-Datei finden Sie im JSON-Schemaspeicher. Weitere Informationen zur template.json-Datei finden Sie im Dotnet-Vorlagenwiki. Ausführlichere Beispiele und Informationen dazu, wie Sie Ihre Vorlagen in Visual Studio sichtbar machen, finden Sie in den Ressourcen, die Sayed Hashimi erstellt hat.

Beispiel

Hier sehen Sie beispielsweise einen Vorlagenordner, der zwei Inhaltsdateien enthält: console.cs und readme.txt. Es gibt auch den erforderlichen Ordner mit dem Namen .template.config , der die template.json Datei enthält.

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

Die template.json Datei 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. Nach der Installation des Pakets kann das shortName Paket mit dem dotnet new Befehl verwendet werden. Zum Beispiel, dotnet new adatumconsole würde die console.cs- und readme.txt-Dateien in den aktuellen Ordner ausgeben.

Vorlagenlokalisierung

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

Die lokalisierbaren Elemente einer Vorlage sind:

Name
Verfasser
BESCHREIBUNG
Symbole
- BESCHREIBUNG
- Anzeigename
- Beschreibungen und Anzeigename von Optionen für Auswahlparameter
Nachfolgende Aktionen
- BESCHREIBUNG
- Manuelle Anweisungen

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

Der Lokalisierungs-JSON besteht aus Schlüsselwertpaaren:

Der Schlüssel ist der Verweis auf ein zu lokalisierendes Element 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 zur Lokalisierung von Vorlagen finden Sie auf der Lokalisierungsseite des dotnet templating Wikis.

Beispiel

Hier finden Sie z. B. 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 entspricht templatestrings.pt-BR.json der Kultur 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 ist mit dem Dotnet-Pack-Befehl und einer CSPROJ-Datei verpackt. Alternativ kann NuGet zusammen mit dem Befehl nuget pack und einer .nuspec-Datei verwendet werden. NuGet erfordert jedoch das .NET Framework unter Windows und Mono unter Linux und macOS.

Die CSPROJ-Datei unterscheidet sich geringfügig von einer herkömmlichen Csproj-Datei mit Codeprojekt. Beachten Sie die folgenden Einstellungen:

Die Einstellung <PackageType> wird hinzugefügt und auf Template festgelegt.
Die <PackageVersion> Einstellung wird hinzugefügt und auf eine gültige NuGet-Versionsnummer festgelegt.
Die <PackageId> Einstellung wird hinzugefügt und auf einen eindeutigen Bezeichner festgelegt. Dieser Bezeichner wird verwendet, um das Vorlagenpaket zu deinstallieren und wird von NuGet-Feeds verwendet, um Ihr Vorlagenpaket zu registrieren.
Allgemeine Metadateneinstellungen sollten festgelegt werden: <Title>, , <Authors>, <Description>und <PackageTags>.
Die <TargetFramework> Einstellung muss festgelegt werden, obwohl die vom Vorlagenprozess erstellte Binärdatei nicht verwendet wird. Im folgenden Beispiel ist sie auf netstandard2.0.

Ein Vorlagenpaket in Form eines nupkg NuGet-Pakets erfordert, dass alle Vorlagen im Inhaltsordner innerhalb des Pakets gespeichert werden. Es gibt einige weitere Einstellungen, die Sie einer CSPROJ-Datei hinzufügen möchten, um sicherzustellen, dass das generierte nupkg als Vorlagenpaket installiert werden kann:

Die <IncludeContentInPack> Einstellung ist so festgelegt, dass true alle Dateien eingeschlossen werden, die das Projekt als Inhalt im NuGet-Paket festlegt.
Die <IncludeBuildOutput> Einstellung ist so festgelegt, dass false alle vom Compiler generierten Binärdateien aus dem NuGet-Paket ausgeschlossen werden.
Die Einstellung <ContentTargetFolders> wird auf content festgelegt. Dadurch wird sichergestellt, dass die als Inhalt festgelegten Dateien im Inhaltsordner im NuGet-Paket gespeichert werden. Dieser Ordner im NuGet-Paket wird vom Dotnet-Vorlagensystem analysiert.

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

Eine einfache Möglichkeit zum Strukturieren des Vorlagenpakets besteht darin, alle Vorlagen in einzelnen Ordnern und dann jeden Vorlagenordner in einem Vorlagenordner zu platzieren, der sich im selben Verzeichnis wie Ihre CSPROJ-Datei befindet. Auf diese Weise können Sie ein einzelnes Projektelement verwenden, um alle Dateien und Ordner in die Vorlagen als Inhalt einzuschließen. Erstellen Sie innerhalb eines <ItemGroup> Elements ein <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> Element.

Hier ist eine Beispiel-CSPROJ-Datei , die alle diese Richtlinien befolgt. Er packiert den untergeordneten Vorlagenordner in den Inhaltspaketordner und schließt dabei alle Codedateien vom Kompilieren aus.

<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 der Verwendung eines CSPROJ zum Erstellen eines Vorlagenpakets. Die Datei "MyDotnetTemplates.csproj " und " Vorlagen " befinden sich beide im Stammverzeichnis eines Verzeichnisses mit dem Namen project_folder. Der Vorlagenordner enthält zwei Vorlagen, mytemplate1 und mytemplate2. Jede Vorlage enthält Inhaltsdateien und einen .template.config Ordner mit einer template.json Konfigurationsdatei.

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 dotnet new search Ergebnis angezeigt wird, legen Sie den NuGet-Pakettyp auf Template.

Installieren eines Vorlagenpakets

Verwenden Sie den Befehl für die neue Installation von dotnet , um ein Vorlagenpaket zu installieren.

Warnung

Vorlagen können MSBuild-Code beim Auslösen ausführen, keine nicht vertrauenswürdigen .NET-Vorlagen installieren oder ausführen.

Um ein Vorlagenpaket aus einem NuGet-Paket zu installieren, das bei nuget.org gespeichert ist, folgen Sie diesen Schritten:

Verwenden Sie den NuGet-Paketbezeichner, um ein Vorlagenpaket zu installieren.

dotnet new install <NUGET_PACKAGE_ID>

So installieren Sie ein Vorlagenpaket aus einer benutzerdefinierten 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 nupkg NuGet-Paketdatei an.

dotnet new install <PATH_TO_NUPKG_FILE>

So installieren Sie ein Vorlagenpaket aus einem Dateisystemverzeichnis

Vorlagen können aus einem Vorlagenordner wie dem Ordner "mytemplate1 " aus dem vorherigen Beispiel installiert werden. Geben Sie den Ordnerpfad des .template.config Ordners an. Der Pfad zum Vorlagenverzeichnis muss nicht absolut sein.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Abrufen einer Liste der installierten Vorlagenpakete

Der "Uninstall"-Befehl listet ohne zusätzliche Parameter alle installierten Template-Pakete und enthaltenen Templates 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 erste Ebene der Elemente danach Currently installed items: sind die Bezeichner, die beim Deinstallieren eines Vorlagenpakets verwendet werden. Im vorherigen Beispiel wird Microsoft.Azure.WebJobs.ProjectTemplates aufgeführt. Wenn das Vorlagenpaket mithilfe eines Dateisystempfads installiert wurde, ist dieser Bezeichner der Ordnerpfad des .template.config Ordners. In der Liste werden nur die über dotnet new install installierten Template-Pakete 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 von einem NuGet-Feed oder von einer nupkg-Datei direkt installiert wurde, geben Sie den Bezeichner an.

dotnet new uninstall <NUGET_PACKAGE_ID>

Wenn das Paket installiert wurde, indem Sie einen Pfad zum ordner.template.config angeben, verwenden Sie diesen Pfad, um das Paket zu deinstallieren. Der absolute Pfad des Vorlagenpakets wird in der vom dotnet new uninstall Befehl bereitgestellten Ausgabe angezeigt. Weitere Informationen finden Sie im Abschnitt " Abrufen einer Liste der installierten Vorlagen ".

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Erstellen eines Projekts mithilfe einer benutzerdefinierten Vorlage

Nachdem eine Vorlage installiert wurde, verwenden Sie die Vorlage, indem Sie den dotnet new <TEMPLATE> Befehl wie bei jeder anderen vorinstallierten Vorlage ausführen. Sie können auch Optionen für den dotnet new Befehl angeben, einschließlich vorlagenspezifischer Optionen, die Sie in den Vorlageneinstellungen konfiguriert haben. Geben Sie den Kurznamen der Vorlage direkt an den Befehl an:

dotnet new <TEMPLATE>

Siehe auch

Feedback

War diese Seite hilfreich?

Last updated on 2025-06-20

Freigeben über

Benutzerdefinierte Vorlagen für dotnet new

.NET-Standardvorlagen

Konfiguration

Quelldateien und Ordner

template.json

Beispiel

Vorlagenlokalisierung

Beispiel

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

Installieren eines Vorlagenpakets

Um ein Vorlagenpaket aus einem NuGet-Paket zu installieren, das bei nuget.org gespeichert ist, folgen Sie diesen Schritten:

So installieren Sie ein Vorlagenpaket aus einer benutzerdefinierten NuGet-Quelle

So installieren Sie ein Vorlagenpaket aus einer lokalen nupkg-Datei

So installieren Sie ein Vorlagenpaket aus einem Dateisystemverzeichnis

Abrufen einer Liste der installierten Vorlagenpakete

Deinstallieren eines Vorlagenpakets

Erstellen eines Projekts mithilfe einer benutzerdefinierten Vorlage

Siehe auch

Feedback

Zusätzliche Ressourcen