Anleitung: Erstellen eines Vorlagensets

Artikel
12/28/2024

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

In diesem Teil der Reihe erfahren Sie, wie Sie:

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.

Voraussetzungen

Schließen Sie Teil 1 und Teil 2 dieser Tutorialreihe ab.

In diesem Lernprogramm werden die beiden Vorlagen verwendet, die in den ersten beiden Teilen dieser Lernprogrammreihe erstellt wurden. Sie können eine andere Vorlage verwenden, solange Sie die Vorlage als Ordner in den Ordner working\content kopieren.
Öffnen Sie ein Terminal, und navigieren Sie zum Ordner working.
Installieren Sie .NET 8 oder .NET 9.
Installieren Sie die Vorlage Microsoft.TemplateEngine.Authoring.Templates aus dem NuGet-Paketfeed.
- Führen Sie den Befehl dotnet new install Microsoft.TemplateEngine.Authoring.Templates über Ihr Terminal aus.

Erstellen eines Vorlagenpaketprojekts

Ein Vorlagenpaket ist eine oder mehrere Vorlagen, die in ein NuGet-Paket verpackt sind. Wenn Sie ein Vorlagenpaket installieren oder deinstallieren, werden alle im Paket enthaltenen Vorlagen hinzugefügt oder entfernt.

Vorlagenpakete werden durch eine NuGet-Paketdatei (.nupkg) dargestellt. Und wie jedes NuGet-Paket können Sie das Vorlagenpaket 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.

Normalerweise verwenden Sie eine C#-Projektdatei, um Code zu kompilieren und eine Binärdatei zu erzeugen. 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 werden, wird die zuvor erstellten Vorlagen des -Elements und des -Projekts enthalten.

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

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 parameter -n legt den Projektdateinamen auf AdatumCorporation.Utility.Templates.csprojfest. 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.

Öffnen Sie als Nächstes die AdatumCorporation.Utility.Templates.csproj Datei in einem Code-Editor, und füllen Sie sie entsprechend den Hinweisen in der Vorlage auf:

<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 ...

Beschreibung des Projekt-XML

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

Die erste Gruppe befasst sich mit Eigenschaften, die für ein NuGet-Paket erforderlich sind. 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 übrigen Einstellungen, wie etwa <Title> und <PackageTags>, beziehen sich auf Metadaten, die im NuGet-Feed und im .NET-Paket-Manager angezeigt werden. Weitere Informationen zu NuGet-Einstellungen finden Sie unter NuGet pack and restore as MSBuild targets (NuGet-Befehle „pack“ und „restore“ als MSBuild-Ziele).

Anmerkung

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 einstellung <TargetFramework> sicher, dass MSBuild ordnungsgemäß ausgeführt wird, wenn Sie den Packbefehl 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 nicht für Vorlagenpaket-Projekte gilt.
Die einstellung <NoDefaultExcludes> stellt sicher, dass Dateien und Ordner, die mit einem . (z. B. .gitignore) beginnen, 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 schließt das <Compile>-Element alle Codedateien vom Kompilieren aus, unabhängig davon, wo sie sich befinden. Diese Einstellung verhindert, dass das Projekt, das zum Erstellen des Vorlagenpakets verwendet wird, versucht, den Code in der Vorlagen Ordnerhierarchie 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 Autorenvorlage 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 ermöglichen, legen Sie LocalizeTemplates auf truefest.

Packen und Installieren

Speichern Sie die Projektdatei. Stellen Sie vor dem Erstellen des Vorlagenpakets sicher, 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 ähnlich der folgenden Hierarchie aussehen:

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 und erstellt ein NuGet-Paket im Ordner working\bin\Release, wie in der folgenden Ausgabe aufgeführt:

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

Die Ausgabe sollte etwa folgendermaßen aussehen:

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, wobei <PACKAGE_ID> mit der Einstellung <PackageId> aus der CSPROJ--Datei identisch ist.

Template-Paket deinstallieren

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. Sie können eine Liste der Vorlagen abrufen, die installiert werden, indem Sie den Befehl dotnet new uninstall ausführen.

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 darüber aus, welche Vorlagenpakete deinstalliert wurden.

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.

Freigeben über