szablony .NET dla autorów

Jako autor szablonu tworzysz szablony .NET — strategie, które generują projekty, pliki lub inne zasoby ze wstępnie zdefiniowanej struktury. Gdy użytkownicy uruchamiają polecenie dotnet new <shortName>, aparat szablonu .NET odczytuje szablon i generuje dane wyjściowe w bieżącym katalogu. Visual Studio okno dialogowe Tworzenie nowego projektu używa również aparatu szablonów .NET dla szablonów projektów .NET, więc szablony tworzone dla interfejsu wiersza polecenia działają również w Visual Studio.

Zestaw SDK .NET jest dostarczany z wbudowanymi szablonami dla typowych punktów początkowych, takich jak aplikacje konsolowe, biblioteki klas i projekty ASP.NET. Poza tymi wbudowanymi szablonami możesz tworzyć własne szablony i rozpowszechniać je jako pakiety NuGet.

Ten artykuł jest dokumentacją dla autorów szablonów. Obejmuje ona sposób, w jaki szablony są ustrukturyzowane, konfigurowane i dystrybuowane. Aby uzyskać instrukcje krok po kroku dotyczące tworzenia i tworzenia szablonów pakietów, zobacz sekcję Powiązana zawartość .

Typy szablonów

Aparat szablonów .NET obsługuje trzy typy szablonów: szablony elementów, szablony projektów i szablony rozwiązań.

  • Szablony elementów generują jeden lub więcej plików, takich jak plik kodu, plik konfiguracji lub inny zasób, bez generowania całego projektu wokół nich. Na przykład szablon elementu może utworzyć plik klasy, który dodaje zestaw metod rozszerzenia lub plik konfiguracji JSON zgodny ze standardowym układem używanym przez zespół. Aby dowiedzieć się, jak utworzyć szablon elementu, zobacz Samouczek: tworzenie szablonu elementu.

  • Project szablony generują kompletną strukturę project. Wbudowany szablon projektu konsoli, na przykład, tworzy .csproj plik, Program.cs plik i inne pliki tworzące projekt. Utwórz szablon projektu, gdy chcesz dać użytkownikom pełny punkt wyjścia projektu, a nie poszczególne pliki. Aby dowiedzieć się, jak utworzyć szablon projektu, zobacz Samouczek: tworzenie szablonu projektu.

  • Szablony rozwiązań generują rozwiązanie z co najmniej jednym projektem. Na przykład szablon rozwiązania może utworzyć projekt interfejsu API sparowany z projektem testowym w jednym kroku.

Podczas tworzenia własnego szablonu należy zadeklarować jego typ przy użyciu tags.type pola w template.json pliku konfiguracji. Prawidłowe wartości to "project", "item"i "solution". Te wartości umożliwiają użytkownikom filtrowanie wyników podczas wyszukiwania szablonów za pomocą dotnet new search polecenia lub dotnet new list.

Wskazówka

Project i szablony rozwiązań są wyświetlane w oknie dialogowym Visual Studio Tworzenie nowego project, ale szablony elementów nie są wyświetlane w oknie dialogowym Dodawanie>nowego elementu. Użytkownicy mogą uzyskiwać dostęp do szablonów elementów za pomocą interfejsu dotnet new wiersza polecenia.

Struktura szablonu

Szablon to folder na dysku zawierający dwie elementy: pliki źródłowe szablonu i specjalny .template.config podfolder. Gdy użytkownik uruchomi dotnet new <shortName>program , aparat szablonu kopiuje pliki źródłowe do lokalizacji wyjściowej i stosuje dowolną konfigurację zdefiniowaną dla szablonu.

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

Pliki źródłowe mogą być dowolnym typem pliku. Aparat szablonu nie wymaga wstrzykiwania specjalnych tokenów ani znaczników do kodu źródłowego. Używa on plików as-is, co oznacza, że można kompilować, uruchamiać i debugować projekt źródłowy szablonu dokładnie tak jak normalny projekt .NET. Aby przekształcić istniejący projekt w szablon, dodaj .template.config/template.json plik do katalogu głównego projektu.

Opcjonalnie można wstrzyknąć tokeny podstawienia powiązane z parametrami szablonu (symbolami) bezpośrednio do plików źródłowych szablonu i nazw plików. Jeśli tokeny nie są prawidłowym kodem źródłowym, nie można kompilować, uruchamiać ani debugować projektu źródłowego przed wdrożeniem go jako szablonu. Tokeny nie mają wpływu na projekty tworzone przez użytkowników na podstawie wdrożonego szablonu, ponieważ aparat szablonu zastępuje je podczas tworzenia projektu.

Jedynym wymaganym plikiem wewnątrz .template.config jest template.json. Ten plik informuje aparat szablonu o wszystkim, czego potrzebuje: nazwa szablonu, krótka nazwa, autor, klasyfikacje i wszystkie parametry, które użytkownicy mogą przekazać podczas tworzenia na podstawie szablonu. Możesz również umieścić icon.png plik w folderze .template.config . W terminalu nie są wyświetlane ikony, ale Visual Studio wyświetla ikonę obok szablonu w oknie dialogowym Tworzenie nowego projektu. 128×128 PNG działa dobrze.

Plik template.json

Plik template.json jest jedynym wymaganym elementem konfiguracji w szablonie. Znajduje się on w folderze .template.config i informuje aparat szablonu o sposobie prezentowania i przetwarzania szablonu. W poniższej tabeli opisano typowe pola wymagane i opcjonalne:

Pole Typ Wymagane Description
$schema URI Nie. Schemat JSON dla elementu template.json. Ustaw wartość na , aby https://json.schemastore.org/template włączyć funkcję IntelliSense w edytorach, takich jak Visual Studio Code.
author ciąg Nie. Autor szablonu.
classifications array(string) Nie. Tagi, których użytkownicy mogą używać do znajdowania szablonu za pomocą dotnet new search polecenia lub dotnet new list. Te wartości są wyświetlane w kolumnie Tagi listy szablonów.
description ciąg Nie. Opis tworzenia szablonu.
identity ciąg Tak Unikatowy identyfikator szablonu.
name ciąg Tak Nazwa wyświetlana szablonu wyświetlana dla użytkowników.
shortName ciąg Tak Krótka nazwa, która jest przekazywana przez użytkowników do dotnet new utworzenia na podstawie szablonu, takiego jak console lub classlib.
sourceName ciąg Nie. Ciąg w plikach źródłowych i nazwach plików, które aparat szablonu zastępuje nazwą podaną przez użytkownika za pośrednictwem metody -n lub --name. Jeśli użytkownik nie podaje nazwy, aparat używa bieżącej nazwy katalogu.
preferNameDirectory boolean Nie. Gdy true i użytkownik podaje nazwę, ale nie katalog wyjściowy, aparat szablonu tworzy nowy katalog o tej nazwie zamiast zapisywać pliki w bieżącym katalogu. Wartość domyślna to false.
tags obiekt Nie. Metadane identyfikujące właściwości, takie jak język szablonu i typ. Użyj dla tags.language języka i tags.type dla project, itemlub solution.

Dwa pola zasługują na szczególną uwagę. Pole sourceName to sposób obsługi nazewnictwa szablonów: ustaw go na ciąg wyświetlany w nazwach plików i kodzie źródłowym (takim jak MyTemplate), a aparat szablonu zastępuje każde wystąpienie dowolną nazwą przekazywaną przez użytkownika podczas tworzenia szablonu. Pole steruje odnajdywaniem. Wybierz classifications tagi, które dokładnie opisują przeznaczenie szablonu, aby użytkownicy mogli je znaleźć podczas wyszukiwania.

Oto minimum template.json szablonu konsoli:

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

Pełny schemat jest dostępny w magazynie schematów JSON. Aby uzyskać zaawansowane opcje konfiguracji, takie jak dołączanie plików warunkowych, akcje po utworzeniu i szablony wieloprojektowe, zobacz witrynę typu wiki dotnet/templating GitHub.

Parametry szablonu (symbole)

Sekcja symbols w sekcji template.json definiuje parametry, które użytkownicy mogą przekazać podczas tworzenia na podstawie szablonu. Każdy symbol staje się opcją interfejsu wiersza polecenia w systemie dotnet new <shortName>, więc symbol o nazwie ClassName staje się --ClassName (lub -C jeśli definiujesz krótką nazwę).

Każdy wpis symboli obsługuje następujące typowe ustawienia:

Setting Description
type Musi być "parameter" przeznaczony dla parametrów przeznaczonych dla użytkownika.
description Wyświetlane w danych wyjściowych pomocy szablonu, gdy użytkownicy uruchamiają polecenie dotnet new <shortName> -?.
datatype Oczekiwany typ danych, taki jak "text", "bool"lub "choice".
replaces Ciąg w zawartości pliku źródłowego, który aparat szablonu zastępuje wartością parametru.
fileRename Ciąg w nazwach plików źródłowych, który aparat szablonu zastępuje wartością parametru.
defaultValue Wartość używana, gdy użytkownik nie podaje parametru.

Ustawienia replaces i fileRename to sposób zastępowania symboli. Gdy użytkownik podaje wartość, aparat szablonu zastępuje każde wystąpienie replaces ciągu wewnątrz zawartości pliku i każde wystąpienie fileRename ciągu w nazwach plików. Jeśli użytkownik nie podaje wartości, zamiast tego zostanie użyta defaultValue wartość .

Na przykład następujący symbol umożliwia użytkownikom ustawienie nazwy klasy podczas tworzenia na podstawie szablonu. Nazwa pliku zostanie zmieniona i klasa wewnątrz pliku zostanie zaktualizowana tak, aby była zgodna z następującymi elementami:

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

Po zdefiniowaniu tego symbolu użytkownik może uruchomić polecenie dotnet new <shortName> --ClassName MyHelpers w celu utworzenia pliku o nazwie zawierającej klasę o nazwie MyHelpers.csMyHelpers. Bez flagi plik i klasa zachowają domyślną nazwę StringExtensions.

Aby sprawdzić parametry udostępniane przez szablon, po zainstalowaniu szablonu przekaż -? jego krótką nazwę:

dotnet new <shortName> -?

Pakiety szablonów

Pakiet szablonu to plik NuGet (.nupkg), który łączy jeden lub więcej szablonów. Gdy użytkownik zainstaluje pakiet szablonu, aparat szablonu .NET rejestruje każdy szablon wewnątrz niego jednocześnie. Pakiety to standardowy sposób dystrybuowania szablonów. Opublikuj pojedynczy pakiet, aby NuGet.org lub prywatny kanał informacyjny NuGet albo udostępnić plik lokalny .nupkg , a użytkownicy otrzymają całą kolekcję za pomocą jednego polecenia.

Aby utworzyć pakiet szablonu, użyj pliku projektu języka C# (.csproj) skonfigurowanego do działania jako projekt pakietu , a nie projektu kompilacji. Kluczowe ustawienia, które sprawiają, że ta praca jest następująca:

Setting Wartość Purpose
PackageType Template Oznacza pakiet jako pakiet szablonu, aby był wyświetlany w dotnet new search wynikach.
IncludeContentInPack true Zawiera pliki zawartości w pakiecie NuGet.
IncludeBuildOutput false Zapobiega dodawaniu skompilowanych plików binarnych do pakietu.
ContentTargetFolders content Umieszcza foldery szablonów w content folderze pakietu NuGet, który jest miejscem, w którym aparat szablonu oczekuje ich znalezienia.

Szablon templatepack projektu zapewnia najprostszy sposób tworzenia projektu pakowania:

  1. Zainstaluj Microsoft. Pakiet NuGet TemplateEngine.Authoring.Templates:

    dotnet new install Microsoft.TemplateEngine.Authoring.Templates

  2. Utwórz projekt tworzenia pakietów:

    dotnet new templatepack -n <PackageName>

Wygenerowany projekt zawiera prawidłowe .csproj ustawienia, content folder dla szablonów oraz zadania programu MSBuild na potrzeby weryfikacji szablonu i opcjonalnej lokalizacji.

Aby zapoznać się z pełnym przewodnikiem tworzenia, pakowania i publikowania pakietu szablonu, zobacz Samouczek: tworzenie pakietu szablonu.

Lokalne testowanie szablonu

Podczas tworzenia szablonu zainstaluj szablon bezpośrednio z jego folderu, aby go przetestować bez wcześniejszego kompilowania pakietu. Przekaż ścieżkę do katalogu zawierającego .template.config folder:

dotnet new install ./mytemplate/

Aby wyświetlić wszystkie zainstalowane pakiety szablonów i dokładne polecenie do odinstalowania każdego z nich, uruchom polecenie dotnet new uninstall bez argumentów:

dotnet new uninstall

Aby odinstalować szablon zainstalowany z katalogu, przekaż tę samą ścieżkę katalogu, która została użyta do jego zainstalowania:

dotnet new uninstall ./mytemplate/

Gdy wszystko będzie gotowe do udostępnienia szablonu, spakuj go jako pakiet NuGet (zobacz Pakiety szablonów) i rozpowszechnij go. Użytkownicy instalują opublikowany szablon za pomocą polecenia dotnet new install i jeden z następujących argumentów źródłowych:

  • Identyfikator pakietu NuGet, który instaluje najnowszą stabilną wersję ze źródeł NuGet skonfigurowanych dla bieżącego katalogu:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp

  • Identyfikator pakietu NuGet z niestandardowym adresem URL kanału informacyjnego. Opcja --nuget-source używa określonego źródła danych oprócz skonfigurowanych źródeł NuGet tylko dla tej instalacji:

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

  • Ścieżka do pliku lokalnego .nupkg :

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

Warning

Szablony mogą uruchamiać zadania programu MSBuild i dowolny kod podczas tworzenia projektu. Zainstaluj tylko szablony ze zaufanych źródeł.

Aby odinstalować pakiet zainstalowany ze źródła NuGet lub pliku lokalnego .nupkg , użyj identyfikatora pakietu NuGet:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

Wbudowane szablony zestawu SDK nie są wyświetlane na liście dezinstalacji i nie można ich usunąć za pomocą polecenia dotnet new uninstall.

Lokalizacja szablonu

Aparat szablonów .NET obsługuje opcjonalną lokalizację metadanych szablonu. Po podaniu plików lokalizacji hosty, takie jak dotnet new i okno dialogowe Visual Studio Nowy Project wyświetla nazwę, opis i symbol szablonu w języku użytkownika zamiast oryginalnego języka utworzonego.

Następujące pola szablonu obsługują lokalizację:

  • name
  • author
  • description
  • Symbol description i displayName
  • Opis i nazwa wyświetlana dla każdego wyboru w parametrze wyboru
  • Opublikuj akcję description i manualInstructions

Aby dodać lokalizację localize , utwórz podfolder wewnątrz .template.config i dodaj jeden plik JSON na język. Nazwij każdy plik templatestrings.<lang-code>.json, gdzie <lang-code> pasuje do prawidłowej CultureInfo nazwy, takiej jak pt-BR, zh-Hanslub de. Każdy plik zawiera pary klucz-wartość, w których klucz jest ścieżką do elementu w template.jsonpliku , używając / jako ogranicznika dla zagnieżdżonych pól.

Na przykład element template.json o następującej zawartości:

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

Brazylijski plik lokalizacji portugalskiej o nazwie templatestrings.pt-BR.json będzie wyglądać następująco:

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

Aparat szablonu analizuje te pliki podczas ładowania informacji o szablonie i zwraca zlokalizowane wartości automatycznie na podstawie bieżącej kultury interfejsu użytkownika — żadne dodatkowe kroki nie są wymagane od użytkownika.

Lokalizacja jest opcjonalna. Jeśli nie dołączysz plików lokalizacji, szablon działa normalnie i zawsze wyświetla wartości z template.json. Aby uzyskać więcej informacji, zobacz stronę lokalizacji witryny typu wiki dotnet/templating.

Integracja z programem Visual Studio

Visual Studio okno dialogowe Tworzenie nowego projektu używa aparatu szablonów .NET dla szablonów projektów .NET. Szablony tworzone do dotnet new pracy również w Visual Studio bez dodatkowej konfiguracji. Gdy użytkownik zainstaluje pakiet szablonu za pomocą dotnet new installprogramu , Visual Studio automatycznie wykrywa i wyświetla te szablony w oknie dialogowym.

Project i szablony rozwiązań są wyświetlane w oknie dialogowym Tworzenie nowego project wraz z wbudowanymi szablonami zestawu SDK. Użytkownicy mogą znaleźć szablony według nazwy, języka lub tagów z classifications pola w pliku szablonu template.json . Dokładne klasyfikacje ułatwiają powierzchnię szablonów w odpowiednich kategoriach filtrów, więc starannie je wybieraj. Aby nadać szablonowi dopracowany wygląd w oknie dialogowym, dodaj element icon.png do .template.config folderu — Visual Studio wyświetla go obok nazwy szablonu.

Szablony elementów nie są obecnie wyświetlane w oknie dialogowym Dodawanie>nowego elementu . Użytkownicy nadal mogą używać szablonów elementów za dotnet new pomocą polecenia w terminalu.

Aby umożliwić odnajdywanie szablonu Visual Studio użytkownikom, którzy jeszcze go nie zainstalowano, opublikuj pakiet szablonu w celu nuget.org. Okno dialogowe Tworzenie nowego projektu zawiera opcję Zainstaluj więcej szablonów z opcji wyszukiwania online, która wyszukuje nuget.org dla pakietów szablonów. Gdy użytkownik zainstaluje pakiet za pomocą tej opcji, Visual Studio używa tego samego mechanizmu instalacji co dotnet new install.

Aby uzyskać bardziej szczegółowe wskazówki dotyczące integracji specyficznej dla Visual Studio, takiej jak kontrolowanie kolejności sortowania szablonów i konfigurowanie dodatkowych opcji specyficznych dla środowiska IDE, zobacz Przykładowe repozytorium Sayed Hashimi.

Treści powiązane

  • Last updated on