Szablony niestandardowe dla nowego dotnetCustom templates for dotnet new

Zestaw .NET Core SDK zawiera wiele szablonów, które są już zainstalowane i gotowe do użycia.The .NET Core SDK comes with many templates already installed and ready for you to use. Poleceniedotnet new nie jest tylko sposobem korzystania z szablonu, ale także instalowania i odinstalowywania szablonów.The dotnet new command isn't only the way to use a template, but also how to install and uninstall templates. Począwszy od platformy .NET Core 2,0, można tworzyć własne szablony niestandardowe dla dowolnego typu projektu, takie jak aplikacja, usługa, narzędzie lub Biblioteka klas.Starting with .NET Core 2.0, you can create your own custom templates for any type of project, such as an app, service, tool, or class library. Można nawet utworzyć szablon, który wyprowadza jeden lub więcej niezależnych plików, na przykład plik konfiguracji.You can even create a template that outputs one or more independent files, such as a configuration file.

Szablony niestandardowe można instalować 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.You can install custom templates from a NuGet package on any NuGet feed, by referencing a NuGet .nupkg file directly, or by specifying a file system directory that contains the template. Aparat szablonów oferuje funkcje, które umożliwiają zamianę wartości, uwzględnianie i wykluczanie plików oraz wykonywanie niestandardowych operacji przetwarzania, gdy szablon jest używany.The template engine offers features that allow you to replace values, include and exclude files, and execute custom processing operations when your template is used.

Aparat szablonu jest otwartym źródłem, a repozytorium kodu online jest w witrynie GitHub /tworzenia szablonów .The template engine is open source, and the online code repository is at dotnet/templating on GitHub. Przykłady szablonów można znaleźć w repozytorium dotnet/dotnet-Template-Samples .Visit the dotnet/dotnet-template-samples repo for samples of templates. Więcej szablonów, w tym szablonów ze stron trzecich, znajduje się w dostępnych szablonach dla platformy dotnet Nowość w serwisie GitHub.More templates, including templates from third parties, are found at Available templates for dotnet new on GitHub. Aby uzyskać więcej informacji na temat tworzenia i używania szablonów niestandardowych, zobacz jak utworzyć własne szablony dla platformy dotnet New i typu wiki/tworzenia szablonów repozytorium GitHub.For more information about creating and using custom templates, see How to create your own templates for dotnet new and the dotnet/templating GitHub repo Wiki.

Aby postępować zgodnie z przewodnikiem i utworzyć szablon, zobacz temat Tworzenie niestandardowego szablonu dla dotnet nowy samouczek.To follow a walkthrough and create a template, see the Create a custom template for dotnet new tutorial.

Szablony domyślne .NET.NET default templates

Po zainstalowaniu zestaw .NET Core SDKotrzymujesz wiele wbudowanych szablonów służących do tworzenia projektów i plików, takich jak aplikacje konsolowe, biblioteki klas, projekty testów jednostkowych, aplikacje ASP.NET Core (w tym projekty kątowe i reagowanie ), i pliki konfiguracji.When you install the .NET Core SDK, you receive over a dozen built-in templates for creating projects and files, including console apps, class libraries, unit test projects, ASP.NET Core apps (including Angular and React projects), and configuration files. Aby wyświetlić listę wbudowanych szablonów, uruchom polecenie dotnet new z opcją -l|--list:To list the built-in templates, run the dotnet new command with the -l|--list option:

dotnet new --list

KonfiguracjaConfiguration

Szablon składa się z następujących części:A template is composed of the following parts:

  • Pliki źródłowe i foldery.Source files and folders.
  • Plik konfiguracji (Template. JSON).A configuration file (template.json).

Pliki źródłowe i folderySource files and folders

Pliki i foldery źródłowe zawierają wszystkie pliki i foldery, które mają być używane przez aparat szablonów po uruchomieniu polecenia dotnet new <TEMPLATE>.The source files and folders include whatever files and folders you want the template engine to use when the dotnet new <TEMPLATE> command is run. Aparat szablonów jest przeznaczony do używania projektów możliwy do uruchomienia jako kod źródłowy do tworzenia projektów.The template engine is designed to use runnable projects as source code to produce projects. Ma to kilka korzyści:This has several benefits:

  • Aparat szablonów nie wymaga dodawania specjalnych tokenów do kodu źródłowego projektu.The template engine doesn't require you to inject special tokens into your project's source code.
  • Pliki kodu nie są plikami specjalnymi ani modyfikowane w sposób umożliwiający współdziałanie z aparatem szablonu.The code files aren't special files or modified in any way to work with the template engine. Dlatego narzędzia zwykle używane podczas pracy z projektami również pracują z zawartością szablonu.So, the tools you normally use when working with projects also work with template content.
  • Możesz tworzyć, uruchamiać i debugować projekty szablonów tak samo jak w przypadku innych projektów.You build, run, and debug your template projects just like you do for any of your other projects.
  • Możesz szybko utworzyć szablon na podstawie istniejącego projektu tylko przez dodanie pliku konfiguracji ./.Template.config/Template.JSON do projektu.You can quickly create a template from an existing project just by adding a ./.template.config/template.json configuration file to the project.

Pliki i foldery przechowywane w szablonie nie są ograniczone do formalnych typów projektów .NET.Files and folders stored in the template aren't limited to formal .NET project types. Pliki źródłowe i foldery mogą zawierać dowolną zawartość, którą chcesz utworzyć, gdy szablon jest używany, nawet jeśli aparat szablonu tworzy tylko jeden plik jako dane wyjściowe.Source files and folders may consist of any content that you wish to create when the template is used, even if the template engine produces just one file as its output.

Pliki generowane przez szablon można modyfikować w oparciu o logikę i ustawienia podane w pliku konfiguracji Template. JSON .Files generated by the template can be modified based on logic and settings you've provided in the template.json configuration file. Użytkownik może przesłonić te ustawienia przez przekazanie opcji do dotnet new <TEMPLATE> polecenie.The user can override these settings by passing options to the dotnet new <TEMPLATE> command. Typowym przykładem logiki niestandardowej jest podanie nazwy klasy lub zmiennej w pliku kodu, który jest wdrażany przez szablon.A common example of custom logic is providing a name for a class or variable in the code file that's deployed by a template.

Template. JSONtemplate.json

Plik Template. JSON zostanie umieszczony w folderze Template. config w katalogu głównym szablonu.The template.json file is placed in a .template.config folder in the root directory of the template. Plik zawiera informacje o konfiguracji do aparatu szablonu.The file provides configuration information to the template engine. Minimalna konfiguracja wymaga od członków pokazanych w poniższej tabeli, co jest wystarczające do utworzenia szablonu funkcjonalnego.The minimum configuration requires the members shown in the following table, which is sufficient to create a functional template.

Element członkowskiMember TypType OpisDescription
$schema Identyfikator URIURI Schemat JSON dla pliku Template. JSON .The JSON schema for the template.json file. Edytory obsługujące schematy JSON umożliwiają korzystanie z funkcji edytowania JSON, gdy schemat jest określony.Editors that support JSON schemas enable JSON-editing features when the schema is specified. Na przykład Visual Studio Code wymaga tego elementu członkowskiego, aby włączyć funkcję IntelliSense.For example, Visual Studio Code requires this member to enable IntelliSense. Użyj wartości http://json.schemastore.org/template.Use a value of http://json.schemastore.org/template.
author stringstring Autor szablonu.The author of the template.
classifications Array (ciąg)array(string) Zero lub więcej charakterystyki szablonu, którego użytkownik może użyć, aby znaleźć szablon podczas jego wyszukania.Zero or more characteristics of the template that a user might use to find the template when searching for it. Klasyfikacje są również wyświetlane w kolumnie Tagi , gdy pojawiają się na liście szablonów utworzonych przy użyciu polecenia dotnet new -l|--list.The classifications also appear in the Tags column when it appears in a list of templates produced by using the dotnet new -l|--list command.
identity stringstring Unikatowa nazwa tego szablonu.A unique name for this template.
name stringstring Nazwa szablonu, który użytkownicy powinni zobaczyć.The name for the template that users should see.
shortName stringstring Domyślna nazwa skrótu służąca do wybierania szablonu, który ma zastosowanie do środowisk, w których nazwa szablonu jest określona przez użytkownika, a nie wybierana za pośrednictwem graficznego interfejsu użytkownika.A default shorthand name for selecting the template that applies to environments where the template name is specified by the user, not selected via a GUI. Na przykład krótka nazwa jest przydatna w przypadku korzystania z szablonów z wiersza polecenia z poleceniami CLI.For example, the short name is useful when using templates from a command prompt with CLI commands.

Pełny Schemat pliku Template. JSON znajduje się w magazynie schematów JSON.The full schema for the template.json file is found at the JSON Schema Store. Aby uzyskać więcej informacji na temat pliku Template. JSON , zobacz stronę typu tworzenia szablonów programu dotnet.For more information about the template.json file, see the dotnet templating wiki.

PrzykładExample

Na przykład poniżej znajduje się folder Template zawierający dwa pliki zawartości: Console.cs i README. txt.For example, here is a template folder that contains two content files: console.cs and readme.txt. Zwróć uwagę, że istnieje wymagany folder o nazwie . Template. config zawierający plik Template. JSON .Take notice that there is the required folder named .template.config that contains the template.json file.

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

Plik Template. JSON wygląda następująco:The template.json file looks like the following:

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

Folder Moje Template to instalowalny pakiet szablonów.The mytemplate folder is an installable template pack. Po zainstalowaniu pakietu shortName może być używany z dotnet new polecenie.Once the pack is installed, the shortName can be used with the dotnet new command. Na przykład dotnet new adatumconsole będzie wyprowadzać pliki console.cs i readme.txt do bieżącego folderu.For example, dotnet new adatumconsole would output the console.cs and readme.txt files to the current folder.

Pakowanie szablonu do pakietu NuGet (plik NUPKG)Packing a template into a NuGet package (nupkg file)

Szablon niestandardowy jest spakowany przy użyciu polecenia pakietu dotnet i pliku . csproj .A custom template is packed with the dotnet pack command and a .csproj file. Alternatywnie, można użyć polecenia NuGet z pakietem NuGet z plikiem . nuspec .Alternatively, NuGet can be used with the nuget pack command along with a .nuspec file. Jednak program NuGet wymaga .NET Framework w systemie Windows i mono w systemie Linux i MacOS.However, NuGet requires the .NET Framework on Windows and Mono on Linux and MacOS.

Plik . csproj różni się nieco od tradycyjnego pliku Code-Project . csproj .The .csproj file is slightly different from a traditional code-project .csproj file. Zwróć uwagę na następujące ustawienia:Note the following settings:

  1. Ustawienie <PackageType> zostało dodane i ustawione na Template.The <PackageType> setting is added and set to Template.
  2. Ustawienie <PackageVersion> zostanie dodane i ustawiony prawidłowy numer wersji programu NuGet.The <PackageVersion> setting is added and set to a valid NuGet version number.
  3. Ustawienie <PackageId> jest dodawane i ustawiane jako unikatowy identyfikator.The <PackageId> setting is added and set to a unique identifier. Ten identyfikator służy do odinstalowywania pakietu szablonów i jest używany przez źródła danych NuGet do rejestrowania pakietu szablonów.This identifier is used to uninstall the template pack and is used by NuGet feeds to register your template pack.
  4. Ogólne ustawienia metadanych należy ustawić: <Title>, <Authors>, <Description>i <PackageTags>.Generic metadata settings should be set: <Title>, <Authors>, <Description>, and <PackageTags>.
  5. Ustawienie <TargetFramework> musi być ustawione, nawet jeśli plik binarny tworzony przez proces szablonu nie jest używany.The <TargetFramework> setting must be set, even though the binary produced by the template process isn't used. W poniższym przykładzie jest ustawiony na netstandard2.0.In the example below it's set to netstandard2.0.

Pakiet szablonów w formie pakietu NuGet . nupkg wymaga, aby wszystkie szablony były przechowywane w folderze zawartości w pakiecie.A template pack, in the form of a .nupkg NuGet package, requires that all templates be stored in the content folder within the package. Istnieje kilka dodatkowych ustawień do dodania do pliku . csproj , aby upewnić się, że wygenerowane . nupkg można zainstalować jako pakiet szablonów:There are a few more settings to add to a .csproj file to ensure that the generated .nupkg can be installed as a template pack:

  1. Ustawienie <IncludeContentInPack> jest ustawione na true w celu uwzględnienia dowolnych plików, które są ustawiane jako zawartość pakietu NuGet.The <IncludeContentInPack> setting is set to true to include any file the project sets as content in the NuGet package.
  2. Ustawienie <IncludeBuildOutput> jest ustawione na false, aby wykluczyć wszystkie pliki binarne wygenerowane przez kompilator z pakietu NuGet.The <IncludeBuildOutput> setting is set to false to exclude all binaries generated by the compiler from the NuGet package.
  3. Ustawienie <ContentTargetFolders> jest ustawione na content.The <ContentTargetFolders> setting is set to content. Daje to pewność, że pliki ustawione jako zawartość są przechowywane w folderze zawartości w pakiecie NuGet.This makes sure that the files set as content are stored in the content folder in the NuGet package. Ten folder w pakiecie NuGet jest analizowany przez system szablonów dotnet.This folder in the NuGet package is parsed by the dotnet template system.

Prostym sposobem wykluczenia wszystkich plików kodu z kompilowania przez projekt szablonu jest użycie elementu <Compile Remove="**\*" /> w pliku projektu, wewnątrz elementu <ItemGroup>.An easy way to exclude all code files from being compiled by your template project is by using the <Compile Remove="**\*" /> item in your project file, inside an <ItemGroup> element.

Łatwym sposobem struktury pakietu Template Pack jest umieszczenie wszystkich szablonów w poszczególnych folderach, a następnie każdy folder szablonu wewnątrz folderu templates znajdującego się w tym samym katalogu, w którym znajduje się plik . csproj .An easy way to structure your template pack is to put all templates in individual folders, and then each template folder inside of a templates folder that is located in the same directory as your .csproj file. W ten sposób można użyć pojedynczego elementu projektu, aby uwzględnić wszystkie pliki i foldery w szablonach jako zawartość.This way, you can use a single project item to include all files and folders in the templates as content. Wewnątrz elementu <ItemGroup>, Utwórz element <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />.Inside of an <ItemGroup> element, create a <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> item.

Poniżej znajduje się przykładowy plik csproj , który jest zgodny ze wszystkimi powyższymi wskazówkami.Here is an example .csproj file that follows all of the guidelines above. Program IT pakuje folder podrzędny szablonów do folderu pakietu zawartości i wyklucza każdy plik kodu z kompilacji.It packs the templates child folder to the content package folder and excludes any code file from being compiled.

<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 przedstawiono strukturę plików i folderów programu przy użyciu pliku . csproj , aby utworzyć pakiet szablonów.The example below demonstrates the file and folder structure of using a .csproj to create a template pack. Folder plików i szablonów MyDotnetTemplates. csproj znajduje się w katalogu głównym katalogu o nazwie project_folder.The MyDotnetTemplates.csproj file and templates folder are both located at the root of a directory named project_folder. Folder szablonów zawiera dwa szablony, mytemplate1 i mytemplate2.The templates folder contains two templates, mytemplate1 and mytemplate2. Każdy szablon zawiera pliki zawartości i folder . Template. config z plikiem konfiguracji Template. JSON .Each template has content files and a .template.config folder with a template.json config file.

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

Instalowanie szablonuInstalling a template

Użyj polecenia dotnet New-i |--Install , aby zainstalować pakiet.Use the dotnet new -i|--install command to install a package.

Aby zainstalować szablon z pakietu NuGet przechowywanego w nuget.orgTo install a template from a NuGet package stored at nuget.org

Użyj identyfikatora pakietu NuGet, aby zainstalować pakiet szablonu.Use the NuGet package identifier to install a template package.

dotnet new -i <NUGET_PACKAGE_ID>

Aby zainstalować szablon z lokalnego pliku NUPKGTo install a template from a local nupkg file

Podaj ścieżkę do pliku pakietu NuGet . nupkg .Provide the path to a .nupkg NuGet package file.

dotnet new -i <PATH_TO_NUPKG_FILE>

Aby zainstalować szablon z katalogu systemu plikówTo install a template from a file system directory

Szablony można instalować z folderu szablonów, takiego jak folder mytemplate1 , z powyższego przykładu.Templates can be installed from a template folder, such as the mytemplate1 folder from the example above. Określ ścieżkę folderu folderu Template. config .Specify the folder path of the .template.config folder. Ścieżka do katalogu szablonów nie musi być bezwzględna.The path to the template directory does not need to be absolute. Jednak do odinstalowania szablonu, który jest instalowany z folderu, wymagana jest ścieżka bezwzględna.However, an absolute path is required to uninstall a template that is installed from a folder.

dotnet new -i <FILE_SYSTEM_DIRECTORY>

Pobierz listę zainstalowanych szablonówGet a list of installed templates

Polecenie odinstalowania bez żadnych innych parametrów spowoduje wyświetlenie listy wszystkich zainstalowanych szablonów.The uninstall command, without any other parameters, will list all installed templates.

dotnet new -u

To polecenie zwraca coś podobnego do następującego:That command returns something similar to the following output:

Template Instantiation Commands for .NET Core CLI

Currently installed items:
  Microsoft.DotNet.Common.ItemTemplates
    Templates:
      global.json file (globaljson)
      NuGet Config (nugetconfig)
      Solution File (sln)
      Dotnet local tool manifest file (tool-manifest)
      Web Config (webconfig)
  Microsoft.DotNet.Common.ProjectTemplates.3.0
    Templates:
      Class library (classlib) C#
      Class library (classlib) F#
      Class library (classlib) VB
      Console Application (console) C#
      Console Application (console) F#
      Console Application (console) VB
...

Pierwszym poziomem elementów po Currently installed items: są identyfikatory używane podczas odinstalowywania szablonu.The first level of items after Currently installed items: are the identifiers used in uninstalling a template. W powyższym przykładzie Microsoft.DotNet.Common.ItemTemplates i Microsoft.DotNet.Common.ProjectTemplates.3.0 są wymienione.And in the example above, Microsoft.DotNet.Common.ItemTemplates and Microsoft.DotNet.Common.ProjectTemplates.3.0 are listed. Jeśli szablon został zainstalowany przy użyciu ścieżki systemu plików, ten identyfikator będzie ścieżką folderu folderu . Template. config .If the template was installed by using a file system path, this identifier will the folder path of the .template.config folder.

Odinstalowywanie szablonuUninstalling a template

Aby odinstalować pakiet, użyj polecenia " New-u |--Uninstall" dotnet .Use the dotnet new -u|--uninstall command to uninstall a package.

Jeśli pakiet został zainstalowany bezpośrednio przez źródło danych NuGet lub plik . nupkg , podaj identyfikator.If the package was installed by either a NuGet feed or by a .nupkg file directly, provide the identifier.

dotnet new -u <NUGET_PACKAGE_ID>

Jeśli pakiet został zainstalowany przez określenie ścieżki do folderu . Template. config , Użyj tej ścieżki bezwzględnej w celu odinstalowania pakietu.If the package was installed by specifying a path to the .template.config folder, use that absolute path to uninstall the package. Ścieżka bezwzględna szablonu znajduje się w danych wyjściowych dostarczonych przez polecenie dotnet new -u.You can see the absolute path of the template in the output provided by the dotnet new -u command. Aby uzyskać więcej informacji, zobacz sekcję Pobieranie listy zainstalowanych szablonów powyżej.For more information, see the Get a list of installed templates section above.

dotnet new -u <ABSOLUTE_FILE_SYSTEM_DIRECTORY>

Tworzenie projektu przy użyciu szablonu niestandardowegoCreate a project using a custom template

Po zainstalowaniu szablonu Użyj szablonu, wykonując polecenie dotnet new <TEMPLATE>, tak jak w przypadku dowolnego innego wstępnie zainstalowanego szablonu.After a template is installed, use the template by executing the dotnet new <TEMPLATE> command as you would with any other pre-installed template. Możesz również określić Opcje dla polecenia dotnet new, w tym opcje specyficzne dla szablonu skonfigurowane w ustawieniach szablonu.You can also specify options to the dotnet new command, including template-specific options you configured in the template settings. Podaj krótką nazwę szablonu bezpośrednio do polecenia:Supply the template's short name directly to the command:

dotnet new <TEMPLATE>

Zobacz takżeSee also