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

.NET SDK には、多くのテンプレートが既にインストールされており、使用する準備が整っています。 dotnet new コマンドは、テンプレートを使用する方法だけでなく、テンプレートをインストールおよびアンインストールする方法でもあります。 アプリ、サービス、ツール、クラス ライブラリなど、任意の種類のプロジェクト用に独自のカスタム テンプレートを作成できます。 構成ファイルなど、1 つ以上の独立したファイルを出力するテンプレートを作成することもできます。

NuGet .nupkg ファイルを直接参照するか、テンプレートを含むファイル システム ディレクトリを指定することで、NuGet パッケージから任意の NuGet フィードにカスタム テンプレートをインストールできます。 テンプレート エンジンには、テンプレートの使用時に値の置換、ファイルのインクルードと除外、カスタム処理操作の実行を行う機能が用意されています。

テンプレート エンジンはオープン ソースであり、オンライン コード リポジトリは GitHub の dotnet/templating にあります。 dotnet new searchを使用して、サード パーティのテンプレートなど、その他のテンプレートを見つけることができます。 カスタム テンプレートの作成と使用の詳細については、「dotnet new および dotnet/templating GitHub リポジトリ Wiki用の独自のテンプレートを作成する方法」を参照してください。

チュートリアルに従ってテンプレートを作成するには、「 dotnet の新しいチュートリアル用のカスタム テンプレートを作成する」 を参照してください。

.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 フォルダーに配置されます。 このファイルは、テンプレート エンジンに構成情報を提供します。 最小構成では、次の表に示すメンバーが必要です。これは、機能テンプレートを作成するのに十分です。

template.json ファイルの完全なスキーマは、JSON スキーマ ストアにあります。 template.json ファイルの詳細については、dotnet テンプレート wiki を参照してください。 Visual Studio でテンプレートを表示する方法の詳細な例と情報については、 Sayed Hashimi によって作成されたリソースを確認してください。

例

たとえば、console.csと readme.txt の 2 つのコンテンツ ファイルを含むテンプレート フォルダーを次 に示します 。 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 と同じ言語で表示されます。 新しいテンプレートを作成する場合、ローカライズは省略可能です。

テンプレートのローカライズ可能な要素は次のとおりです。

• 名前
• 著者
• 説明
• シンボル
  • 説明
  • 表示される名前
  • 選択パラメーターの説明と選択肢の表示名
• 投稿操作
  • 説明
  • 取扱説明書

ローカライズ ファイルには 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 を .nuspec ファイルと共に nuget pack コマンドと共に使用することもできます。 ただし、NuGet には Windows 上の .NET Framework と Linux および macOS 上の Mono が必要です。

.csproj ファイルは、従来のコード プロジェクトの .csproj ファイルとは若干異なります。 次の設定に注意してください。

1. <PackageType>設定が追加され、Templateに設定されます。
2. <PackageVersion>設定が追加され、有効な NuGet バージョン番号に設定されます。
3. <PackageId>設定が追加され、一意の識別子に設定されます。 この識別子はテンプレート パックをアンインストールするために使用され、NuGet フィードによってテンプレート パックを登録するために使用されます。
4. 汎用メタデータ設定は、 <Title>、 <Authors>、 <Description>、および <PackageTags>に設定する必要があります。
5. テンプレート プロセスによって生成されたバイナリが使用されていない場合でも、 <TargetFramework> 設定を設定する必要があります。 次の例では、 netstandard2.0に設定されています。

テンプレート パッケージは、 .nupkg NuGet パッケージの形式で、すべてのテンプレートをパッケージ内の コンテンツ フォルダーに格納する必要があります。 生成された .nupkg をテンプレート パックとしてインストールできるように、.csproj ファイルに追加する設定がいくつかあります。

1. <IncludeContentInPack>設定はtrueに設定され、プロジェクトがコンテンツとして設定するすべてのファイルが NuGet パッケージに含まれます。
2. <IncludeBuildOutput>設定はfalseに設定され、コンパイラによって生成されたすべてのバイナリが NuGet パッケージから除外されます。
3. <ContentTargetFolders>設定はcontentに設定されます。 これにより、 コンテンツ として設定されたファイルが NuGet パッケージの コンテンツ フォルダーに格納されます。 NuGet パッケージ内のこのフォルダーは、dotnet テンプレート システムによって解析されます。

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

テンプレート パックを簡単に構成するには、すべてのテンプレートを個々のフォルダーに配置し、.csproj ファイルと同じディレクトリにあるテンプレート フォルダー内の各テンプレート フォルダーを配置します。 これにより、1 つのプロジェクト項目を使用して、 テンプレート 内のすべてのファイルとフォルダーを コンテンツとして含めることができます。 <ItemGroup>要素内に、<Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />項目を作成します。

次に示すのは、これらすべてのガイドラインに従う .csproj ファイルの例です。 テンプレートの子フォルダーをコンテンツ パッケージ フォルダーにパックし、コード ファイルをコンパイルから除外します。

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

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

アンインストール コマンドは、他のパラメーターを指定せずに、インストールされているすべてのテンプレート パッケージと含まれるテンプレートを一覧表示します。

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:後の項目の最初のレベルは、テンプレート パッケージのアンインストールで使用される識別子です。 前の例では、 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 用のカスタム テンプレートを作成する (チュートリアル)
• dotnet/templating GitHub リポジトリ Wiki
• テンプレートのサンプル
• dotnet new 用の独自のテンプレートを作成する方法
• JSON スキーマ ストアにある template.jsonスキーマ