.NET-Vorlagen für Autoren

Als Vorlagenautor erstellen Sie .NET Vorlagen – Blaupausen, die Projekte, Dateien oder andere Ressourcen aus einer vordefinierten Struktur generieren. Wenn Benutzer ausgeführt werdendotnet new <shortName>, liest das .NET Vorlagenmodul die Vorlage und erzeugt die Ausgabe im aktuellen Verzeichnis. Visual Studio das Dialogfeld "Neues Projekt erstellen" verwendet auch das .NET Vorlagenmodul für .NET Projektvorlagen, sodass Vorlagen, die Sie für die CLI erstellen, auch in Visual Studio funktionieren.

Das .NET SDK enthält integrierte Vorlagen für allgemeine Ausgangspunkte wie Konsolen-Apps, Klassenbibliotheken und ASP.NET Projekte. Über diese integrierten Vorlagen hinaus können Sie eigene Vorlagen erstellen und als NuGet-Pakete verteilen.

Dieser Artikel ist eine Referenz für Vorlagenautoren. Es wird erläutert, wie Vorlagen strukturiert, konfiguriert und verteilt werden. Schrittweise Anleitungen zum Erstellen und Verpacken von Vorlagen finden Sie im Abschnitt "Verwandte Inhalte ".

Vorlagentypen

Das .NET Vorlagenmodul unterstützt drei Arten von Vorlagen: Elementvorlagen, Projektvorlagen und Lösungsvorlagen.

• Elementvorlagen generieren eine oder mehrere Dateien, z. B. eine Codedatei, Konfigurationsdatei oder andere Ressource, ohne ein gesamtes Projekt um sie herum zu generieren. Beispielsweise kann eine Elementvorlage eine Klassendatei erzeugen, die eine Reihe von Erweiterungsmethoden hinzufügt, oder eine JSON-Konfigurationsdatei, die einem Standardlayout folgt, das Ihr Team verwendet. Informationen zum Erstellen einer Elementvorlage finden Sie im Lernprogramm: Erstellen einer Elementvorlage.

• Project Vorlagen generieren eine vollständige project Struktur. Die integrierte Konsolenprojektvorlage erzeugt z. B. eine .csproj Datei, eine Program.cs Datei und alle anderen Dateien, aus denen das Projekt besteht. Erstellen Sie eine Projektvorlage, wenn Sie Benutzern anstelle einzelner Dateien einen vollständigen Projektstartpunkt geben möchten. Informationen zum Erstellen einer Projektvorlage finden Sie im Lernprogramm: Erstellen einer Projektvorlage.

• Projektmappenvorlagen generieren eine Lösung mit einem oder mehreren Projekten. Beispielsweise kann eine Lösungsvorlage ein API-Projekt erstellen, das mit einem Testprojekt in einem einzigen Schritt gekoppelt ist.

Wenn Sie eine eigene Vorlage erstellen, deklarieren Sie den Typ mithilfe des tags.type Felds in der template.json Konfigurationsdatei. Die gültigen Werte sind "project", "item"und "solution". Mit diesen Werten können Benutzer Ergebnisse filtern, wenn sie nach Vorlagen suchen, mit dotnet new search oder dotnet new list.

Vorlagenstruktur

Eine Vorlage ist ein Ordner auf dem Datenträger, der zwei Dinge enthält: die Vorlagenquelldateien und einen speziellen .template.config Unterordner. Wenn ein Benutzer ausgeführt wird dotnet new <shortName>, kopiert das Vorlagenmodul die Quelldateien an den Ausgabespeicherort und wendet alle Konfigurationen an, die Sie für die Vorlage definiert haben.

mytemplate/
├── console.cs
├── readme.txt
└── .template.config/
    ├── template.json
    └── icon.png

Die Quelldateien können beliebige Dateitypen sein. Das Vorlagenmodul erfordert nicht, dass Sie spezielle Token oder Markierungen in den Quellcode einfügen. Es verwendet die Dateien as-is, was bedeutet, dass Sie das Quellprojekt einer Vorlage genau wie ein normales .NET Projekt erstellen, ausführen und debuggen können. Um ein vorhandenes Projekt in eine Vorlage umzuwandeln, fügen Sie dem Projektstamm eine .template.config/template.json Datei hinzu.

Sie können optional Ersetzungstoken, die an Vorlagenparameter (Symbole) gebunden sind, direkt in Vorlagenquelldateien und Dateinamen einfügen. Wenn die Token ungültiger Quellcode sind, können Sie das Quellprojekt nicht erstellen, ausführen oder debuggen, bevor Sie es als Vorlage bereitstellen. Die Token wirken sich nicht auf Projekte aus, die Benutzer aus der bereitgestellten Vorlage erstellen, da das Vorlagenmodul sie während der Projekterstellung ersetzt.

Die einzige erforderliche Datei ist .template.configtemplate.json. Diese Datei teilt dem Vorlagenmodul alles mit, was es benötigt: Name, Kurzname, Autor, Klassifizierungen und alle Parameter, die Benutzer übergeben können, wenn sie aus der Vorlage erstellen. Sie können eine icon.png Datei auch im .template.config Ordner platzieren. Das Terminal zeigt keine Symbole an, aber Visual Studio zeigt das Symbol neben der Vorlage im Dialogfeld "Neues Projekt erstellen" an. Ein PNG 128×128 funktioniert gut.

Die template.json-Datei

Die template.json Datei ist die einzige erforderliche Konfiguration in einer Vorlage. Es befindet sich innerhalb des .template.config Ordners und teilt dem Vorlagenmodul mit, wie Sie Ihre Vorlage präsentieren und verarbeiten können. In der folgenden Tabelle werden allgemeine erforderliche und optionale Felder beschrieben:

Zwei Felder verdienen zusätzliche Aufmerksamkeit. Das sourceName Feld behandelt die Benennung von Vorlagen: Legen Sie sie auf eine Zeichenfolge fest, die in Ihren Dateinamen und Quellcode angezeigt wird (z MyTemplate. B. ), und das Vorlagenmodul ersetzt jedes Vorkommen durch den Namen, den der Benutzer beim Erstellen der Vorlage übergibt. Das classifications Feld steuert die Auffindbarkeit. Wählen Sie Tags aus, die den Zweck Ihrer Vorlage genau beschreiben, damit Benutzer sie bei der Suche finden können.

Dies ist ein Minimum template.json für eine Konsolenvorlage:

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": [ "Common", "Console" ],
  "description": "Creates a console application.",
  "identity": "MyCompany.ConsoleTemplate.CSharp",
  "name": "My Console App",
  "shortName": "myconsole",
  "sourceName": "MyConsoleApp",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

Das vollständige Schema ist im JSON Schema Store verfügbar. Erweiterte Konfigurationsoptionen, z. B. bedingte Dateieinschluss, Aktionen nach der Erstellung und Multiprojektvorlagen, finden Sie im dotnet/templating GitHub Wiki.

Vorlagenparameter (Symbole)

Der symbols Abschnitt in template.json definiert die Parameter, die Benutzer beim Erstellen aus Ihrer Vorlage übergeben können. Jedes Symbol wird zu einer CLI-Optiondotnet new <shortName>, sodass ein benanntes --ClassNameClassName Symbol wird (oder -C wenn Sie einen Kurznamen definieren).

Jeder Symboleintrag unterstützt die folgenden allgemeinen Einstellungen:

Die replaces Und fileRename Einstellungen sind, wie Symbole die Ersetzung von Symbolen fördern. Wenn ein Benutzer einen Wert bereitstellt, ersetzt das Vorlagenmodul jedes Vorkommen der Zeichenfolge innerhalb des replaces Dateiinhalts und jedes Vorkommen der fileRename Zeichenfolge in Dateinamen. Wenn der Benutzer keinen Wert bereitstellt, wird er defaultValue stattdessen verwendet.

Mit dem folgenden Symbol können Benutzer beispielsweise den Klassennamen festlegen, wenn sie aus der Vorlage erstellen. Die Datei wird umbenannt, und die darin enthaltene Klasse wird entsprechend aktualisiert:

"symbols": {
  "ClassName": {
    "type": "parameter",
    "description": "The name of the code file and class.",
    "datatype": "text",
    "replaces": "StringExtensions",
    "fileRename": "StringExtensions",
    "defaultValue": "StringExtensions"
  }
}

Mit diesem definierten Symbol kann ein Benutzer ausgeführt werden dotnet new <shortName> --ClassName MyHelpers , um eine Datei mit dem Namen MyHelpers.cs einer Klasse mit dem Namen MyHelperszu erzeugen. Ohne das Flag behalten die Datei und klasse den Standardnamen StringExtensionsbei.

Um die verfügbaren Parameter zu überprüfen, übergeben -? Sie nach der Installation an den kurzen Namen:

dotnet new <shortName> -?

Vorlagenpakete

Ein Vorlagenpaket ist eine NuGet(.nupkg)-Datei, die eine oder mehrere Ihrer Vorlagen zusammenbündelt. Wenn ein Benutzer Ihr Vorlagenpaket installiert, registriert das .NET Vorlagenmodul alle darin enthaltenen Vorlagen gleichzeitig. Pakete sind die Standardmethode zum Verteilen von Vorlagen. Veröffentlichen Sie ein einzelnes Paket für NuGet.org oder einen privaten NuGet-Feed, oder geben Sie eine lokale .nupkg Datei frei, und Benutzer erhalten die gesamte Sammlung mit einem Einzigen Befehl.

Verwenden Sie zum Erstellen eines Vorlagenpakets eine C#-Projektdatei (.csproj), die als Paketprojekt und nicht als Kompilierungsprojekt konfiguriert ist. Die wichtigsten Einstellungen, die diese Arbeit vornehmen, sind:

Die templatepack Projektvorlage bietet die einfachste Möglichkeit zum Erstellen eines Verpackungsprojekts:

1. Installieren Sie die Microsoft. TemplateEngine.Authoring.Templates NuGet-Paket:

   dotnet new install Microsoft.TemplateEngine.Authoring.Templates
   

2. Erstellen Sie das Paketprojekt:

   dotnet new templatepack -n <PackageName>
   

Das generierte Projekt enthält die richtigen .csproj Einstellungen, einen content Ordner für Ihre Vorlagen und MSBuild-Aufgaben für die Vorlagenüberprüfung und optionale Lokalisierung.

Eine vollständige exemplarische Vorgehensweise zum Erstellen, Packen und Veröffentlichen eines Vorlagenpakets finden Sie unter Lernprogramm: Erstellen eines Vorlagenpakets.

Lokales Testen der Vorlage

Installieren Sie ihre Vorlage während der Vorlagenentwicklung direkt aus dem Ordner, um sie zu testen, ohne zuerst ein Paket zu erstellen. Übergeben Sie den Pfad zum Verzeichnis, das den .template.config Ordner enthält:

dotnet new install ./mytemplate/

Wenn Sie alle installierten Vorlagenpakete und den genauen Befehl zum Deinstallieren der einzelnen Vorlagen anzeigen möchten, führen Sie dotnet new uninstall keine Argumente aus:

dotnet new uninstall

Um eine aus einem Verzeichnis installierte Vorlage zu deinstallieren, übergeben Sie denselben Verzeichnispfad, den Sie zum Installieren verwendet haben:

dotnet new uninstall ./mytemplate/

Sobald Sie bereit sind, Ihre Vorlage freizugeben, packen Sie sie als NuGet-Paket (siehe Vorlagenpakete) und verteilen Sie sie. Benutzer installieren Ihre veröffentlichte Vorlage mit dotnet new install und einem der folgenden Quellargumente:

• Eine NuGet-Paket-ID, die die neueste stabile Version aus den NuGet-Quellen installiert, die für das aktuelle Verzeichnis konfiguriert sind:

  dotnet new install AdatumCorporation.ConsoleTemplate.CSharp
  

• Eine NuGet-Paket-ID mit einer benutzerdefinierten Feed-URL. Die --nuget-source Option verwendet den angegebenen Feed zusätzlich zu den konfigurierten NuGet-Quellen nur für diese Installation:

  dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json
  

• Ein Pfad zu einer lokalen .nupkg Datei:

  dotnet new install ./AdatumCorporation.ConsoleTemplate.CSharp.1.0.0.nupkg
  

Um ein paket zu deinstallieren, das aus einer NuGet-Quelle oder einer lokalen .nupkg Datei installiert ist, verwenden Sie die NuGet-Paket-ID:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

Die integrierten SDK-Vorlagen werden nicht in der Deinstallationsliste angezeigt und können nicht entfernt werden.dotnet new uninstall

Vorlagenlokalisierung

Das .NET Vorlagenmodul unterstützt die optionale Lokalisierung von Vorlagenmetadaten. Wenn Sie Lokalisierungsdateien bereitstellen, zeigen Hosts wie dotnet new und das Dialogfeld Visual Studio Neue Project den Namen, die Beschreibung und die Symbolinformationen der Vorlage in der Sprache des Benutzers anstelle der ursprünglichen verfassten Sprache an.

Die folgenden Vorlagenfelder unterstützen die Lokalisierung:

• name
• author
• description
• Symbol description und displayName
• Beschreibung und Anzeigename für jede Auswahl in einem Auswahlparameter
• Aktion posten description und manualInstructions

Erstellen Sie zum Hinzufügen der Lokalisierung einen localize Unterordner innerhalb .template.config und fügen Sie pro Sprache eine JSON-Datei hinzu. Benennen Sie jede Datei templatestrings.<lang-code>.json, wobei <lang-code> sie mit einem gültigen CultureInfo Namen übereinstimmt, z pt-BR. B. , , zh-Hansoder de. Jede Datei enthält Schlüsselwertpaare, bei denen der Schlüssel ein Pfad zum Element template.jsonist, wobei / er als Trennzeichen für geschachtelte Felder verwendet wird.

Beispiel: Ein template.json Beispiel mit folgendem Inhalt:

{
  "$schema": "https://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."
    }
  }
}

Eine lokalisierungsdatei für Brasilianisches Portugiesisch mit dem Namen templatestrings.pt-BR.json würde wie folgt aussehen:

{
  "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."
}

Das Vorlagenmodul analysiert diese Dateien beim Laden von Vorlageninformationen und gibt lokalisierte Werte automatisch basierend auf der aktuellen Benutzeroberflächenkultur zurück. Für den Benutzer sind keine zusätzlichen Schritte erforderlich.

Die Lokalisierung ist optional. Wenn Sie keine Lokalisierungsdateien enthalten, funktioniert die Vorlage normal und zeigt immer die Werte von template.json. Weitere Informationen finden Sie auf der Seite "dotnet/templating wiki localization".

Integration von Visual Studio

Visual Studio erstellt ein neues Projektdialogfeld verwendet das .NET Vorlagenmodul für .NET Projektvorlagen. Vorlagen, die Sie für dotnet new die Arbeit in Visual Studio erstellen, auch ohne zusätzliche Konfiguration. Wenn ein Benutzer Ihr Vorlagenpaket mit dotnet new installinstalliert, erkennt Visual Studio diese Vorlagen automatisch im Dialogfeld.

Project- und Lösungsvorlagen werden neben den integrierten SDK-Vorlagen im Dialogfeld "Neue project erstellen" angezeigt. Benutzer können Vorlagen anhand des Namens, der Sprache oder der Tags aus dem classifications Feld in der Datei der Vorlage template.json finden. Genaue Klassifizierungen helfen Ihrer Vorlagenoberfläche in den richtigen Filterkategorien. Wählen Sie sie daher sorgfältig aus. Um Ihrer Vorlage eine ansprechende Darstellung im Dialogfeld zu verleihen, fügen Sie dem .template.config Ordner einen icon.png hinzu– Visual Studio zeigt sie neben dem Namen der Vorlage an.

Elementvorlagen werden derzeit nicht im Dialogfeld "Neues Elementhinzufügen>" angezeigt. Benutzer können weiterhin Elementvorlagen mit dem dotnet new Befehl im Terminal verwenden.

Um ihre Vorlage für Visual Studio Benutzer, die sie noch nicht installiert haben, auffindbar zu machen, veröffentlichen Sie Ihr Vorlagenpaket in nuget.org. Das Dialogfeld "Neues Projekt erstellen" enthält eine Option "Weitere Vorlagen installieren" aus der Onlinesuchoption, die nuget.org nach Vorlagenpaketen durchsucht. Wenn ein Benutzer Ihr Paket über diese Option installiert, verwendet Visual Studio denselben Installationsmechanismus wie dotnet new install.

Ausführlichere Anleitungen zur Visual Studio-spezifischen Integration – z. B. Steuern der Sortierreihenfolge von Vorlagen und Konfigurieren zusätzlicher IDE-spezifischer Optionen – finden Sie im Vorlagenbeispielrepository von Sayed Hashimi.

Verwandte Inhalte

• Tutorial: Erstellen einer Elementvorlage
• Lernprogramm: Erstellen einer Projektvorlage
• Lernprogramm: Erstellen eines Vorlagenpakets
• Befehl „dotnet new“
• dotnet/templating GitHub Repositorywiki
• Vorlagenbeispiele