Szablony niestandardowe dla aplikacji dotnet new

Artykuł
08/15/2023

Zestaw .NET SDK zawiera wiele szablonów już zainstalowanych i gotowych do użycia. Polecenie dotnet new nie jest tylko sposobem używania szablonu, ale także sposobu instalowania i odinstalowywania szablonów. Możesz utworzyć własne szablony niestandardowe dla dowolnego typu projektu, takiego jak aplikacja, usługa, narzędzie lub biblioteka klas. Można nawet utworzyć szablon, który generuje jeden lub więcej niezależnych plików, takich jak plik konfiguracji.

Szablony niestandardowe można zainstalować z pakietu NuGet na dowolnym kanale informacyjnym NuGet, odwołując się bezpośrednio do pliku NuGet nupkg lub określając katalog systemu plików zawierający szablon. Aparat szablonów oferuje funkcje, które umożliwiają zastępowanie wartości, dołączanie i wykluczanie plików oraz wykonywanie niestandardowych operacji przetwarzania podczas korzystania z szablonu.

Aparat szablonu jest oprogramowaniem open source, a repozytorium kodu online znajduje się w witrynie dotnet/templating w witrynie GitHub. Więcej szablonów, w tym szablonów pochodzących od innych firm, można znaleźć przy użyciu usługi dotnet new search. Aby uzyskać więcej informacji na temat tworzenia i używania szablonów niestandardowych, zobacz How to create your own templates for dotnet new and the dotnet/templating GitHub repo Wiki (Jak utworzyć własne szablony dla nowych szablonów dotnet/templating w repozytorium GitHub).

Uwaga

Przykłady szablonów są dostępne w repozytorium dotnet/templating w witrynie GitHub.

Aby postępować zgodnie z przewodnikiem i utworzyć szablon, zobacz samouczek Tworzenie szablonu niestandardowego dla aplikacji dotnet new .

Szablony domyślne platformy .NET

Podczas instalowania zestawu SDK platformy .NET otrzymujesz kilkanaście wbudowanych szablonów do tworzenia projektów i plików, w tym aplikacji konsolowych, bibliotek klas, projektów testów jednostkowych, aplikacji ASP.NET Core (w tym projektów Angular i React ) oraz plików konfiguracji. Aby wyświetlić listę wbudowanych szablonów, uruchom dotnet new list polecenie:

dotnet new list

Konfigurowanie

Szablon składa się z następujących części:

Pliki źródłowe i foldery.
Plik konfiguracji (template.json).

Pliki źródłowe i foldery

Pliki źródłowe i foldery zawierają pliki i foldery, których aparat szablonu ma używać podczas uruchamiania dotnet new <TEMPLATE> polecenia. Aparat szablonów jest przeznaczony do używania projektów możliwych do uruchomienia jako kodu źródłowego do tworzenia projektów. Ma to kilka korzyści:

Aparat szablonu nie wymaga wstrzykiwania specjalnych tokenów do kodu źródłowego projektu.
Pliki kodu nie są specjalnymi plikami ani modyfikowane w żaden sposób do pracy z aparatem szablonu. Dlatego narzędzia, których zwykle używasz podczas pracy z projektami, współpracują również z zawartością szablonu.
Kompilujesz, uruchamiasz i debugujesz projekty szablonów tak samo jak w przypadku dowolnego z innych projektów.
Szablon można szybko utworzyć na podstawie istniejącego projektu, dodając do projektu plik konfiguracji ./.template.config/template.json .

Pliki i foldery przechowywane w szablonie nie są ograniczone do formalnych typów projektów .NET. Pliki źródłowe i foldery mogą składać się z dowolnej zawartości, którą chcesz utworzyć podczas korzystania z szablonu, nawet jeśli aparat szablonu tworzy tylko jeden plik jako jego dane wyjściowe.

Pliki generowane przez szablon można modyfikować na podstawie logiki i ustawień podanych w pliku konfiguracji template.json . Użytkownik może zastąpić te ustawienia, przekazując opcje do dotnet new <TEMPLATE> polecenia . Typowym przykładem logiki niestandardowej jest podanie nazwy klasy lub zmiennej w pliku kodu wdrażanym przez szablon.

template.json

Plik template.json znajduje się w folderze .template.config w katalogu głównym szablonu. Plik zawiera informacje o konfiguracji aparatu szablonu. Minimalna konfiguracja wymaga elementów członkowskich przedstawionych w poniższej tabeli, co jest wystarczające do utworzenia szablonu funkcjonalnego.

Element członkowski	Type	Opis
`$schema`	Identyfikator URI	Schemat JSON dla pliku template.json . Edytory, które obsługują schematy JSON, umożliwiają edytowanie w formacie JSON funkcji po określeniu schematu. Na przykład program Visual Studio Code wymaga włączenia funkcji IntelliSense przez tego członka. Użyj wartości `http://json.schemastore.org/template`.
`author`	string	Autor szablonu.
`classifications`	array(string)	Zero lub więcej cech szablonu, których użytkownik może użyć do znalezienia szablonu podczas wyszukiwania go. Klasyfikacje są również wyświetlane w kolumnie Tagi , gdy są wyświetlane na liście szablonów utworzonych przy użyciu `dotnet new list` polecenia .
`identity`	string	Unikatowa nazwa tego szablonu.
`name`	string	Nazwa szablonu, który użytkownicy powinni zobaczyć.
`shortName`	string	Domyślna skrócona nazwa wybierania szablonu, który ma zastosowanie do środowisk, w których nazwa szablonu jest określona przez użytkownika, a nie wybrana za pośrednictwem graficznego interfejsu użytkownika. Na przykład krótka nazwa jest przydatna podczas używania szablonów z wiersza polecenia za pomocą poleceń interfejsu wiersza polecenia.
`sourceName`	string	Nazwa w drzewie źródłowym, która ma zastąpić nazwą określaną przez użytkownika. Aparat szablonu będzie szukać dowolnego wystąpienia wymienionego `sourceName` w pliku konfiguracji i zastąpić go w nazwach plików i zawartości pliku. Wartość, która ma zostać zastąpiona, można podać przy użyciu `-n` opcji lub `--name` podczas uruchamiania szablonu. Jeśli nie określono żadnej nazwy, używany jest bieżący katalog.
`preferNameDirectory`	Wartość logiczna	Wskazuje, czy utworzyć katalog dla szablonu, jeśli określono nazwę, ale katalog wyjściowy nie jest ustawiony (zamiast tworzyć zawartość bezpośrednio w bieżącym katalogu). Wartość domyślna to false.

Pełny schemat pliku template.json znajduje się w magazynie schematów JSON. Aby uzyskać więcej informacji na temat pliku template.json , zobacz witrynę typu wiki dotnet templating. Aby uzyskać bardziej szczegółowe przykłady i informacje na temat sposobu uwidocznienia szablonów w programie Visual Studio, zapoznaj się z utworzonymi zasobami Sayed Hashimi.

Przykład

Oto folder szablonu zawierający dwa pliki zawartości: console.cs i readme.txt. Istnieje również wymagany folder o nazwie .template.config zawierający plik template.json .

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

Plik template.json wygląda następująco:

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

Folder mytemplate to instalowany pakiet szablonu. Po zainstalowaniu shortName pakietu można go użyć z poleceniem dotnet new . Na przykład dotnet new adatumconsole spowoduje wyprowadzenie console.cs plików i readme.txt do bieżącego folderu.

Lokalizacja szablonu

Szablony platformy .NET można lokalizują. Jeśli szablon jest zlokalizowany dla języka pasującego do bieżących ustawień regionalnych, jego elementy są wyświetlane w tym samym języku co interfejs wiersza polecenia. Lokalizacja jest opcjonalna podczas tworzenia nowych szablonów.

Elementy lokalizowalne w szablonie to:

Nazwisko
Autor
opis
Symbole
- Opis
- Wyświetlana nazwa
- Opisy i nazwa wyświetlana wybranych parametrów
Akcje ogłaszane
- opis
- Instrukcje ręczne

Pliki lokalizacji mają format JSON i powinien istnieć tylko jeden plik na kulturę. Konwencja nazewnictwa to: , gdzie lang code odpowiada jednej z opcji CultureInfo. templatestrings.<lang code>.json Wszystkie pliki lokalizacji powinny znajdować się w folderze .template-config\localize .

Plik JSON lokalizacji składa się z par klucz-wartość:

Kluczem jest odwołanie do elementu, który template.json ma zostać zlokalizowany. Jeśli element jest elementem podrzędnym, użyj pełnej ścieżki z / ogranicznikiem.
Wartość jest ciągiem lokalizacji elementu podanego przez klucz.

Aby uzyskać więcej informacji na temat lokalizowania szablonów, zobacz stronę lokalizacji witryny typu wiki dotnet templating.

Przykład

Na przykład poniżej przedstawiono plik template.json z niektórymi polami lokalizowalnymi:

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

Niektóre pola mają być zlokalizowane dla brazylijskiego portugalskiego. Nazwa pliku będzie templatestrings.pt-BR.json zgodna z kulturą i wyglądałaby 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."
}

Pakowanie szablonu do pakietu NuGet (plik nupkg)

Szablon niestandardowy jest zapakowany za pomocą polecenia dotnet pack i pliku csproj . Alternatywnie można użyć narzędzia NuGet z poleceniem pakietu nuget wraz z plikiem nuspec . Jednak pakiet NuGet wymaga programu .NET Framework w systemach Windows i Mono w systemach Linux i macOS.

Plik csproj różni się nieco od tradycyjnego pliku csproj projektu kodu. Zwróć uwagę na następujące ustawienia:

Ustawienie <PackageType> jest dodawane i ustawiane na Template.
To <PackageVersion> ustawienie jest dodawane i ustawiane na prawidłowy numer wersji NuGet.
To <PackageId> ustawienie jest dodawane i ustawiane na unikatowy identyfikator. Ten identyfikator służy do odinstalowania pakietu szablonu i jest używany przez kanały informacyjne NuGet do rejestrowania pakietu szablonu.
Należy ustawić ogólne ustawienia metadanych: <Title>, , <Authors><Description>i <PackageTags>.
Ustawienie <TargetFramework> musi być ustawione, mimo że plik binarny utworzony przez proces szablonu nie jest używany. W poniższym przykładzie ustawiono wartość netstandard2.0.

Pakiet szablonu w postaci pakietu NuGet nupkg wymaga przechowywania wszystkich szablonów w folderze zawartości w pakiecie. Istnieje jeszcze kilka ustawień do dodania do pliku csproj , aby upewnić się, że wygenerowany plik nupkg można zainstalować jako pakiet szablonu:

Ustawienie <IncludeContentInPack> ma na celu true dołączenie dowolnego pliku, który projekt ustawia jako zawartość w pakiecie NuGet.
Ustawienie <IncludeBuildOutput> ma wartość , aby false wykluczyć wszystkie pliki binarne wygenerowane przez kompilator z pakietu NuGet.
Ustawienie <ContentTargetFolders> ma wartość content. Dzięki temu pliki ustawione jako zawartość są przechowywane w folderze zawartości w pakiecie NuGet. Ten folder w pakiecie NuGet jest analizowany przez system szablonów dotnet.

Łatwym sposobem wykluczenia wszystkich plików kodu z kompilowania projektu szablonu jest użycie <Compile Remove="**\*" /> elementu w pliku projektu wewnątrz <ItemGroup> elementu.

Łatwym sposobem struktury pakietu szablonów jest umieszczenie wszystkich szablonów w poszczególnych folderach, a następnie każdy folder szablonu w folderze szablonów , który znajduje się w tym samym katalogu co plik csproj . W ten sposób można użyć jednego elementu projektu do uwzględnienia wszystkich plików i folderów w szablonach jako zawartości. <ItemGroup> Wewnątrz elementu utwórz <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> element.

Oto przykładowy plik csproj , który jest zgodny ze wszystkimi tymi wytycznymi. Pakuje folder podrzędny szablonów do folderu pakietu zawartości i wyklucza z kompilowania dowolny plik kodu.

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

W poniższym przykładzie pokazano strukturę plików i folderów przy użyciu pliku csproj do utworzenia pakietu szablonu. Zarówno plik MyDotnetTemplates.csproj , jak i folder templates znajdują się w katalogu głównym katalogu o nazwie project_folder. Folder templates zawiera dwa szablony : mytemplate1 i mytemplate2. Każdy szablon zawiera pliki zawartości i folder .template.config z plikiem konfiguracji template.json .

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

Uwaga

Aby upewnić się, że pakiet szablonu jest wyświetlany w dotnet new search wyniku, ustaw typ pakietu NuGet na Templatewartość .

Instalowanie pakietu szablonu

Użyj polecenia dotnet new install, aby zainstalować pakiet szablonu.

Aby zainstalować pakiet szablonu z pakietu NuGet przechowywanego w nuget.org

Użyj identyfikatora pakietu NuGet, aby zainstalować pakiet szablonu.

dotnet new install <NUGET_PACKAGE_ID>

Aby zainstalować pakiet szablonu z niestandardowego źródła NuGet

Podaj niestandardowe źródło NuGet (na przykład https://api.my-custom-nuget.com/v3/index.json).

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

Aby zainstalować pakiet szablonu z lokalnego pliku nupkg

Podaj ścieżkę do pliku pakietu NuGet nupkg .

dotnet new install <PATH_TO_NUPKG_FILE>

Aby zainstalować pakiet szablonu z katalogu systemu plików

Szablony można instalować z folderu szablonu, takiego jak folder mytemplate1 z poprzedniego przykładu. Określ ścieżkę folderu .template.config . Ścieżka do katalogu szablonu nie musi być bezwzględna.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Pobieranie listy zainstalowanych pakietów szablonów

Polecenie dezinstalacji, bez żadnych innych parametrów, wyświetla listę wszystkich zainstalowanych pakietów szablonów i dołączonych szablonów.

dotnet new uninstall

To polecenie zwraca coś podobnego do następujących danych wyjściowych:

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

Pierwszy poziom elementów po Currently installed items: są identyfikatorami używanymi podczas odinstalowywania pakietu szablonu. W poprzednim przykładzie Microsoft.Azure.WebJobs.ProjectTemplates znajduje się na liście. Jeśli pakiet szablonu został zainstalowany przy użyciu ścieżki systemu plików, ten identyfikator jest ścieżką folderu .template.config . Na liście są wyświetlane tylko pakiety szablonów zainstalowane za pośrednictwem dotnet new install programu . Pakiety szablonów wbudowane w zestaw SDK platformy .NET nie są wyświetlane.

Odinstalowywanie pakietu szablonu

Użyj polecenia dotnet new uninstall, aby odinstalować pakiet szablonu.

Jeśli pakiet został zainstalowany przez źródło danych NuGet lub bezpośrednio przez plik nupkg , podaj identyfikator.

dotnet new uninstall <NUGET_PACKAGE_ID>

Jeśli pakiet został zainstalowany, określając ścieżkę do folderu .template.config , użyj tej ścieżki, aby odinstalować pakiet. Ścieżkę bezwzględną pakietu szablonu można zobaczyć w danych wyjściowych dostarczonych dotnet new uninstall przez polecenie . Aby uzyskać więcej informacji, zobacz sekcję Pobieranie listy zainstalowanych szablonów .

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Tworzenie projektu przy użyciu szablonu niestandardowego

Po zainstalowaniu szablonu użyj szablonu, wykonując dotnet new <TEMPLATE> polecenie tak jak w przypadku dowolnego innego wstępnie zainstalowanego szablonu. Można również określić opcjedotnet new polecenia, w tym opcje specyficzne dla szablonu skonfigurowane w ustawieniach szablonu. Podaj krótką nazwę szablonu bezpośrednio do polecenia:

dotnet new <TEMPLATE>

Szablony niestandardowe dla aplikacji dotnet new

Szablony domyślne platformy .NET

Konfigurowanie

Pliki źródłowe i foldery

template.json

Przykład

Lokalizacja szablonu

Przykład

Pakowanie szablonu do pakietu NuGet (plik nupkg)

Instalowanie pakietu szablonu

Aby zainstalować pakiet szablonu z pakietu NuGet przechowywanego w nuget.org

Aby zainstalować pakiet szablonu z niestandardowego źródła NuGet

Aby zainstalować pakiet szablonu z lokalnego pliku nupkg

Aby zainstalować pakiet szablonu z katalogu systemu plików

Pobieranie listy zainstalowanych pakietów szablonów

Odinstalowywanie pakietu szablonu

Tworzenie projektu przy użyciu szablonu niestandardowego

Zobacz też

Opinia

Dodatkowe zasoby