Sdílet prostřednictvím

Kurz: Vytvoření balíčku šablony

  • Článek

Pomocí .NET můžete vytvářet a nasazovat šablony, které generují projekty, soubory a dokonce i prostředky. Tento kurz je třetí částí série, která vás naučí, jak vytvořit, nainstalovat a odinstalovat šablony pro použití s příkazem dotnet new.

Dokončenou šablonu si můžete prohlédnout v úložišti GitHubu s ukázkami .NET .

V této části série se naučíte:

Požadavky

  • Dokončete část 1 a část 2 této tutoriálové série.

    V tomto kurzu se používají dvě šablony vytvořené v prvních dvou částech této série kurzů. Pokud šablonu zkopírujete jako složku, můžete použít jinou šablonu do složky working\content.

  • Otevřete terminál a přejděte do pracovní složky.

  • Nainstalujte .NET 8 nebo .NET 9.

  • Nainstalujte šablonu Microsoft.TemplateEngine.Authoring.Templates z kanálu balíčků NuGet.

    • Z terminálu spusťte příkaz dotnet new install Microsoft.TemplateEngine.Authoring.Templates.

Vytvořte projekt balíčku šablony

Balíček šablony je jedna nebo více šablon zabalených do balíčku NuGet. Při instalaci nebo odinstalaci balíčku šablony se přidají nebo odeberou všechny šablony obsažené v balíčku.

Balíčky šablon jsou reprezentovány souborem NuGet (.nupkg). Stejně jako jakýkoli balíček NuGet můžete balíček šablony nahrát do informačního kanálu NuGet. Příkaz dotnet new install podporuje instalaci balíčků šablon z informačního kanálu balíčků NuGet, souboru .nupkg nebo adresáře se šablonou.

Soubor projektu jazyka C# obvykle používáte ke kompilaci kódu a vytvoření binárního souboru. Projekt se ale dá použít také k vygenerování balíčku šablony. Změnou nastavení .csprojmůžete zabránit kompilaci kódu a místo toho zahrnout veškeré zdroje vašich šablon jako prostředky. Když je tento projekt sestaven, vytvoří balíček NuGet šablony.

Balíček, který vygenerujete, bude obsahovat položku a šablony projektu , které byly vytvořeny dříve.

Balíček Microsoft.TemplateEngine.Authoring.Templates obsahuje šablony užitečné pro vytváření šablon. Pokud chcete tento balíček nainstalovat, měl by být nuget.org dostupný jako informační kanál NuGet v pracovním adresáři.

  1. V pracovní složce vytvořte balíček šablony spuštěním následujícího příkazu:

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

    Parametr -n nastaví název souboru projektu na AdatumCorporation.Utility.Templates.csproj. Měl by se zobrazit výsledek podobný následujícímu výstupu.

    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. Dále otevřete soubor AdatumCorporation.Utility.Templates.csproj v editoru kódu a naplňte ho podle tipů v šabloně:

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

Popis xml projektu

Nastavení v <PropertyGroup> v fragmentu kódu XML se rozdělí do dvou skupin.

První skupina se zabývá vlastnostmi požadovanými pro balíček NuGet. Čtyři nastavení <Package*> souvisejí s vlastnostmi balíčku NuGet, které slouží k identifikaci vašeho balíčku ve zdroji NuGet. Hodnota <PackageId>, zatímco ji používá NuGet, se používá také k odinstalaci balíčku šablony. Zbývající nastavení, jako jsou <Title> a <PackageTags>, souvisejí s metadaty zobrazenými v informačním kanálu NuGet a ve správci balíčků .NET. Další informace o nastavení NuGet a vlastnostech MSBuild naleznete v tématu NuGet a MSBuild.

Poznámka

Chcete-li zajistit, aby se balíček šablony zobrazil ve výsledcích dotnet new search, musí být <PackageType> nastaven na Template.

Ve druhé skupině nastavení <TargetFramework> zajistí správné spuštění nástroje MSBuild při spuštění příkazu pack pro kompilaci a zabalení projektu. Tato skupina také obsahuje nastavení, která je potřeba udělat s konfigurací projektu tak, aby při vytváření zahrnovala šablony do příslušné složky v balíčku NuGet:

  • Nastavení <NoWarn> potlačí upozornění, které se nevztahuje na projekty balíčků šablon.

  • Nastavení <NoDefaultExcludes> zajišťuje, aby soubory a složky, které začínají . (například .gitignore), byly součástí šablony. Výchozí chování balíčků NuGet je ignorovat tyto soubory a složky.

<ItemGroup> obsahuje dvě položky. Nejprve položka <Content> obsahuje vše, co je ve složce se šablonami , jako obsah. Je také nastavená tak, že vyloučí všechny složky bin nebo obj složku, aby se zabránilo zahrnutí jakéhokoli kompilovaného kódu (pokud jste otestovali a zkompilovali šablony). Za druhé <Compile> položka vyloučí všechny soubory kódu z kompilace bez ohledu na to, kde se nacházejí. Toto nastavení brání projektu, který se používá k vytvoření balíčku šablony, aby se pokusil zkompilovat kód v hierarchii šablon složek.

Spropitné

Další informace o nastavení metadat NuGet najdete v tématu Balení šablony do balíčku NuGet (soubor nupkg).

Vytvořený soubor projektu obsahuje šablony pro vytváření úkolů MSBuild a nastavení lokalizace.

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

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

Důležitý

Složka pro obsah obsahuje složku SampleTemplate. Odstranit tuto složku, protože byla přidána do šablony pro vytváření pro demonstrační účely.

Tyto úlohy nástroje MSBuild poskytují ověřování šablon a lokalizaci schopností šablon. Lokalizace je ve výchozím nastavení zakázaná. Chcete-li povolit vytváření lokalizačních souborů, nastavte LocalizeTemplates na true.

Balení a instalace

Uložte soubor projektu. Před sestavením balíčku šablony ověřte správnost struktury složek. Šablony, které chcete zabalit, umístěte do složky šablon, každou do vlastní složky. Struktura složek by měla vypadat podobně jako v následující hierarchii:

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

Složka obsahu má dvě složky: rozšíření a consoleasync.

V terminálu spusťte příkaz dotnet pack z pracovní složky. Tento příkaz sestaví projekt a vytvoří balíček NuGet ve složce working\bin\Release, jak je uvedeno v následujícím výstupu:

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

Dále nainstalujte balíček šablony pomocí příkazu dotnet new install. V systému Windows

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

V Linuxu nebo macOS:

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

Měl by se zobrazit výstup podobný následujícímu:

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

Pokud jste balíček NuGet nahráli do informačního kanálu NuGet, můžete použít příkaz dotnet new install <PACKAGE_ID>, ve kterém je <PACKAGE_ID> stejné jako nastavení <PackageId> ze souboru .csproj.

Odinstalujte balíček šablony

Bez ohledu na to, jak jste nainstalovali balíček šablon, ať už přímo se souborem .nupkg nebo prostřednictvím zdroje NuGet, postup pro odebrání balíčku šablon je stejný. Použijte <PackageId> šablony, kterou chcete odinstalovat. Seznam šablon, které jsou nainstalovány, můžete získat spuštěním příkazu 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

Spuštěním dotnet new uninstall AdatumCorporation.Utility.Templates odinstalujte balíček šablony. Příkaz vypíše informace o tom, jaké balíčky šablony byly odinstalovány.

Blahopřejeme! Nainstalovali jste a odinstalovali balíček šablony.

Další kroky

Další informace o šablonách, z nichž většinu jste se již naučili, najdete v článku Vlastní šablony pro dotnet nové.