dotnet new のカスタム テンプレートCustom templates for dotnet new

.NET Core SDK には、既にインストールされて使用できる状態になっている多くのテンプレートが付属します。The .NET Core SDK comes with many templates already installed and ready for you to use. dotnet new コマンドは、テンプレートを使用する手段であるだけでなく、テンプレートをインストールおよびアンインストールする方法でもあります。The dotnet new command isn't only the way to use a template, but also how to install and uninstall templates. .NET Core 2.0 以降から、アプリ、サービス、ツール、クラス ライブラリなど、あらゆる種類のプロジェクトを対象に独自のテンプレートを作成できるようになりました。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. 構成ファイルなど、1 つまたは複数の独立ファイルを出力するテンプレートを作成することもできます。You can even create a template that outputs one or more independent files, such as a configuration file.

NuGet の .nupkg ファイルを直接参照するか、テンプレートが含まれるファイル システム ディレクトリを指定することで、任意の NuGet フィード上の NuGet パッケージからカスタム テンプレートをインストールできます。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. テンプレート エンジンの機能を利用すると、テンプレートを使うときに、値を置き換えたり、ファイルを含めたり除外したり、独自の処理操作を実行したりできます。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.

テンプレート エンジンはオープン ソースです。オンライン コード リポジトリは GitHub の dotnet/templating にあります。The template engine is open source, and the online code repository is at dotnet/templating on GitHub. テンプレートのサンプルが必要であれば、dotnet/dotnet-template-samples リポジトリをご覧ください。Visit the dotnet/dotnet-template-samples repo for samples of templates. GitHub の「Available templates for dotnet new」 (dotnet new で利用できるテンプレート) には、サードパーティのテンプレートなど、テンプレートが他にもあります。More templates, including templates from third parties, are found at Available templates for dotnet new on GitHub. カスタム テンプレートの作成と利用の詳細については、「dotnet new の独自のテンプレートを作成する方法」と「dotnet/templating GitHub リポジトリ Wiki」を参照してください。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.

チュートリアルでテンプレートを作成するには、「dotnet new のカスタム テンプレートを作成する」チュートリアルをご利用ください。To follow a walkthrough and create a template, see the Create a custom template for dotnet new tutorial.

.NET の既定のテンプレート.NET default templates

.NET Core SDK をインストールすると、コンソール アプリ、クラス ライブラリ、単体テスト プロジェクト、ASP.NET Core アプリ (Angular プロジェクトと React プロジェクトを含む)、構成ファイルなど、プロジェクトやファイルを作成するための 12 個を超える組み込みテンプレートが与えられます。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. 組み込みテンプレートの一覧を表示するには、-l|--list オプションを指定して dotnet new コマンドを実行します。To list the built-in templates, run the dotnet new command with the -l|--list option:

dotnet new --list

構成Configuration

テンプレートは次の部分から構成されます。A template is composed of the following parts:

  • ソース ファイルとフォルダー。Source files and folders.
  • 構成ファイル (template.json)。A configuration file (template.json).

ソース ファイルとフォルダーSource files and folders

ソース ファイルとフォルダーには、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. テンプレート エンジンは、ソース コードとして実行可能なプロジェクトを利用し、プロジェクトを生成するように設計されています。The template engine is designed to use runnable projects as source code to produce projects. これにはいくつかの利点があります。This has several benefits:

  • テンプレート エンジンでは、プロジェクトのソース コードに特別なトークンを挿入することを必要としません。The template engine doesn't require you to inject special tokens into your project's source code.
  • コード ファイルは特別なファイルではなく、テンプレート エンジンで利用するために変更されることはありません。The code files aren't special files or modified in any way to work with the template engine. そのため、プロジェクトの利用時に通常利用しているツールでテンプレート コンテンツに対応できます。So, the tools you normally use when working with projects also work with template content.
  • 他のプロジェクトの場合と同じように、テンプレート プロジェクトをビルドし、実行し、デバッグします。You build, run, and debug your template projects just like you do for any of your other projects.
  • ./.template.config/template.json 構成ファイルをプロジェクトに追加するだけで、既存のプロジェクトからテンプレートを簡単に作成できます。You can quickly create a template from an existing project just by adding a ./.template.config/template.json configuration file to the project.

テンプレートに格納されるファイルやフォルダーは、正式な種類の .NET プロジェクトに限定されません。Files and folders stored in the template aren't limited to formal .NET project types. テンプレート エンジンで出力として生成されるファイルが 1 つだけであっても、ソース ファイルとフォルダーは、テンプレートを使って作成するすべてのコンテンツで構成できます。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.

テンプレートによって生成されるファイルは、template.json 構成ファイルで提供するロジックと設定に基づいて変更できます。Files generated by the template can be modified based on logic and settings you've provided in the template.json configuration file. ユーザーは、dotnet new <TEMPLATE> コマンドにオプションを渡すことによって、これらの設定を上書きすることができます。The user can override these settings by passing options to the dotnet new <TEMPLATE> command. カスタム ロジックの一般的な例は、テンプレートによって展開されるコード ファイル内のクラスや変数に名前を提供する場合です。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

template.json ファイルは、テンプレートのルート ディレクトリの .template.config フォルダーにあります。The template.json file is placed in a .template.config folder in the root directory of the template. このファイルは、テンプレート エンジンに構成情報を提供します。The file provides configuration information to the template engine. 最小構成には、次の表に示すメンバーが必要です。この最小構成があれば、実際に機能するテンプレートが作成されます。The minimum configuration requires the members shown in the following table, which is sufficient to create a functional template.

メンバーMember Type 説明Description
$schema URIURI template.json ファイルの JSON スキーマ。The JSON schema for the template.json file. エディターが JSON スキーマ対応であれば、スキーマの指定時、JSON 編集機能が有効になります。Editors that support JSON schemas enable JSON-editing features when the schema is specified. たとえば、Visual Studio Code の場合、IntelliSense を有効にするためにこのメンバーが必要になります。For example, Visual Studio Code requires this member to enable IntelliSense. 値として http://json.schemastore.org/template を使用します。Use a value of http://json.schemastore.org/template.
author stringstring テンプレートの作成者。The author of the template.
classifications array(string)array(string) テンプレートのゼロ以上の特性。ユーザーがこれを利用し、テンプレートを探すことがあります。Zero or more characteristics of the template that a user might use to find the template when searching for it. dotnet new -l|--list コマンドでテンプレートの一覧を生成したとき、Tags 列が表示される場合、この列にも分類が表示されます。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 このテンプレートの一意の名前。A unique name for this template.
name stringstring ユーザーに対して表示されるテンプレートの名前。The name for the template that users should see.
shortName stringstring テンプレートを選択するための既定の省略名。テンプレート名が GUI 経由で選択されるのではなく、ユーザーによって指定される環境に適用されます。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. たとえば、CLI コマンドでコマンド プロンプトからテンプレートを利用するときに省略名が便利です。For example, the short name is useful when using templates from a command prompt with CLI commands.

template.json ファイルの完全スキーマは JSON Schema Store にあります。The full schema for the template.json file is found at the JSON Schema Store. template.json ファイルについて詳しくは、dotnet テンプレート wiki をご覧ください。For more information about the template.json file, see the dotnet templating wiki.

Example

たとえば、次に示すテンプレート フォルダーには、2 つのコンテンツ ファイル console.csreadme.txt が含まれます。For example, here is a template folder that contains two content files: console.cs and readme.txt. template.json ファイルが含まれる、 .template.config という名前の必須フォルダーがあることに注意してください。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

template.json ファイルは次のようなものです。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"
}

mytemplate フォルダーは、インストール可能なテンプレート パックです。The mytemplate folder is an installable template pack. パックがインストールされたら、shortNamedotnet new コマンドで使うことができます。Once the pack is installed, the shortName can be used with the dotnet new command. たとえば、dotnet new adatumconsole では、console.cs および readme.txt ファイルが現在のフォルダーに出力されます。For example, dotnet new adatumconsole would output the console.cs and readme.txt files to the current folder.

テンプレートをパッケージ化し、NuGet パッケージ (nupkg ファイル) を作成するPacking a template into a NuGet package (nupkg file)

カスタム テンプレートは、dotnet pack コマンドと .csproj ファイルでパッケージ化されます。A custom template is packed with the dotnet pack command and a .csproj file. または、nuget pack コマンドと .nuspec ファイルで NuGet を使うこともできます。Alternatively, NuGet can be used with the nuget pack command along with a .nuspec file. ただし、NuGet の場合、Windows では .NET Framework が、Linux と MacOS では Mono が必要です。However, NuGet requires the .NET Framework on Windows and Mono on Linux and MacOS.

.csproj ファイルは、従来のコード プロジェクトの .csproj ファイルと若干異なります。The .csproj file is slightly different from a traditional code-project .csproj file. 次の設定を確認してください。Note the following settings:

  1. 設定 <PackageType> が追加され、Template に設定されます。The <PackageType> setting is added and set to Template.
  2. 設定 <PackageVersion> が追加され、有効な NuGet のバージョン番号に設定されます。The <PackageVersion> setting is added and set to a valid NuGet version number.
  3. 設定 <PackageId> が追加され、一意の識別子に設定されます。The <PackageId> setting is added and set to a unique identifier. この識別子は、テンプレート パックのアンインストールに使われ、テンプレート パックを登録するために NuGet フィードによって使われます。This identifier is used to uninstall the template pack and is used by NuGet feeds to register your template pack.
  4. ジェネリック メタデータの設定 <Title><Authors><Description><PackageTags> を設定する必要があります。Generic metadata settings should be set: <Title>, <Authors>, <Description>, and <PackageTags>.
  5. テンプレート プロセスによって生成されるバイナリを使わない場合でも、設定 <TargetFramework> を設定する必要があります。The <TargetFramework> setting must be set, even though the binary produced by the template process isn't used. 次の例では、netstandard2.0 に設定されています。In the example below it's set to netstandard2.0.

.nupkg NuGet パッケージの形式のテンプレート パックでは、すべてのテンプレートをパッケージ内の content フォルダーに格納する必要があります。A template pack, in the form of a .nupkg NuGet package, requires that all templates be stored in the content folder within the package. 生成された .nupkg をテンプレート パックとしてインストールできるようにするため、 .csproj ファイルに追加する設定がさらにいくつかあります。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. プロジェクトでコンテンツとして設定されるすべてのファイルを NuGet パッケージに含めるには、設定 <IncludeContentInPack>true に設定します。The <IncludeContentInPack> setting is set to true to include any file the project sets as content in the NuGet package.
  2. コンパイラによって生成されたすべてのバイナリを NuGet パッケージから除外するには、設定 <IncludeBuildOutput>false に設定します。The <IncludeBuildOutput> setting is set to false to exclude all binaries generated by the compiler from the NuGet package.
  3. 設定 <ContentTargetFolders>content に設定します。The <ContentTargetFolders> setting is set to content. これにより、コンテンツとして設定されたファイルは、NuGet パッケージ内の content フォルダーに格納されます。This makes sure that the files set as content are stored in the content folder in the NuGet package. NuGet パッケージのこのフォルダーは、dotnet テンプレート システムによって解析されます。This folder in the NuGet package is parsed by the dotnet template system.

すべてのコード ファイルをテンプレート プロジェクトによってコンパイルされないように除外する簡単な方法は、プロジェクト ファイルの <ItemGroup> 要素内で <Compile Remove="**\*" /> 項目を使うことです。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.

テンプレート パックを構成する簡単な方法は、すべてのテンプレートを個別のフォルダーに格納した後、 .csproj ファイルと同じディレクトリにある templates フォルダーの内部に各テンプレート フォルダーを格納することです。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. これにより、1 つのプロジェクト項目を使って、すべてのファイルとフォルダーをコンテンツとして templates に含めることができます。This way, you can use a single project item to include all files and folders in the templates as content. <ItemGroup> 要素の内部に、<Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> 項目を作成します。Inside of an <ItemGroup> element, create a <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> item.

上記のすべてのガイドラインに従う .csproj ファイルの例を次に示します。Here is an example .csproj file that follows all of the guidelines above. templates 子フォルダーを content パッケージ フォルダーにパッケージ化し、すべてのコード ファイルをコンパイルから除外します。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>

次の例では、 .csproj を使用してテンプレート パックを作成するファイルとフォルダーの構造を示します。The example below demonstrates the file and folder structure of using a .csproj to create a template pack. MyDotnetTemplates.csproj ファイルと templates フォルダーはどちらも、project_folder という名前のディレクトリのルートにあります。The MyDotnetTemplates.csproj file and templates folder are both located at the root of a directory named project_folder. templates フォルダーには、mytemplate1mytemplate2 の 2 つのテンプレートが含まれています。The templates folder contains two templates, mytemplate1 and mytemplate2. 各テンプレートには、コンテンツ ファイルと、template.json 構成ファイルが格納された .template.config フォルダーが含まれます。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

テンプレートをインストールするInstalling a template

パッケージをインストールするには、dotnet new -i|--install コマンドを使います。Use the dotnet new -i|--install command to install a package.

nuget.org に保存されている NuGet パッケージからテンプレートをインストールするにはTo install a template from a NuGet package stored at nuget.org

テンプレート パッケージをインストールするには、NuGet パッケージ識別子を使います。Use the NuGet package identifier to install a template package.

dotnet new -i <NUGET_PACKAGE_ID>

ローカル nupkg ファイルからテンプレートをインストールするにはTo install a template from a local nupkg file

.nupkg NuGet パッケージ ファイルに対するパスを指定します。Provide the path to a .nupkg NuGet package file.

dotnet new -i <PATH_TO_NUPKG_FILE>

ファイル システム ディレクトリからテンプレートをインストールするにはTo install a template from a file system directory

テンプレートはテンプレート フォルダーからインストールできます (上の例の mytemplate1 フォルダーなど)。Templates can be installed from a template folder, such as the mytemplate1 folder from the example above. .template.config フォルダーのフォルダー パスを指定します。Specify the folder path of the .template.config folder. テンプレート ディレクトリへのパスは、絶対パスである必要はありません。The path to the template directory does not need to be absolute. ただし、フォルダーからインストールされたテンプレートをアンインストールするには、絶対パスが必要です。However, an absolute path is required to uninstall a template that is installed from a folder.

dotnet new -i <FILE_SYSTEM_DIRECTORY>

インストールされているテンプレートの一覧を取得するGet a list of installed templates

他のパラメーターを何も指定しない uninstall コマンドでは、インストールされているすべてのテンプレートの一覧が表示されます。The uninstall command, without any other parameters, will list all installed templates.

dotnet new -u

そのコマンドでは、次のような出力が返されます。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
...

Currently installed items: の後の第 1 レベルの項目は、テンプレートのアンインストールで使われる識別子です。The first level of items after Currently installed items: are the identifiers used in uninstalling a template. 上の例では、Microsoft.DotNet.Common.ItemTemplatesMicrosoft.DotNet.Common.ProjectTemplates.3.0 の一覧が表示されています。And in the example above, Microsoft.DotNet.Common.ItemTemplates and Microsoft.DotNet.Common.ProjectTemplates.3.0 are listed. ファイル システム パスを使ってテンプレートをインストールした場合、この識別子は .template.config フォルダーのフォルダー パスです。If the template was installed by using a file system path, this identifier will the folder path of the .template.config folder.

テンプレートをアンインストールするUninstalling a template

パッケージをアンインストールするには、dotnet new -u|--uninstall コマンドを使います。Use the dotnet new -u|--uninstall command to uninstall a package.

NuGet フィードまたは直接 .nupkg ファイルでパッケージをインストールした場合は、識別子を指定します。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>

.template.config フォルダーに対するパスを指定してパッケージをインストールした場合は、その絶対パスを使ってパッケージをアンインストールします。If the package was installed by specifying a path to the .template.config folder, use that absolute path to uninstall the package. テンプレートの絶対パスは、dotnet new -u コマンドによって提供される出力で確認できます。You can see the absolute path of the template in the output provided by the dotnet new -u command. 詳しくは、前の「インストールされているテンプレートの一覧を取得する」セクションをご覧ください。For more information, see the Get a list of installed templates section above.

dotnet new -u <ABSOLUTE_FILE_SYSTEM_DIRECTORY>

カスタム テンプレートを利用してプロジェクトを作成するCreate a project using a custom template

テンプレートがインストールされたら、事前インストールされている他のテンプレートの場合と同様に、dotnet new <TEMPLATE> コマンドを実行してテンプレートを使用します。After a template is installed, use the template by executing the dotnet new <TEMPLATE> command as you would with any other pre-installed template. テンプレートの設定で構成したテンプレート固有のオプションなど、オプションdotnet new コマンドに対して指定することもできます。You can also specify options to the dotnet new command, including template-specific options you configured in the template settings. テンプレートの省略名 (短い名前) をコマンドに直接指定します。Supply the template's short name directly to the command:

dotnet new <TEMPLATE>

関連項目See also