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

[アーティクル]
05/09/2023

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

次の方法で共有

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

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

構成

ソースファイルとフォルダー

template.json

例

テンプレートのローカライズ

例

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

テンプレートパッケージをインストールする

nuget.org に保存されている NuGet パッケージからテンプレートパッケージをインストールするには

カスタム NuGet ソースからテンプレートパッケージをインストールするには

ローカル nupkg ファイルからテンプレートパッケージをインストールするには

ファイルシステムディレクトリからテンプレートパッケージをインストールするには

インストールされているテンプレートパッケージの一覧を取得する

テンプレートパッケージをアンインストールする

カスタムテンプレートを利用してプロジェクトを作成する

関連項目

その他のリソース

次の方法で共有

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

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

構成

ソース ファイルとフォルダー

template.json

例

テンプレートのローカライズ

例

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

テンプレート パッケージをインストールする

nuget.org に保存されている NuGet パッケージからテンプレート パッケージをインストールするには

カスタム NuGet ソースからテンプレート パッケージをインストールするには

ローカル nupkg ファイルからテンプレート パッケージをインストールするには

ファイル システム ディレクトリからテンプレート パッケージをインストールするには

インストールされているテンプレート パッケージの一覧を取得する

テンプレート パッケージをアンインストールする

カスタム テンプレートを利用してプロジェクトを作成する

関連項目

その他のリソース

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

ソースファイルとフォルダー

テンプレートパッケージをインストールする

nuget.org に保存されている NuGet パッケージからテンプレートパッケージをインストールするには

カスタム NuGet ソースからテンプレートパッケージをインストールするには

ローカル nupkg ファイルからテンプレートパッケージをインストールするには

ファイルシステムディレクトリからテンプレートパッケージをインストールするには

インストールされているテンプレートパッケージの一覧を取得する

テンプレートパッケージをアンインストールする

カスタムテンプレートを利用してプロジェクトを作成する