Vlastní šablony pro dotnet new

Sada .NET SDK obsahuje mnoho již nainstalovaných šablon a je připravených k použití. Příkazdotnet 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/templating GitHub repo Wiki.

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 tutoriál Vytvoření vlastní šablony pro příkaz dotnet new.

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 soubortemplate.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`	řetězec	Autor šablony.
`classifications`	array(řetězec)	Nulové nebo více charakteristik šablony, které může uživatel použít k nalezení šablony, když ji hledá. Klasifikace se také zobrazí ve sloupci Značky , když se zobrazí v seznamu šablon vytvořených pomocí `dotnet new list` příkazu.
`identity`	řetězec	Jedinečný název této šablony.
`name`	řetězec	Název šablony, kterou by uživatelé měli vidět.
`shortName`	řetězec	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 v příkazovém řádku s CLI příkazy.
`sourceName`	řetězec	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. Hodnota, která má být nahrazena, může být zadána při spuštění šablony pomocí možností `-n` nebo `--name`. Pokud není zadán žádný název, použije se aktuální adresář.
`preferNameDirectory`	logický	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 wiki š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 lze použít s příkazem dotnet new. Například dotnet new adatumconsole by zapisoval soubory console.cs a readme.txt do aktuální 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 zobrazený název možností pro parametrické volby
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ý prvek, použijte kompletní 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 soubortemplate.json 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."
    }
  }
}

Některá pole je třeba lokalizovat na brazilskou portugalštinu. 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 následujících nastavení:

Toto <PackageType> nastavení je přidáno a nastaveno na Template.
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 content. 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 před zkompilováním vaším projektovým šablonovým souborem, je použití položky <Compile Remove="**\*" /> 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 předvádí strukturu souborů a složek za účelem vytvoření balíčku šablony pomocí .csproj. The soubor MyDotnetTemplates.csproj a složka templates se oba nacházejí v kořenovém adresáři 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 souboremtemplate.json.

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

Poznámka:

Aby bylo zajištěno, že se balíček šablony zobrazí ve výsledku dotnet new search, nastavte typ balíčku NuGet na Template.

Instalace balíčku šablony

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

Výstraha

Šablony můžou při aktivaci spustit kód MSBuild, neinstalovat ani spouštět nedůvěryhodné šablony .NET.

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: jsou identifikátory používané při odinstalaci balíčku šablony. V předchozím příkladu je uvedený Microsoft.Azure.WebJobs.ProjectTemplates. Pokud byl balíček šablony nainstalován pomocí cesty systému souborů, pak tento identifikátor představuje cestu ke složce .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í.

Odinstalujte balíček š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žnostidotnet 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>

Viz také

Váš názor

Byla tato stránka užitečná?

Last updated on 2024-03-05

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

Odinstalujte balíček šablony

Vytvoření projektu pomocí vlastní šablony

Viz také

Váš názor

Další materiály