Vlastní šablony pro dotnet new

Článek
03/05/2024

Sada .NET SDK obsahuje mnoho již nainstalovaných šablon a je připravených k použití. Příkaz dotnet new není jenom způsob, jak použít šablonu, ale také způsob instalace a odinstalace šablon. Můžete vytvořit vlastní šablony pro libovolný typ projektu, jako je aplikace, služba, nástroj nebo knihovna tříd. Můžete dokonce vytvořit šablonu, která vypíše jeden nebo více nezávislých souborů, například konfigurační soubor.

Vlastní šablony můžete nainstalovat z balíčku NuGet do libovolného informačního kanálu NuGet, odkazováním na soubor NuGet .nupkg přímo nebo zadáním adresáře systému souborů, který obsahuje šablonu. Modul šablon nabízí funkce, které umožňují nahradit hodnoty, zahrnout a vyloučit soubory a spouštět vlastní operace zpracování při použití šablony.

Modul šablony je open source a online úložiště kódu je v dotnet/templatingu na GitHubu. Další šablony, včetně šablon od třetích stran, lze najít pomocí dotnet new search. Další informace o vytváření a používání vlastních šablon najdete v tématu Vytvoření vlastních šablon pro dotnet new a dotnet/šablonování wikiwebu úložiště GitHub.

Poznámka:

Příklady šablon jsou k dispozici v úložišti dotnet/templating GitHub.

Pokud chcete postupovat podle návodu a vytvořit šablonu, přečtěte si téma Vytvoření vlastní šablony pro nový kurz dotnet.

Výchozí šablony .NET

Při instalaci sady .NET SDK získáte více než tucet předdefinovaných šablon pro vytváření projektů a souborů, včetně konzolových aplikací, knihoven tříd, projektů testů jednotek, ASP.NET základních aplikací (včetně projektů Angular a React ) a konfiguračních souborů. Pokud chcete zobrazit seznam předdefinovaných šablon, spusťte dotnet new list příkaz:

dotnet new list

Konfigurace

Šablona se skládá z následujících částí:

Zdrojové soubory a složky
Konfigurační soubor (template.json).

Zdrojové soubory a složky

Zdrojové soubory a složky zahrnují všechny soubory a složky, které má modul šablon použít při dotnet new <TEMPLATE> spuštění příkazu. Modul šablon je navržený tak, aby jako zdrojový kód používal runnable projekty k vytváření projektů. To má několik výhod:

Modul šablon nevyžaduje vložení speciálních tokenů do zdrojového kódu projektu.
Soubory kódu nejsou speciální soubory ani upravovány žádným způsobem, aby fungovaly s modulem šablon. Nástroje, které obvykle používáte při práci s projekty, tedy pracují také s obsahem šablony.
Sestavíte, spustíte a ladíte projekty šablon stejně jako u všech ostatních projektů.
Šablonu můžete rychle vytvořit z existujícího projektu tak, že do projektu přidáte konfigurační soubor ./.template.config/template.json .

Soubory a složky uložené v šabloně nejsou omezeny na formální typy projektů .NET. Zdrojové soubory a složky se můžou skládat z libovolného obsahu, který chcete vytvořit při použití šablony, i když modul šablony vytvoří jako výstup jenom jeden soubor.

Soubory vygenerované šablonou je možné upravit na základě logiky a nastavení, která jste zadali v konfiguračním souboru template.json . Uživatel může tato nastavení přepsat předáním možností příkazu dotnet new <TEMPLATE> . Běžným příkladem vlastní logiky je zadání názvu třídy nebo proměnné v souboru kódu, který je nasazený šablonou.

template.json

Soubor template.json se umístí do složky .template.config v kořenovém adresáři šablony. Soubor poskytuje konfigurační informace modulu šablony. Minimální konfigurace vyžaduje členy uvedené v následující tabulce, což stačí k vytvoření funkční šablony.

Člen	Typ	Popis
`$schema`	Identifikátor URI	Schéma JSON pro soubor template.json . Editory, které podporují schémata JSON, umožňují při zadání schématu funkce pro úpravy JSON. Visual Studio Code například vyžaduje, aby tento člen povolil IntelliSense. Použijte hodnotu `http://json.schemastore.org/template`.
`author`	string	Autor šablony.
`classifications`	array(řetězec)	Nulová nebo více charakteristik šablony, kterou může uživatel použít k vyhledání šablony při hledání. Klasifikace se také zobrazí ve sloupci Značky , když se zobrazí v seznamu šablon vytvořených pomocí `dotnet new list` příkazu.
`identity`	string	Jedinečný název této šablony.
`name`	string	Název šablony, kterou by uživatelé měli vidět.
`shortName`	string	Výchozí zkrácený název pro výběr šablony, která se vztahuje na prostředí, kde je název šablony určen uživatelem, není vybrán prostřednictvím grafického uživatelského rozhraní. Krátký název je například užitečný při použití šablon z příkazového řádku s příkazy rozhraní příkazového řádku.
`sourceName`	string	Název ve zdrojovém stromu, který se má nahradit jménem, které uživatel určí. Modul šablony vyhledá jakýkoli výskyt `sourceName` uvedeného v konfiguračním souboru a nahradí ho názvy souborů a obsahem souboru. Hodnotu, kterou chcete nahradit, můžete při spuštění šablony zadat pomocí `-n` možností.`--name` Pokud není zadán žádný název, použije se aktuální adresář.
`preferNameDirectory`	Logická hodnota	Určuje, jestli se má vytvořit adresář pro šablonu, pokud je zadaný název, ale výstupní adresář není nastavený (místo vytvoření obsahu přímo v aktuálním adresáři). Výchozí hodnota je false.

Úplné schéma souboru template.json se nachází v úložišti schémat JSON. Další informace o souboru template.json najdete na wikiwebu šablon dotnet. Podrobnější příklady a informace o tom, jak zobrazit šablony v sadě Visual Studio, najdete v prostředcích, které Sayed Hashimi vytvořil.

Příklad

Tady je například složka šablony, která obsahuje dva soubory obsahu: console.cs a readme.txt. K dispozici je také požadovaná složka s názvem .template.config , která obsahuje soubor template.json .

└───mytemplate
    │   console.cs
    │   readme.txt
    │
    └───.template.config
            template.json

Soubor template.json vypadá takto:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Travis Chau",
  "classifications": [ "Common", "Console" ],
  "identity": "AdatumCorporation.ConsoleTemplate.CSharp",
  "name": "Adatum Corporation Console Application",
  "shortName": "adatumconsole"
}

Složka mytemplate je instalovatelný balíček šablony. Jakmile je balíček nainstalovaný, shortName můžete ho použít s příkazem dotnet new . Výstupem by byly například dotnet new adatumconsole soubory a readme.txt soubory do aktuální console.cs složky.

Lokalizace šablon

Šablony .NET jsou lokalizovatelné. Pokud je šablona lokalizovaná pro jazyk odpovídající aktuálnímu národnímu prostředí, zobrazí se jeho prvky ve stejném jazyce jako rozhraní příkazového řádku. Lokalizace je volitelná při vytváření nových šablon.

Lokalizovatelné elementy v šabloně jsou:

Název
Autor
Popis
Symboly
- Popis
- Zobrazovaný název
- Popisy a zobrazovaný název voleb pro parametry voleb
Publikování akcí
- Popis
- Ruční pokyny

Lokalizační soubory mají formát JSON a jeden soubor na jazykovou verzi by měl existovat. Konvence vytváření názvů je: templatestrings.<lang code>.json, kde lang code odpovídá jedné z možností CultureInfo . Všechny lokalizační soubory by měly být ve .template-config\localize složce.

Kód JSON lokalizace se skládá z párů klíč-hodnota:

Klíčem je odkaz na prvek template.json , který se má lokalizovat. Pokud je prvek podřízený, použijte úplnou cestu s oddělovačem / .
Hodnota je lokalizační řetězec elementu zadaného klíčem.

Další informace o lokalizaci šablon najdete na stránce lokalizace wikiwebu dotnet.

Příklad

Tady je například template.json soubor s některými lokalizovatelnými poli:

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

A některá pole se mají lokalizovat do brazilské portugalštiny. Název souboru bude templatestrings.pt-BR.json odpovídat jazykové verzi a bude vypadat takto:

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

Zabalení šablony do balíčku NuGet (soubor nupkg)

Vlastní šablona je zabalena příkazem dotnet pack a souborem .csproj . Alternativně můžete NuGet použít s příkazem nuget pack spolu se souborem .nuspec . NuGet však vyžaduje rozhraní .NET Framework ve Windows a Mono v Linuxu a macOS.

Soubor .csproj se mírně liší od tradičního souboru .csproj projektu kódu. Všimněte si těchto nastavení:

Toto <PackageType> nastavení se přidá a nastaví na Templatehodnotu .
Nastavení <PackageVersion> se přidá a nastaví na platné číslo verze NuGet.
Nastavení <PackageId> se přidá a nastaví na jedinečný identifikátor. Tento identifikátor slouží k odinstalaci balíčku šablony a používá ho informační kanály NuGet k registraci balíčku šablon.
Obecná nastavení metadat by měla být nastavena: <Title>, <Authors>, <Description>a <PackageTags>.
Nastavení <TargetFramework> se musí nastavit, i když se nepoužívá binární soubor vytvořený procesem šablony. V následujícím příkladu je nastavená na netstandard2.0.

Balíček šablony ve formě balíčku NuGet .nupkg vyžaduje, aby všechny šablony byly uloženy ve složce obsahu v balíčku. Existuje několik dalších nastavení pro přidání do souboru .csproj , aby se zajistilo, že vygenerovaný soubor .nupkg lze nainstalovat jako balíček šablon:

Nastavení <IncludeContentInPack> je nastaveno tak, aby true zahrnovalo libovolný soubor, který projekt nastaví jako obsah v balíčku NuGet.
Nastavení <IncludeBuildOutput> je nastaveno tak, aby false se vyloučily všechny binární soubory generované kompilátorem z balíčku NuGet.
Nastavení <ContentTargetFolders> je nastaveno na contenthodnotu . Tím se zajistí, že soubory nastavené jako obsah jsou uloženy ve složce obsahu v balíčku NuGet. Tato složka v balíčku NuGet je analyzována systémem šablon dotnet.

Snadný způsob, jak vyloučit všechny soubory kódu zkompilování projektem šablony, je použití <Compile Remove="**\*" /> položky v souboru projektu uvnitř elementu <ItemGroup> .

Snadnou strukturou balíčku šablon je umístit všechny šablony do jednotlivých složek a potom všechny složky šablony uvnitř složky šablon , která se nachází ve stejném adresáři jako soubor .csproj . Tímto způsobem můžete použít jednu položku projektu k zahrnutí všech souborů a složek do šablon jako obsahu. Uvnitř elementu <ItemGroup> vytvořte <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> položku.

Tady je příklad souboru .csproj , který dodržuje všechny tyto pokyny. Zabalí podřízenou složku šablon do složky balíčku obsahu a vyloučí zkompilování jakéhokoli souboru kódu.

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

  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0</PackageVersion>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <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>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
  </PropertyGroup>

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

</Project>

Následující příklad ukazuje strukturu souborů a složek pomocí .csproj k vytvoření balíčku šablony. Složka MyDotnetTemplates.csproj se nachází v kořenovém adresáři adresáře s názvem project_folder. Složka šablon obsahuje dvě šablony, mytemplate1 a mytemplate2. Každá šablona obsahuje soubory obsahu a složku .template.config s konfiguračním souborem template.json .

project_folder
│   MyDotnetTemplates.csproj
│
└───templates
    ├───mytemplate1
    │   │   console.cs
    │   │   readme.txt
    │   │
    │   └───.template.config
    │           template.json
    │
    └───mytemplate2
        │   otherfile.cs
        │
        └───.template.config
                template.json

Poznámka:

Pokud chcete zajistit, aby se balíček šablony zobrazil ve dotnet new search výsledku, nastavte typ balíčku NuGet na Templatehodnotu .

Instalace balíčku šablony

Pomocí příkazu dotnet new install nainstalujte balíček šablony.

Instalace balíčku šablony z balíčku NuGet uloženého na nuget.org

K instalaci balíčku šablony použijte identifikátor balíčku NuGet.

dotnet new install <NUGET_PACKAGE_ID>

Instalace balíčku šablony z vlastního zdroje NuGet

Zadejte vlastní zdroj NuGet (například https://api.my-custom-nuget.com/v3/index.json).

dotnet new install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>

Instalace balíčku šablony z místního souboru nupkg

Zadejte cestu k souboru balíčku NuGet .nupkg .

dotnet new install <PATH_TO_NUPKG_FILE>

Instalace balíčku šablony z adresáře systému souborů

Šablony lze nainstalovat ze složky šablony, například ze složky mytemplate1 z předchozího příkladu. Zadejte cestu ke složce .template.config . Cesta k adresáři šablony nemusí být absolutní.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Získání seznamu nainstalovaných balíčků šablon

Příkaz uninstall bez jakýchkoli dalších parametrů obsahuje seznam všech nainstalovaných balíčků šablon a zahrnutých šablon.

dotnet new uninstall

Tento příkaz vrátí něco podobného následujícímu výstupu:

Currently installed items:
   Microsoft.Azure.WebJobs.ProjectTemplates
      Version: 4.0.1942
      Details:
         Author: Microsoft
         NuGetSource: https://api.nuget.org/v3/index.json
      Templates:
         Azure Functions (func) C#
         Azure Functions (func) F#
      Uninstall Command:
         dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...

První úroveň položek po Currently installed items: identifikátorech použitých při odinstalaci balíčku šablony. A v předchozím příkladu Microsoft.Azure.WebJobs.ProjectTemplates je uvedený. Pokud byl balíček šablony nainstalován pomocí cesty systému souborů, tento identifikátor je cesta ke složce složky .template.config . V seznamu se zobrazí jenom balíčky šablony nainstalované prostřednictvím dotnet new install . Balíčky šablon, které jsou integrované do sady .NET SDK, se nezobrazují.

Odinstalace balíčku šablony

K odinstalaci balíčku šablony použijte příkaz dotnet new uninstall .

Pokud byl balíček nainstalován buď informačním kanálem NuGet, nebo přímo souborem .nupkg , zadejte identifikátor.

dotnet new uninstall <NUGET_PACKAGE_ID>

Pokud byl balíček nainstalován zadáním cesty ke složce .template.config , použijte tuto cestu k odinstalaci balíčku. Absolutní cestu k balíčku šablony můžete zobrazit ve výstupu poskytnutém příkazem dotnet new uninstall . Další informace najdete v části Získání seznamu nainstalovaných šablon .

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Vytvoření projektu pomocí vlastní šablony

Po instalaci šablony použijte šablonu spuštěním dotnet new <TEMPLATE> příkazu stejně jako u jakékoli jiné předinstalované šablony. Můžete také zadat možnosti dotnet new příkazu, včetně možností specifických pro šablonu, které jste nakonfigurovali v nastavení šablony. Zadejte krátký název šablony přímo do příkazu:

dotnet new <TEMPLATE>

Sdílet prostřednictvím

Vlastní šablony pro dotnet new

Výchozí šablony .NET

Konfigurace

Zdrojové soubory a složky

template.json

Příklad

Lokalizace šablon

Příklad

Zabalení šablony do balíčku NuGet (soubor nupkg)

Instalace balíčku šablony

Instalace balíčku šablony z balíčku NuGet uloženého na nuget.org

Instalace balíčku šablony z vlastního zdroje NuGet

Instalace balíčku šablony z místního souboru nupkg

Instalace balíčku šablony z adresáře systému souborů

Získání seznamu nainstalovaných balíčků šablon

Odinstalace balíčku šablony

Vytvoření projektu pomocí vlastní šablony

Viz také

Další materiály