dotnet new のカスタム テンプレート
.NET SDK には、既にインストールされて使用できる状態になっている多くのテンプレートが付属しています。 dotnet new コマンドは、テンプレートを使用する手段であるだけでなく、テンプレートをインストールおよびアンインストールする方法でもあります。 アプリ、サービス、ツール、クラス ライブラリなど、あらゆる種類のプロジェクトを対象に独自のテンプレートを作成できます。 構成ファイルなど、1 つまたは複数の独立ファイルを出力するテンプレートを作成することもできます。
NuGet の .nupkg ファイルを直接参照するか、テンプレートが含まれるファイル システム ディレクトリを指定することで、任意の NuGet フィード上の NuGet パッケージからカスタム テンプレートをインストールできます。 テンプレート エンジンの機能を利用すると、テンプレートを使うときに、値を置き換えたり、ファイルを含めたり除外したり、独自の処理操作を実行したりできます。
テンプレート エンジンはオープン ソースです。オンライン コード リポジトリは GitHub の dotnet/templating にあります。 サード パーティのテンプレートを含む他のテンプレートは、dotnet new search を使用して見つかる可能性があります。 カスタム テンプレートの作成と利用の詳細については、「dotnet new の独自のテンプレートを作成する方法」と「dotnet/templating GitHub リポジトリ Wiki」を参照してください。
注意
テンプレートの例は、dotnet/templating GitHub リポジトリで入手できます。
チュートリアルでテンプレートを作成するには、「dotnet new のカスタム テンプレートを作成する」チュートリアルをご利用ください。
.NET の既定のテンプレート
.NET SDK をインストールすると、コンソール アプリ、クラス ライブラリ、単体テスト プロジェクト、ASP.NET Core アプリ (Angular プロジェクトと React プロジェクトを含む)、構成ファイルなど、プロジェクトやファイルを作成するための 12 個を超える組み込みテンプレートが提供されます。 組み込みテンプレートの一覧を表示するには、dotnet new list コマンドを実行します。
dotnet new list
構成
テンプレートは次の部分から構成されます。
- ソース ファイルとフォルダー。
- 構成ファイル (template.json)。
ソース ファイルとフォルダー
ソース ファイルとフォルダーには、dotnet new <TEMPLATE> コマンドの実行時にテンプレート エンジンで使用されるすべてのファイルとフォルダーが含まれます。 テンプレート エンジンは、ソース コードとして実行可能なプロジェクトを利用し、プロジェクトを生成するように設計されています。 これにはいくつかの利点があります。
- テンプレート エンジンでは、プロジェクトのソース コードに特別なトークンを挿入することを必要としません。
- コード ファイルは特別なファイルではなく、テンプレート エンジンで利用するために変更されることはありません。 そのため、プロジェクトの利用時に通常利用しているツールでテンプレート コンテンツに対応できます。
- 他のプロジェクトの場合と同じように、テンプレート プロジェクトをビルドし、実行し、デバッグします。
- ./.template.config/template.json 構成ファイルをプロジェクトに追加するだけで、既存のプロジェクトからテンプレートを簡単に作成できます。
テンプレートに格納されるファイルやフォルダーは、正式な種類の .NET プロジェクトに限定されません。 テンプレート エンジンで出力として生成されるファイルが 1 つだけであっても、ソース ファイルとフォルダーは、テンプレートを使って作成するすべてのコンテンツで構成できます。
テンプレートによって生成されるファイルは、template.json 構成ファイルで提供するロジックと設定に基づいて変更できます。 ユーザーは、dotnet new <TEMPLATE> コマンドにオプションを渡すことによって、これらの設定を上書きすることができます。 カスタム ロジックの一般的な例は、テンプレートによって展開されるコード ファイル内のクラスや変数に名前を提供する場合です。
template.json
template.json ファイルは、テンプレートのルート ディレクトリの .template.config フォルダーにあります。 このファイルは、テンプレート エンジンに構成情報を提供します。 最小構成には、次の表に示すメンバーが必要です。この最小構成があれば、実際に機能するテンプレートが作成されます。
| メンバー | 種類 | 説明 |
|---|---|---|
$schema |
URI | template.json ファイルの JSON スキーマ。 エディターが JSON スキーマ対応であれば、スキーマの指定時、JSON 編集機能が有効になります。 たとえば、Visual Studio Code の場合、IntelliSense を有効にするためにこのメンバーが必要になります。 値として http://json.schemastore.org/template を使用します。 |
author |
string | テンプレートの作成者。 |
classifications |
array(string) | テンプレートのゼロ以上の特性。ユーザーがこれを利用し、テンプレートを探すことがあります。 dotnet new list コマンドでテンプレートの一覧を生成したとき、Tags 列が表示される場合、この列にも分類が表示されます。 |
identity |
string | このテンプレートの一意の名前。 |
name |
string | ユーザーに対して表示されるテンプレートの名前。 |
shortName |
string | テンプレートを選択するための既定の省略名。テンプレート名が GUI 経由で選択されるのではなく、ユーザーによって指定される環境に適用されます。 たとえば、CLI コマンドでコマンド プロンプトからテンプレートを利用するときに省略名が便利です。 |
sourceName |
string | ユーザーが指定した名前に置き換えるソース ツリー内の名前です。 テンプレート エンジンによって、構成ファイルで示されている sourceName が検索され、ファイル名とファイルの内容で置き換えられます。 置き換えられる値は、テンプレートの実行中に -n または --name オプションを使用して指定できます。 名前が指定されていない場合は、現在のディレクトリが使用されます。 |
preferNameDirectory |
ブール型 | 名前が指定されているが出力ディレクトリが設定されていない場合に、(現在のディレクトリに直接コンテンツを作成するのではなく) テンプレートのディレクトリを作成するかどうかを示します。 既定値は false です。 |
template.json ファイルの完全スキーマは JSON Schema Store にあります。 template.json ファイルについて詳しくは、dotnet テンプレート wiki をご覧ください。 テンプレートを Visual Studio で表示する方法の詳細な例と情報については、Sayed Hashimi が作成したリソースを確認してください。
例
たとえば、次に示すテンプレート フォルダーには、2 つのコンテンツ ファイル console.cs と readme.txt が含まれます。 template.json ファイルが含まれる、.template.config という名前の必須フォルダーもあります。
└───mytemplate
│ console.cs
│ readme.txt
│
└───.template.config
template.json
template.json ファイルは次のようなものです。
{
"$schema": "http://json.schemastore.org/template",
"author": "Travis Chau",
"classifications": [ "Common", "Console" ],
"identity": "AdatumCorporation.ConsoleTemplate.CSharp",
"name": "Adatum Corporation Console Application",
"shortName": "adatumconsole"
}
mytemplate フォルダーは、インストール可能なテンプレート パッケージです。 パッケージがインストールされたら、shortName を dotnet new コマンドで使うことができます。 たとえば、dotnet new adatumconsole では、console.cs および readme.txt ファイルが現在のフォルダーに出力されます。
テンプレートのローカライズ
.NET テンプレートはローカライズ可能です。 テンプレートが現在のロケールに一致する言語用にローカライズされている場合、その要素は CLI と同じ言語で表示されます。 新しいテンプレートを作成する場合、ローカライズは省略可能です。
テンプレートのローカライズ可能な要素は次のとおりです。
- Name
- Author
- 説明
- シンボル
- 説明
- 表示名
- 選択パラメーターに対する選択肢の説明と表示名
- 事後アクション
- 説明
- 手動の手順
ローカライズ ファイルには JSON 形式があり、カルチャごとに 1 つのファイルだけが存在する必要があります。 名前付け規則は templatestrings.<lang code>.json です。ここで lang code は CultureInfo オプションのいずれかに対応しています。 すべてのローカライズ ファイルは、.template-config\localize フォルダー内に配置する必要があります。
ローカライズ JSON は、キーと値のペアで構成されます。
- キーは、ローカライズする
template.jsonの要素への参照です。 要素が子の場合は、完全なパスと/区切り記号を使用します。 - 値は、キーによって指定された要素のローカライズ文字列です。
テンプレートのローカライズについて詳しくは、dotnet テンプレート Wiki のローカライズに関するページをご覧ください。
例
例として、ローカライズ可能なフィールドを含む template.json ファイルを次に示します。
{
"$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."
}
}
}
また、一部のフィールドはポルトガル語 (ブラジル) にローカライズされる必要があります。 ファイル名はカルチャに合わせて templatestrings.pt-BR.json になり、次のようになります。
{
"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."
}
テンプレートをパッケージ化し、NuGet パッケージ (nupkg ファイル) を作成する
カスタム テンプレートは、dotnet pack コマンドと .csproj ファイルでパッケージ化されます。 または、nuget pack コマンドと .nuspec ファイルで NuGet を使うこともできます。 ただし、NuGet の場合、Windows では .NET Framework が、Linux と macOS では Mono が必要です。
.csproj ファイルは、従来のコード プロジェクトの .csproj ファイルと若干異なります。 次の設定を確認してください。
- 設定
<PackageType>が追加され、Templateに設定されます。 - 設定
<PackageVersion>が追加され、有効な NuGet のバージョン番号に設定されます。 - 設定
<PackageId>が追加され、一意の識別子に設定されます。 この識別子は、テンプレート パックのアンインストールに使われ、テンプレート パックを登録するために NuGet フィードによって使われます。 - ジェネリック メタデータの設定
<Title>、<Authors>、<Description>、<PackageTags>を設定する必要があります。 - テンプレート プロセスによって生成されるバイナリを使わない場合でも、設定
<TargetFramework>を設定する必要があります。 次の例では、netstandard2.0に設定されています。
.nupkg NuGet パッケージの形式のテンプレート パッケージでは、すべてのテンプレートをパッケージ内の content フォルダーに格納する必要があります。 生成された .nupkg をテンプレート パックとしてインストールできるようにするため、 .csproj ファイルに追加する設定がさらにいくつかあります。
- プロジェクトでコンテンツとして設定されるすべてのファイルを NuGet パッケージに含めるには、設定
<IncludeContentInPack>をtrueに設定します。 - コンパイラによって生成されたすべてのバイナリを NuGet パッケージから除外するには、設定
<IncludeBuildOutput>をfalseに設定します。 - 設定
<ContentTargetFolders>をcontentに設定します。 これにより、コンテンツとして設定されたファイルは、NuGet パッケージ内の content フォルダーに格納されます。 NuGet パッケージのこのフォルダーは、dotnet テンプレート システムによって解析されます。
すべてのコード ファイルをテンプレート プロジェクトによってコンパイルされないように除外する簡単な方法は、プロジェクト ファイルの <ItemGroup> 要素内で <Compile Remove="**\*" /> 項目を使うことです。
テンプレート パックを構成する簡単な方法は、すべてのテンプレートを個別のフォルダーに格納した後、 .csproj ファイルと同じディレクトリにある templates フォルダーの内部に各テンプレート フォルダーを格納することです。 これにより、1 つのプロジェクト項目を使って、すべてのファイルとフォルダーをコンテンツとして templates に含めることができます。 <ItemGroup> 要素の内部に、<Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> 項目を作成します。
これらのすべてのガイドラインに従う .csproj ファイルの例を次に示します。 templates 子フォルダーを content パッケージ フォルダーにパッケージ化し、すべてのコード ファイルをコンパイルから除外します。
<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 を使用してテンプレート パッケージを作成するファイルとフォルダーの構造を示します。 MyDotnetTemplates.csproj ファイルと templates フォルダーはどちらも、project_folder という名前のディレクトリのルートにあります。 templates フォルダーには、mytemplate1 と mytemplate2 の 2 つのテンプレートが含まれています。 各テンプレートには、コンテンツ ファイルと、template.json 構成ファイルが格納された .template.config フォルダーが含まれます。
project_folder
│ MyDotnetTemplates.csproj
│
└───templates
├───mytemplate1
│ │ console.cs
│ │ readme.txt
│ │
│ └───.template.config
│ template.json
│
└───mytemplate2
│ otherfile.cs
│
└───.template.config
template.json
注意
テンプレート パッケージが dotnet new search の結果に表示されるようにするには、NuGet パッケージの種類を Template に設定します。
テンプレート パッケージをインストールする
テンプレート パッケージをインストールするには、dotnet new install コマンドを使います。
nuget.org に保存されている NuGet パッケージからテンプレート パッケージをインストールするには
テンプレート パッケージをインストールするには、NuGet パッケージ識別子を使います。
dotnet new install <NUGET_PACKAGE_ID>
カスタム NuGet ソースからテンプレート パッケージをインストールするには
カスタム NuGet ソースを指定します (例: https://api.my-custom-nuget.com/v3/index.json)。
dotnet new --install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>
ローカル nupkg ファイルからテンプレート パッケージをインストールするには
.nupkg NuGet パッケージ ファイルに対するパスを指定します。
dotnet new install <PATH_TO_NUPKG_FILE>
ファイル システム ディレクトリからテンプレート パッケージをインストールするには
テンプレートはテンプレート フォルダーからインストールできます (前の例の mytemplate1 フォルダーなど)。 .template.config フォルダーのフォルダー パスを指定します。 テンプレート ディレクトリへのパスは、絶対パスである必要はありません。
dotnet new install <FILE_SYSTEM_DIRECTORY>
インストールされているテンプレート パッケージの一覧を取得する
他のパラメーターを何も指定しない uninstall コマンドでは、インストールされているすべてのテンプレート パッケージおよび含まれているテンプレートの一覧が表示されます。
dotnet new uninstall
そのコマンドでは、次のような出力が返されます。
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
...
Currently installed items: の後の第 1 レベルの項目は、テンプレート パッケージのアンインストールで使われる識別子です。 また、前の例では、Microsoft.Azure.WebJobs.ProjectTemplates が表示されています。 ファイル システム パスを使ってテンプレート パッケージをインストールした場合、この識別子は .template.config フォルダーのフォルダー パスです。 dotnet new install を使用してインストールされたテンプレート パッケージのみが一覧に表示されます。 .NET SDK に組み込まれているテンプレート パッケージは表示されません。
テンプレート パッケージをアンインストールする
テンプレート パッケージをアンインストールするには、dotnet new uninstall コマンドを使います。
NuGet フィードまたは直接 .nupkg ファイルでパッケージをインストールした場合は、識別子を指定します。
dotnet new uninstall <NUGET_PACKAGE_ID>
.template.config フォルダーに対するパスを指定してパッケージをインストールした場合は、そのパスを使ってパッケージをアンインストールします。 テンプレート パッケージの絶対パスは、dotnet new uninstall コマンドによって提供される出力で確認できます。 詳しくは、インストールされているテンプレートの一覧の取得に関するセクションを参照してください。
dotnet new uninstall <FILE_SYSTEM_DIRECTORY>
カスタム テンプレートを利用してプロジェクトを作成する
テンプレートがインストールされたら、事前インストールされている他のテンプレートの場合と同様に、dotnet new <TEMPLATE> コマンドを実行してテンプレートを使用します。 テンプレートの設定で構成したテンプレート固有のオプションなど、オプションを dotnet new コマンドに対して指定することもできます。 テンプレートの省略名 (短い名前) をコマンドに直接指定します。
dotnet new <TEMPLATE>
関連項目
.NET
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示