šablony .NET pro autory

Jako autor šablony vytvoříte šablony .NET – podrobné plány, které generují projekty, soubory nebo jiné prostředky z předdefinované struktury. Při spuštění dotnet new <shortName>.NET modul šablon načte šablonu a vytvoří výstup v aktuálním adresáři. Visual Studio dialogové okno Vytvořit nový projekt také používá modul šablon .NET pro .NET šablony projektu, takže šablony, které vytváříte pro rozhraní příkazového řádku, fungují i v Visual Studio.

Sada .NET SDK se dodává s integrovanými šablonami pro běžné výchozí body, jako jsou konzolové aplikace, knihovny tříd a projekty ASP.NET. Kromě těchto předdefinovaných šablon můžete vytvářet vlastní šablony a distribuovat je jako balíčky NuGet.

Tento článek je referenční informace pro autory šablon. Popisuje, jak jsou šablony strukturované, nakonfigurované a distribuované. Podrobné pokyny k vytváření a vytváření šablon balíčků najdete v části Související obsah .

Typy šablon

Modul šablon .NET podporuje tři typy šablon: šablony položek, šablony projektů a šablony řešení.

  • Šablony položek generují jeden nebo více souborů, například soubor kódu, konfigurační soubor nebo jiný zdroj, aniž by se kolem nich vygeneroval celý projekt. Šablona položky může například vytvořit soubor třídy, který přidá sadu rozšiřujících metod nebo konfigurační soubor JSON, který následuje za standardním rozložením, které váš tým používá. Informace o tom, jak vytvořit šablonu položky, najdete v tématu Kurz: Vytvoření šablony položky.

  • Project šablony generují úplnou strukturu project. Předdefinovaná šablona projektu konzoly .csproj například vytvoří soubor, Program.cs soubor a všechny ostatní soubory, které tvoří projekt. Vytvořte šablonu projektu, pokud chcete uživatelům poskytnout úplný počáteční bod projektu místo jednotlivých souborů. Informace o tom, jak vytvořit šablonu projektu, najdete v tématu Kurz: Vytvoření šablony projektu.

  • Šablony řešení generují řešení s jedním nebo více projekty. Šablona řešení může například vytvořit projekt rozhraní API spárovaný s testovacím projektem v jednom kroku.

Při vytváření vlastní šablony deklarujete jeho typ pomocí tags.type pole v konfiguračním template.json souboru. Platné hodnoty jsou "project", "item"a "solution". Tyto hodnoty umožňují uživatelům filtrovat výsledky při hledání šablon pomocí dotnet new search nebo dotnet new list.

Tip

Project a šablony řešení se zobrazí v dialogovém okně Visual Studio Vytvořit novou project, ale šablony položek se nezobrazí v dialogovém okně Přidat>novou položku. Uživatelé mají přístup k šablonům položek z rozhraní příkazového dotnet new řádku.

Struktura šablony

Šablona je složka na disku, která obsahuje dvě věci: zdrojové soubory šablony a speciální .template.config podsložku. Když uživatel spustí dotnet new <shortName>, modul šablony zkopíruje zdrojové soubory do výstupního umístění a použije pro šablonu veškerou konfiguraci, kterou jste definovali.

mytemplate/
├── console.cs
├── readme.txt
└── .template.config/
    ├── template.json
    └── icon.png

Zdrojové soubory mohou být libovolným typem souboru. Modul šablon nevyžaduje vložení speciálních tokenů nebo značek do zdrojového kódu. Používá soubory as-is, což znamená, že můžete vytvářet, spouštět a ladit zdrojový projekt šablony stejně jako normální projekt .NET projektu. Pokud chcete existující projekt převést na šablonu, přidejte .template.config/template.json do kořenového adresáře projektu soubor.

Volitelně můžete vložit náhradní tokeny vázané na parametry šablony (symboly) přímo do zdrojových souborů šablon a názvů souborů. Pokud tokeny nejsou platným zdrojovým kódem, nemůžete před nasazením jako šablony sestavit, spustit ani ladit zdrojový projekt. Tokeny nemají vliv na projekty, které uživatelé vytvářejí z nasazené šablony, protože modul šablon je během vytváření projektu nahrazuje.

Jediný požadovaný soubor uvnitř .template.config je template.json. Tento soubor říká modulu šablony vše, co potřebuje: název šablony, krátký název, autor, klasifikace a všechny parametry, které uživatelé můžou předat při vytváření ze šablony. Soubor můžete také umístit icon.png do .template.config složky. Terminál nezobrazuje ikony, ale Visual Studio zobrazí ikonu vedle šablony v dialogovém okně Vytvořit nový projekt. A 128×128 PNG funguje dobře.

Soubor template.json

Soubor template.json je jediná požadovaná část konfigurace v šabloně. Nachází se ve .template.config složce a řekne modulu šablony, jak prezentovat a zpracovat šablonu. Následující tabulka popisuje běžná povinná a volitelná pole:

Pole Typ Povinné Description
$schema identifikátor URI No Schéma JSON pro template.json. Nastavte na https://json.schemastore.org/template povolení IntelliSense v editorech, jako je Visual Studio Code.
author řetězec No Autor šablony.
classifications array(řetězec) No Značky, které uživatelé můžou použít k vyhledání šablony s dotnet new search nebo dotnet new list. Tyto hodnoty se zobrazí ve sloupci Značky v seznamu šablon.
description řetězec No Popis toho, co šablona vytvoří.
identity řetězec Ano Jedinečný identifikátor šablony.
name řetězec Ano Zobrazovaný název šablony zobrazené uživatelům.
shortName řetězec Ano Krátké jméno, které uživatelé předávají k dotnet new vytvoření ze šablony, například console nebo classlib.
sourceName řetězec No Řetězec ve zdrojových souborech a názvech souborů, které modul šablony nahradí jménem, které uživatel poskytne prostřednictvím -n nebo --name. Pokud uživatel nezadá název, modul použije aktuální název adresáře.
preferNameDirectory boolean No Když true a uživatel zadá název, ale žádný výstupní adresář, modul šablony vytvoří nový adresář s tímto názvem místo zápisu souborů do aktuálního adresáře. Výchozí hodnota je false.
tags objekt No Metadata, která identifikují vlastnosti, jako je jazyk šablony a typ. Slouží tags.language pro jazyk a tags.type pro project, itemnebo solution.

Dvě pole si zaslouží zvláštní pozornost. Pole sourceName je způsob, jakým šablony zpracovávají pojmenování: nastavte ho na řetězec, který se zobrazí v názvech souborů a zdrojovém kódu (například MyTemplate) a modul šablony nahradí všechny výskyty jakýmkoli názvem, které uživatel předá při vytváření šablony. Pole classifications řídí zjistitelnost; zvolte značky, které přesně popisují účel šablony, aby ho uživatelé mohli při hledání najít.

Tady je minimální template.json hodnota šablony konzoly:

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": [ "Common", "Console" ],
  "description": "Creates a console application.",
  "identity": "MyCompany.ConsoleTemplate.CSharp",
  "name": "My Console App",
  "shortName": "myconsole",
  "sourceName": "MyConsoleApp",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

Úplné schéma je k dispozici v úložišti schémat JSON. Pokročilé možnosti konfigurace, jako je zahrnutí podmíněného souboru, akce po vytvoření a šablony více projektů, najdete na wikiwebu dotnet/šablon GitHub y.

Parametry šablony (symboly)

Oddíl symbols v template.json části definuje parametry, které mohou uživatelé předat při vytváření ze šablony. Každý symbol se změní na dotnet new <shortName>možnost rozhraní příkazového řádku , takže se z nich stane symbol s názvem ClassName--ClassName (nebo -C pokud definujete krátký název).

Každá položka symbolu podporuje následující běžná nastavení:

Setting Description
type Musí se jednat "parameter" o parametry určené pro uživatele.
description Zobrazuje se ve výstupu nápovědy k šabloně při spuštění dotnet new <shortName> -?uživatele .
datatype Očekávaný datový typ, například "text", "bool"nebo "choice".
replaces Řetězec v obsahu zdrojového souboru, který modul šablony nahradí hodnotou parametru.
fileRename Řetězec v názvech zdrojových souborů, který modul šablony nahradí hodnotou parametru.
defaultValue Hodnota použitá v případech, kdy uživatel parametr nezadá.

fileRename Nastavení replaces a způsob nahrazení jednotek symboly. Když uživatel zadá hodnotu, modul šablony nahradí každý výskyt replaces řetězce uvnitř obsahu souboru a každý výskyt fileRename řetězce v názvech souborů. Pokud uživatel nezadá hodnotu, defaultValue použije se místo toho.

Následující symbol například umožňuje uživatelům nastavit název třídy při vytváření ze šablony. Soubor se přejmenuje a třída uvnitř souboru se aktualizuje tak, aby odpovídala:

"symbols": {
  "ClassName": {
    "type": "parameter",
    "description": "The name of the code file and class.",
    "datatype": "text",
    "replaces": "StringExtensions",
    "fileRename": "StringExtensions",
    "defaultValue": "StringExtensions"
  }
}

S tímto symbolem definovaným může uživatel spustit dotnet new <shortName> --ClassName MyHelpers , aby vytvořil soubor s názvem MyHelpers.cs třídy s názvem MyHelpers. Bez příznaku ponechá soubor a třída výchozí název StringExtensions.

Pokud chcete ověřit parametry, které šablona zpřístupňuje, předejte -? její krátký název po instalaci:

dotnet new <shortName> -?

Balíčky šablon

Balíček šablony je soubor NuGet (.nupkg), který spojuje jednu nebo více šablon dohromady. Když uživatel nainstaluje balíček šablony, modul šablon .NET zaregistruje všechny šablony uvnitř šablony najednou. Balíčky představují standardní způsob distribuce šablon. Publikování jednoho balíčku do NuGet.org nebo privátního informačního kanálu NuGet nebo sdílení místního .nupkg souboru a uživatelé získají celou kolekci jedním příkazem.

Pokud chcete vytvořit balíček šablony, použijte soubor projektu jazyka C# (.csproj) nakonfigurovaný tak, aby fungoval jako projekt balení , a ne jako kompilační projekt. Klíčové nastavení, které tuto práci dělají, jsou:

Setting Value Purpose
PackageType Template Označí balíček jako balíček šablony, aby se zobrazil ve dotnet new search výsledcích.
IncludeContentInPack true Obsahuje soubory obsahu v balíčku NuGet.
IncludeBuildOutput false Zabraňuje přidání zkompilovaných binárních souborů do balíčku.
ContentTargetFolders content Umístí složky šablony do content složky balíčku NuGet, kde je modul šablon očekává, že je najde.

Šablona templatepack projektu představuje nejjednodušší způsob, jak vytvořit projekt balení:

  1. Nainstalujte Microsoft. Balíček NuGet TemplateEngine.Authoring.Templates:

    dotnet new install Microsoft.TemplateEngine.Authoring.Templates

  2. Vytvořte projekt balení:

    dotnet new templatepack -n <PackageName>

Vygenerovaný projekt obsahuje správná .csproj nastavení, content složku pro šablony a úlohy NÁSTROJE MSBuild pro ověřování šablon a volitelnou lokalizaci.

Úplný návod k vytváření, balení a publikování balíčku šablony najdete v tématu Kurz: Vytvoření balíčku šablony.

Místní testování šablony

Během vývoje šablony nainstalujte šablonu přímo ze složky a otestujte ji, aniž byste nejprve vytvářeli balíček. Předejte cestu k adresáři, který obsahuje .template.config složku:

dotnet new install ./mytemplate/

Pokud chcete zobrazit všechny nainstalované balíčky šablon a přesný příkaz k odinstalaci jednotlivých balíčků, spusťte dotnet new uninstall bez argumentů:

dotnet new uninstall

Pokud chcete odinstalovat šablonu nainstalovanou z adresáře, předejte stejnou cestu k adresáři, jakou jste použili k instalaci:

dotnet new uninstall ./mytemplate/

Jakmile budete připraveni šablonu sdílet, zabalte ji jako balíček NuGet (viz balíčky šablon) a distribuujte ji. Uživatelé nainstalují publikovanou šablonu s dotnet new install jedním z následujících zdrojových argumentů:

  • ID balíčku NuGet, které nainstaluje nejnovější stabilní verzi ze zdrojů NuGet nakonfigurovaných pro aktuální adresář:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp

  • ID balíčku NuGet s vlastní adresou URL informačního kanálu Tato --nuget-source možnost kromě nakonfigurovaných zdrojů NuGet používá pro tuto instalaci jenom zadaný informační kanál:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json

  • Cesta k místnímu .nupkg souboru:

    dotnet new install ./AdatumCorporation.ConsoleTemplate.CSharp.1.0.0.nupkg

Warning

Šablony mohou během vytváření projektu spouštět úlohy MSBuild a libovolný kód. Nainstalujte šablony jenom ze zdrojů, kterým důvěřujete.

Pokud chcete odinstalovat balíček nainstalovaný ze zdroje NuGet nebo místního .nupkg souboru, použijte ID balíčku NuGet:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

Předdefinované šablony sady SDK se nezobrazují v seznamu odinstalace a nejde je odebrat .dotnet new uninstall

Lokalizace šablon

Modul šablon .NET podporuje volitelnou lokalizaci metadat šablony. Když zadáte lokalizační soubory, hostitelé, jako dotnet new je Visual Studio dialogové okno Nový Project, zobrazí název, popis a informace o symbolech šablony v jazyce uživatele místo původního vytvořeného jazyka.

Následující pole šablony podporují lokalizaci:

  • name
  • author
  • description
  • Symbol description a displayName
  • Popis a zobrazovaný název pro každou volbu v parametru volby
  • Publikovat akci description a manualInstructions

Pokud chcete přidat lokalizaci, vytvořte localize uvnitř .template.config podsložku a přidejte jeden soubor JSON pro každý jazyk. Pojmenujte každý soubortemplatestrings.<lang-code>.json, kde <lang-code> odpovídá platnému CultureInfo názvu, například pt-BR, nebo .dezh-Hans Každý soubor obsahuje páry klíč-hodnota, kde klíč je cesta k prvku v template.json, pomocí / jako oddělovač pro vnořená pole.

Například s následujícím obsahem template.json :

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

Soubor lokalizace brazilské templatestrings.pt-BR.json portugalštiny by vypadal 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."
}

Modul šablony tyto soubory analyzuje, když načte informace o šabloně, a vrátí lokalizované hodnoty automaticky na základě aktuální jazykové verze uživatelského rozhraní – uživatel nevyžaduje žádné další kroky.

Lokalizace je volitelná. Pokud neobsahujete lokalizační soubory, šablona funguje normálně a vždy zobrazuje hodnoty z template.json. Další informace najdete na stránce lokalizace wikiwebu dotnet/templating.

Integrace sady Visual Studio

Visual Studio dialogové okno Vytvořit nový projekt používá modul šablon .NET pro šablony projektu .NET. Šablony, které vytvoříte pro dotnet new práci v Visual Studio, i bez jakékoli další konfigurace. Když uživatel nainstaluje balíček šablony s dotnet new install, Visual Studio automaticky rozpozná a zobrazí tyto šablony v dialogovém okně.

Project a šablony řešení se zobrazí v dialogovém okně Vytvořit nový project společně s předdefinované šablony sady SDK. Uživatelé mohou najít šablony podle názvu, jazyka nebo značek z classifications pole v souboru šablony template.json . Přesné klasifikace pomáhají vaší šabloně v správných kategoriích filtru, proto je pečlivě vyberte. Pokud chcete šabloně dát elegantní vzhled v dialogovém okně, přidejte icon.png ji do .template.config složky – Visual Studio ji zobrazí vedle názvu šablony.

Šablony položek se momentálně nezobrazují v dialogovém okně Přidat>novou položku . Uživatelé můžou šablony položek dál používat s příkazem dotnet new v terminálu.

Pokud chcete, aby byla šablona zjistitelná pro Visual Studio uživatele, kteří ho ještě nenainstalovali, publikujte balíček šablony do nuget.org. Dialogové okno Vytvořit nový projekt obsahuje možnost Instalovat další šablony z možnosti online hledání, která hledá nuget.org pro balíčky šablon. Když uživatel nainstaluje balíček prostřednictvím této možnosti, Visual Studio použije stejný instalační mechanismus jako dotnet new install.

Podrobnější pokyny k integraci specifické pro Visual Studio – například řízení pořadí řazení šablon a konfigurace dalších možností specifických pro integrované vývojové prostředí – najdete v tématu Úložiště s ukázkou šablony Sayed Hashimi.

Související obsah

  • Last updated on