Udostępnij za pośrednictwem

Samouczek: tworzenie pakietu szablonu

  • Artykuł

Za pomocą platformy .NET można tworzyć i wdrażać szablony, które generują projekty, pliki, a nawet zasoby. Ta część trzecia serii uczy, jak tworzyć, instalować i odinstalowywać szablony do użycia za pomocą polecenia dotnet new.

Gotowy szablon można wyświetlić w repozytorium GitHub przykładów platformy .NET .

W tej części serii dowiesz się, jak wykonywać następujące działania:

Warunki wstępne

  • Ukończ część 1 i część 2 tej serii samouczków.

    W tym samouczku użyto dwóch szablonów utworzonych w dwóch pierwszych częściach tej serii samouczków. Możesz użyć innego szablonu, o ile skopiujesz szablon jako folder do folderu working\content.

  • Otwórz terminal i przejdź do roboczego folderu .

  • Zainstaluj program .NET 8 lub .NET 9.

  • Zainstaluj szablon Microsoft.TemplateEngine.Authoring.Templates z kanału informacyjnego pakietów NuGet.

    • Uruchom polecenie dotnet new install Microsoft.TemplateEngine.Authoring.Templates z terminalu.

Tworzenie projektu pakietu szablonu

Pakiet szablonu to jeden lub więcej szablonów spakowanych do pakietu NuGet. Podczas instalowania lub odinstalowywania pakietu szablonu wszystkie szablony zawarte w pakiecie są dodawane lub usuwane odpowiednio.

Pakiety szablonów są reprezentowane przez plik NuGet (.nupkg). Podobnie jak każdy pakiet NuGet, możesz przekazać pakiet szablonu do źródła danych NuGet. Polecenie dotnet new install obsługuje instalowanie pakietów szablonów z kanału informacyjnego pakietów NuGet, pliku .nupkg lub katalogu z szablonem.

Zwykle do kompilowania kodu i tworzenia pliku binarnego używa się pliku projektu w języku C#. Jednak projekt może służyć również do generowania pakietu szablonu. Zmieniając ustawienia .csproj, można uniemożliwić kompilowanie dowolnego kodu i zamiast tego uwzględnić wszystkie zasoby szablonów jako zasoby. Po zbudowaniu tego projektu tworzony jest pakiet NuGet szablonu.

Pakiet, który wygenerujesz, będzie zawierał wcześniej utworzone szablony elementu oraz projektu .

Pakiet Microsoft.TemplateEngine.Authoring.Templates zawiera szablony przydatne do tworzenia szablonów. Aby zainstalować ten pakiet, nuget.org powinno być dostępne jako źródło danych NuGet w katalogu roboczym.

  1. W roboczym folderze uruchom następujące polecenie, aby utworzyć pakiet szablonu.

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

    Parametr -n ustawia nazwę pliku projektu na AdatumCorporation.Utility.Templates.csproj. Powinien zostać wyświetlony wynik podobny do poniższych danych wyjściowych.

    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. Następnie otwórz plik AdatumCorporation.Utility.Templates.csproj w edytorze kodu i wypełnij go zgodnie z wskazówkami w szablonie:

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

Opis kodu XML projektu

Ustawienia w obszarze <PropertyGroup> we fragmencie kodu XML są podzielone na dwie grupy.

Pierwsza grupa zajmuje się właściwościami wymaganymi dla pakietu NuGet. Cztery ustawienia <Package*> dotyczą właściwości pakietu NuGet, aby zidentyfikować pakiet w źródle NuGet. Wartość <PackageId>, podczas gdy używana przez NuGet, jest również wykorzystywana do odinstalowania pakietu szablonu. Pozostałe ustawienia, takie jak <Title> i <PackageTags>, są związane z metadanymi wyświetlanymi w kanale informacyjnym NuGet i menedżerze pakietów .NET. Aby uzyskać więcej informacji o ustawieniach NuGet, zobacz właściwości NuGet i MSBuild.

Notatka

Aby upewnić się, że pakiet szablonu jest wyświetlany w wynikach dotnet new search, <PackageType> musi być ustawiona na Template.

W drugiej grupie ustawienie <TargetFramework> gwarantuje, że program MSBuild działa prawidłowo po uruchomieniu polecenia pakietu w celu skompilowania i spakowania projektu. Grupa zawiera również ustawienia, które muszą mieć związek z konfigurowaniem projektu w celu uwzględnienia szablonów w odpowiednim folderze w pakiecie NuGet podczas jego tworzenia:

  • Ustawienie <NoWarn> pomija komunikat ostrzegawczy, który nie ma zastosowania do projektów pakietów szablonów.

  • Ustawienie <NoDefaultExcludes> zapewnia, że pliki i foldery rozpoczynające się od . (na przykład .gitignore) są częścią szablonu. Domyślne zachowanie pakietów NuGet polega na ignorowaniu tych plików i folderów.

<ItemGroup> zawiera dwa elementy. Najpierw element <Content> zawiera wszystkie elementy w szablonach jako zawartość. Jest to również skonfigurowane tak, aby wykluczyć jakiekolwiek foldery bin lub foldery obj, aby zapobiec włączeniu dowolnego skompilowanego kodu (jeśli przetestowano i skompilowano szablony). Po drugie, element <Compile> wyklucza wszystkie pliki kodu z kompilowania niezależnie od tego, gdzie się znajdują. To ustawienie uniemożliwia projektowi używanemu do utworzenia pakietu szablonów próbę skompilowania kodu w hierarchii folderów szablonów .

Napiwek

Aby uzyskać więcej informacji na temat ustawień metadanych NuGet, zobacz Pack a template into a NuGet package (nupkg file).

Utworzony plik projektu zawiera zadania MSBuild do tworzenia szablonów oraz ustawienia lokalizacji.

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

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

Ważny

Folder zawartości zawiera folder SampleTemplate. Usuń ten folder, ponieważ został on dodany do szablonu autorskiego w celach demonstracyjnych.

Te zadania programu MSBuild zapewniają weryfikację szablonu i lokalizacji szablonów możliwości. Lokalizacja jest domyślnie wyłączona. Aby włączyć tworzenie plików lokalizacji, ustaw LocalizeTemplates na true.

Pakowanie i instalowanie

Zapisz plik projektu. Przed utworzeniem pakietu szablonu sprawdź, czy struktura folderów jest poprawna. Każdy szablon, który chcesz spakować, powinien zostać umieszczony w folderze szablonów we własnym folderze. Struktura folderów powinna wyglądać podobnie do następującej hierarchii:

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

Folder zawartości ma dwa foldery: rozszerzenia i consoleasync.

W terminalu w folderze roboczym uruchom polecenie dotnet pack. To polecenie kompiluje projekt i tworzy pakiet NuGet w folderze working\bin\Release, zgodnie z następującymi danymi wyjściowymi:

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

Następnie zainstaluj pakiet szablonu za pomocą polecenia dotnet new install. W systemie Windows:

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

W systemie Linux lub macOS:

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

Powinny zostać wyświetlone dane wyjściowe podobne do następujących:

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

Jeśli pakiet NuGet został przekazany do źródła NuGet, możesz użyć polecenia dotnet new install <PACKAGE_ID>, w którym <PACKAGE_ID> jest takie samo jak ustawienie <PackageId> z pliku .csproj.

Odinstalowywanie pakietu szablonu

Niezależnie od sposobu instalowania pakietu szablonu za pomocą pliku .nupkg bezpośrednio lub za pomocą kanału informacyjnego NuGet usunięcie pakietu szablonu jest takie samo. Użyj <PackageId> tego szablonu, który chcesz odinstalować. Listę zainstalowanych szablonów można uzyskać, uruchamiając polecenie dotnet new uninstall.

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

Uruchom dotnet new uninstall AdatumCorporation.Utility.Templates, aby odinstalować pakiet szablonu. Polecenie zwraca informacje o tym, jakie pakiety szablonów zostały odinstalowane.

Gratulacje! Zainstalowałeś i odinstalowałeś pakiet szablonu.

Następne kroki

Aby dowiedzieć się więcej na temat szablonów, z których większość już się nauczyłeś, zapoznaj się z artykułem Szablony niestandardowe dla dotnet new.