Freigeben über

Tutorial: Erstellen eines Vorlagenpakets

  • Artikel

Mit .NET können Sie Vorlagen erstellen und bereitstellen, die Projekte, Dateien und sogar Ressourcen generieren. Dieses Tutorial ist der dritte Teil einer Reihe, die zeigt, 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.

In diesem Teil der Reihe wird Folgendes vermittelt:

  • Erstellen Sie mithilfe des NuGet-Pakets Microsoft.TemplateEngine.Authoring.Templates ein Vorlagenpaket.
  • Installieren Sie ein Vorlagenpaket aus einer NuGet-Paketdatei.
  • Deinstallieren Sie ein Vorlagenpaket nach Paket-ID.
  • Erstellen Sie ein „*.csproj“-Projekt zum Erstellen eines Vorlagenpakets.
  • Konfigurieren Sie die Projektdatei zum Ausführen eines Packvorgangs.
  • Installieren Sie ein Vorlagenpaket aus einer NuGet-Paketdatei.
  • Deinstallieren Sie ein Vorlagenpaket nach Paket-ID.

Voraussetzungen

  • Absolvieren Sie Teil 1 und Teil 2 dieser Tutorialreihe.

    In diesem Tutorial werden die beiden Vorlagen verwendet, die in den ersten beiden Teilen dieser Tutorialreihe erstellt wurden. Sie können eine andere Vorlage verwenden, solange diese als Ordner in den Ordner working\content kopiert wird.

  • Öffnen Sie ein Terminal, und navigieren Sie zum Ordner working.

  • Installieren von .NET 8.

  • Installieren Sie die Vorlage Microsoft.TemplateEngine.Authoring.Templates aus dem NuGet-Paketfeed.

    • Führen Sie in Ihrem Terminal den Befehl dotnet new install Microsoft.TemplateEngine.Authoring.Templates aus.

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 eines Vorlagenpaketprojekts

Ein Vorlagenpaket besteht aus einer oder mehreren Vorlagen, die in ein NuGet-Paket gepackt werden. Wenn Sie ein Vorlagenpaket installieren oder deinstallieren, werden alle darin enthaltenen Vorlagen hinzugefügt bzw. entfernt.

Bei Vorlagenpaketen handelt es sich um NuGet-Paketdateien (NUPKG). Daher können Sie diese wie jedes andere NuGet-Paket in einen NuGet-Feed hochladen. Der Befehl dotnet new install unterstützt die Installation von Vorlagenpaketen aus einem NuGet-Paketfeed, einer .nupkg-Datei oder einem Ordner mit einer Vorlage.

Üblicherweise wird eine C#-Projektdatei verwendet, um Code zu kompilieren und eine Binärdatei zu erstellen. Das Projekt kann jedoch auch verwendet werden, um ein Vorlagenpaket zu generieren. Durch Ändern der Einstellungen der CSPROJ-Datei können Sie sicherstellen, dass kein Code kompiliert wird, und stattdessen alle Ressourcen ihrer Vorlagen als Ressourcen einschließen. Beim Kompilieren erzeugt dieses Projekt ein Vorlagenpaket in Form eines NuGet-Pakets.

Das Paket, das Sie generieren, wird die zuvor erstellten [item] und (cli-templates-create-item-template.md) und Projektvorlagen enthalten.

Das Microsoft.TemplateEngine.Authoring.Templates-Paket enthält Vorlagen, die für die Vorlagenerstellung nützlich sind. Zum Installieren dieses Pakets sollte nuget.org als NuGet-Feed im Arbeitsverzeichnis verfügbar sein.

  1. Führen Sie im Arbeitsordner den folgenden Befehl aus, um die Vorlage für das Vorlagenpaket zu erstellen:

    dotnet new templatepack -n "AdatumCorporation.Utility.Templates"

    Der -n-Parameter legt den Namen der Projektdatei auf AdatumCorporation.Utility.Templates.csproj fest. Das Ergebnis sollte in etwa wie in der folgenden Ausgabe aussehen:

    The template "Template Package" was created successfully.

Processing post-creation actions...
Description: Manual actions required
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to _content_ folder. Fill in README.md.

  2. Öffnen Sie als Nächstes die Datei AdatumCorporation.Utility.Templates.csproj in einem Code-Editor, und ergänzen Sie sie gemäß den Hinweisen in der Vorlage:

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

  <PropertyGroup>
    <!-- The package metadata. Fill in the properties marked as TODO below -->
    <!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <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>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
    ... cut for brevity ...

  1. Führen Sie im Arbeitsordner den folgenden Befehl aus, um die Vorlage für das Vorlagenpaket zu erstellen:

    dotnet new console -n AdatumCorporation.Utility.Templates

    Der -n-Parameter legt den Namen der Projektdatei auf AdatumCorporation.Utility.Templates.csproj fest. Das Ergebnis sollte in etwa wie in der folgenden Ausgabe aussehen:

    The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on .\AdatumCorporation.Utility.Templates.csproj...
  Restore completed in 52.38 ms for C:\code\working\AdatumCorporation.Utility.Templates.csproj.

Restore succeeded.

  2. Löschen Sie die Datei Program.cs. Die neue Projektvorlage generiert diese Datei, wird jedoch nicht von der Vorlagen-Engine verwendet.

  3. Öffnen Sie als Nächstes die Datei AdatumCorporation.Utility.Templates.csproj in Ihrem bevorzugten Editor, und ersetzen Sie den Inhalt durch den folgenden XML-Code:

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

  <PropertyGroup>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;adatum</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>netstandard2.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
  </PropertyGroup>

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

</Project>

Beschreibung der Projekt-XML

Die Einstellungen unter <PropertyGroup> im XML-Codeschnipsel sind in zwei Gruppen unterteilt.

Die erste Gruppe enthält erforderliche Eigenschaften für ein NuGet-Paket. Die vier Einstellungen vom Typ <Package*> haben mit den NuGet-Paketeigenschaften zu tun, die Ihr Paket in einem NuGet-Feed identifizieren. Der Wert <PackageId>, der von NuGet verwendet wird, wird auch zum Deinstallieren des Vorlagenpakets verwendet. Die verbleibenden Einstellungen, etwa <Title> und <PackageTags>, hängen mit den im NuGet-Feed angezeigten Metadaten und dem .NET-Paket-Manager zusammen. Weitere Informationen zu NuGet-Einstellungen finden Sie unter NuGet pack and restore as MSBuild targets (NuGet-Befehle „pack“ und „restore“ als MSBuild-Ziele).

Hinweis

Um sicherzustellen, dass das Vorlagenpaket in Ergebnissen von dotnet new search angezeigt wird, müssen Sie <PackageType> auf Template festlegen.

In der zweiten Gruppe stellt die <TargetFramework>-Einstellung sicher, dass MSBuild ordnungsgemäß ausgeführt wird, wenn Sie den Befehl zum Packen („pack“) ausführen, um das Projekt zu kompilieren und zu packen. Die Gruppe umfasst außerdem Einstellungen, die der Konfiguration des Projekts dienen, damit die Vorlagen bei der Erstellung im entsprechenden Ordner in das NuGet-Paket eingebunden werden:

  • Die Einstellung <NoWarn> unterdrückt eine Warnmeldung, die sich nicht auf Vorlagenpaketprojekte bezieht.

  • Die <NoDefaultExcludes>-Einstellung stellt sicher, dass Dateien und Ordner, die mit einem . beginnen (wie .gitignore), Teil der Vorlage sind. Das default-Verhalten (Standard) von NuGet-Paketen besteht darin, diese Dateien und Ordner zu ignorieren.

<ItemGroup> enthält zwei Elemente. Erstens: Der Inhalt des <Content>-Elements besteht aus allem, was im Ordner templates vorhanden ist. Außerdem werden alle Ordner vom Typ bin oder obj ausgeschlossen, um zu verhindern, dass kompilierter Code eingeschlossen wird (falls Sie Ihre Vorlagen getestet und kompiliert haben). Zweitens: Das <Compile>-Element schließt alle Codedateien von der Kompilierung aus, unabhängig davon, wo sie sich befinden. Diese Einstellung verhindert, dass das für die Erstellung des Vorlagenpakets verwendete Projekt versucht, den Code in der Ordnerhierarchie templates zu kompilieren.

Tipp

Weitere Informationen zu NuGet-Metadateneinstellungen finden Sie unter Packen einer Vorlage in ein NuGet-Paket (nupkg-Datei).

Die erstellte Projektdatei enthält MSBuild-Aufgaben für die Vorlagenerstellung und Lokalisierungseinstellungen.

  <PropertyGroup>
    <LocalizeTemplates>false</LocalizeTemplates>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
  </ItemGroup>

Wichtig

Der Inhaltsinhaltsordner content enthält einen Ordner namens SampleTemplate. Löschen Sie diesen Ordner, da er der Erstellungsvorlage nur zu Demonstrationszwecken hinzugefügt wurde.

Diese MSBuild-Aufgaben ermöglichen die Vorlagenvalidierung und Lokalisierung der Vorlagenfunktionen. Die Lokalisierung ist standardmäßig deaktiviert. Um die Erstellung von Lokalisierungsdateien zu aktivieren, legen Sie LocalizeTemplates auf true fest.

Packen und Installieren

Speichern Sie die Projektdatei. Bevor Sie das Vorlagenpaket erstellen, vergewissern Sie sich, dass die Ordnerstruktur korrekt ist. Jede Vorlage, die Sie in ein Paket aufnehmen möchten, sollte im Ordner templates in ihrem eigenen Ordner gespeichert werden. Die Ordnerstruktur sollte der folgenden Hierarchie ähneln:

working
│   AdatumCorporation.Utility.Templates.csproj
└───content
    ├───extensions
    │   └───.template.config
    │           template.json
    └───consoleasync
        └───.template.config
                template.json

Der Ordner templates enthält zwei Ordner: extensions und consoleasync.

Führen Sie in Ihrem Terminal aus dem working-Ordner den Befehl dotnet pack aus. Dieser Befehl erstellt das Projekt sowie ein NuGet-Paket im Ordner working\bin\debug, wie in der folgenden Ausgabe dargestellt:

MSBuild version 17.8.0-preview-23367-03+0ff2a83e9 for .NET
  Determining projects to restore...
  Restored C:\code\working\AdatumCorporation.Utility.Templates.csproj (in 1.16 sec).

  AdatumCorporation.Utility.Templates -> C:\code\working\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
  Successfully created package 'C:\code\working\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.

Installieren Sie als Nächstes mithilfe des Befehls dotnet new install die Vorlagenpaketdatei. Unter Windows:

dotnet new install .\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Unter Linux oder macOS:

dotnet new install bin/Release/AdatumCorporation.Utility.Templates.1.0.0.nupkg

Eine Ausgabe ähnlich der folgenden sollte angezeigt werden:

The following template packages will be installed:
   C:\code\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code
Example templates: async project                  consoleasync             [C#]              Common/Console/C#9

Wenn Sie das NuGet-Paket in einen NuGet-Feed hochgeladen haben, können Sie den Befehl dotnet new install <PACKAGE_ID> verwenden. <PACKAGE_ID> entspricht dabei der Einstellung <PackageId> aus der CSPROJ-Datei.

Deinstallieren des Vorlagenpakets

Beim Entfernen eines Vorlagenpakets spielt es keine Rolle, ob Sie das Paket direkt mit der NUPKG-Datei oder per NuGet-Feed installiert haben. Verwenden Sie die Paket-ID (<PackageId>) der Vorlage, die Sie deinstallieren möchten. Mithilfe des Befehls dotnet new uninstall können Sie eine Liste der installierten Vorlagen abrufen.

C:\working> dotnet new uninstall
Currently installed items:
... cut to save space ...

  AdatumCorporation.Utility.Templates
    Details:
      NuGetPackageId: AdatumCorporation.Utility.Templates
      Version: 1.0.0
      Author: Me
    Templates:
      Example templates: async project (consoleasync) C#
      Example templates: string extensions (stringext) C#
    Uninstall Command:
      dotnet new uninstall AdatumCorporation.Utility.Templates

Führen Sie dotnet new uninstall AdatumCorporation.Utility.Templates aus, um das Vorlagenpaket zu deinstallieren. Der Befehl gibt Informationen dazu aus, welche Vorlagenpakete deinstalliert wurden.

Herzlichen Glückwunsch! Sie haben ein Vorlagenpaket installiert und deinstalliert.

Nächste Schritte

Weitere Informationen zu Vorlagen (die Ihnen größtenteils bereits bekannt sein dürften) finden Sie im Artikel Benutzerdefinierte Vorlagen für dotnet new.