作成者向けの.NET テンプレート

テンプレート作成者は、定義済みの構造からプロジェクト、ファイル、またはその他のリソースを生成するブループリント.NETテンプレートを作成します。 ユーザーがdotnet new <shortName>を実行すると、.NET テンプレート エンジンによってテンプレートが読み取られ、現在のディレクトリに出力が生成されます。 Visual Studioの [新しいプロジェクトの作成] ダイアログでは、.NET プロジェクト テンプレート用の.NET テンプレート エンジンも使用されるため、CLI 用に作成したテンプレートもVisual Studioで機能します。

.NET SDK には、コンソール アプリ、クラス ライブラリ、ASP.NET プロジェクトなどの一般的な開始点用の組み込みテンプレートが付属しています。 これらの組み込みテンプレート以外にも、独自のテンプレートを作成し、NuGet パッケージとして配布することができます。

この記事は、テンプレート作成者向けのリファレンスです。 テンプレートの構造化、構成、配布方法について説明します。 テンプレートを作成してパッケージ化する手順については、「 関連コンテンツ 」セクションを参照してください。

テンプレートの種類

.NET テンプレート エンジンでは、項目テンプレート、プロジェクト テンプレート、ソリューション テンプレートの 3 種類のテンプレートがサポートされています。

• 項目テンプレートは 、コード ファイル、構成ファイル、その他のリソースなどの 1 つ以上のファイルを生成します。プロジェクト全体は生成しません。 たとえば、項目テンプレートでは、一連の拡張メソッドを追加するクラス ファイルや、チームが使用する標準レイアウトに従う JSON 構成ファイルが生成される場合があります。 項目テンプレートを作成する方法については、「 チュートリアル: 項目テンプレートを作成する」を参照してください。

• Projectテンプレートは、完全なproject構造を生成します。 たとえば、組み込みのコンソール プロジェクト テンプレートでは、 .csproj ファイル、 Program.cs ファイル、およびプロジェクトを構成するその他のファイルが生成されます。 個々のファイルではなく完全なプロジェクトの開始点をユーザーに提供する場合は、プロジェクト テンプレートを作成します。 プロジェクト テンプレートを作成する方法については、「 チュートリアル: プロジェクト テンプレートを作成する」を参照してください。

• ソリューション テンプレートは、 1 つ以上のプロジェクトを含むソリューションを生成します。 たとえば、ソリューション テンプレートでは、1 つのステップでテスト プロジェクトとペアになった API プロジェクトを作成できます。

独自のテンプレートを作成するときは、template.json構成ファイルの tags.type フィールドを使用してその型を宣言します。 有効な値は、"project"、"item"、および "solution"です。 これらの値を使用すると、ユーザーは dotnet new search または dotnet new listでテンプレートを検索するときに結果をフィルター処理できます。

テンプレート構造

テンプレートはディスク上のフォルダーであり、テンプレート ソース ファイルと特殊な .template.config サブフォルダーの 2 つを含みます。 ユーザーが dotnet new <shortName>実行すると、テンプレート エンジンはソース ファイルを出力場所にコピーし、テンプレートに対して定義した構成を適用します。

mytemplate/
├── console.cs
├── readme.txt
└── .template.config/
    ├── template.json
    └── icon.png

ソース ファイルには、任意の種類のファイルを指定できます。 テンプレート エンジンでは、ソース コードに特別なトークンやマーカーを挿入する必要はありません。 as-isファイルを使用します。つまり、通常の.NET プロジェクトとまったく同じように、テンプレートのソース プロジェクトをビルド、実行、デバッグできます。 既存のプロジェクトをテンプレートにするには、 .template.config/template.json ファイルをプロジェクト ルートに追加します。

必要に応じて、テンプレート パラメーター (シンボル) に関連付けられた置換トークンをテンプレート ソース ファイルとファイル名に直接挿入できます。 トークンが有効なソース コードでない場合は、テンプレートとしてデプロイする前に、ソース プロジェクトをビルド、実行、デバッグすることはできません。 このトークンは、ユーザーがデプロイされたテンプレートから作成するプロジェクトには影響しません。これは、プロジェクトの作成時にテンプレート エンジンによって置き換えられるためです。

.template.config内で必要なファイルはtemplate.jsonだけです。 このファイルは、テンプレート エンジンに必要なもの (テンプレートの名前、短い名前、作成者、分類、およびユーザーがテンプレートから作成するときに渡すことができるすべてのパラメーター) を伝えます。 icon.png ファイルを .template.config フォルダーに配置することもできます。 ターミナルにはアイコンは表示されませんが、Visual Studioは [新しいプロジェクトの作成] ダイアログのテンプレートの横にアイコンを表示します。 128 ×128 PNG は適切に動作します。

template.json ファイル

template.json ファイルは、テンプレートで必要な構成の唯一の部分です。 .template.config フォルダー内に存在し、テンプレートエンジンにテンプレートを提示して処理する方法を指示します。 次の表では、一般的な必須フィールドと省略可能なフィールドについて説明します。

2 つのフィールドには特に注意が必要です。 sourceNameフィールドは、テンプレートが名前付けを処理する方法です。ファイル名とソース コード (MyTemplate など) に表示される文字列に設定すると、テンプレート エンジンはすべての出現箇所を、テンプレートの作成時にユーザーが渡す任意の名前に置き換えます。 classificationsフィールドは検出可能性を制御します。テンプレートの目的を正確に記述するタグを選択して、ユーザーが検索時に見つけられるようにします。

コンソール テンプレートの最小 template.json を次に示します。

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": [ "Common", "Console" ],
  "description": "Creates a console application.",
  "identity": "MyCompany.ConsoleTemplate.CSharp",
  "name": "My Console App",
  "shortName": "myconsole",
  "sourceName": "MyConsoleApp",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

完全なスキーマは JSON スキーマ ストアで入手できます。 条件付きファイルのインクルード、作成後のアクション、マルチプロジェクト テンプレートなどの高度な構成オプションについては、dotnet/templating GitHub wiki を参照してください。

テンプレート パラメーター (シンボル)

template.jsonの symbols セクションでは、テンプレートから作成するときにユーザーが渡すことができるパラメーターを定義します。 各シンボルは dotnet new <shortName>の CLI オプションになるため、 ClassName という名前のシンボルは --ClassName になります (短い名前を定義した場合は -C )。

各シンボル エントリは、次の一般的な設定をサポートしています。

replacesとfileRenameの設定は、シンボルが置換を駆動する方法です。 ユーザーが値を指定すると、テンプレート エンジンは、ファイルの内容内で replaces 文字列が出現するたびに、ファイル名内で fileRename 文字列が出現するたびに置き換えられます。 ユーザーが値を指定しない場合は、代わりに defaultValue が使用されます。

たとえば、次の記号を使用すると、ユーザーはテンプレートから作成するときにクラス名を設定できます。 ファイルの名前が変更され、その中のクラスが一致するように更新されます。

"symbols": {
  "ClassName": {
    "type": "parameter",
    "description": "The name of the code file and class.",
    "datatype": "text",
    "replaces": "StringExtensions",
    "fileRename": "StringExtensions",
    "defaultValue": "StringExtensions"
  }
}

このシンボルを定義すると、ユーザーはdotnet new <shortName> --ClassName MyHelpersを実行して、MyHelpersという名前のクラスを含む MyHelpers.cs という名前のファイルを生成できます。 フラグがない場合、ファイルとクラスは既定の名前 StringExtensions保持されます。

テンプレートが公開するパラメーターを確認するには、インストール後に -? を短い名前に渡します。

dotnet new <shortName> -?

テンプレート パッケージ

テンプレート パッケージは、1 つ以上のテンプレートをバンドルする NuGet (.nupkg) ファイルです。 ユーザーがテンプレート パッケージをインストールすると、.NET テンプレート エンジンは、その中のすべてのテンプレートを一度に登録します。 パッケージは、テンプレートを配布する標準的な方法です。 1 つのパッケージを NuGet.org またはプライベート NuGet フィードに発行するか、ローカル .nupkg ファイルを共有すると、ユーザーは 1 つのコマンドでコレクション全体を取得できます。

テンプレート パッケージをビルドするには、コンパイル プロジェクトではなくパッケージ プロジェクトとして機能するように構成された C# プロジェクト ファイル (.csproj) を使用します。 この作業を行う主な設定は次のとおりです。

templatepack プロジェクト テンプレートは、パッケージ化プロジェクトを作成する最も簡単な方法を提供します。

1. Microsoftをインストールします。TemplateEngine.Authoring.Templates NuGet パッケージ:

   dotnet new install Microsoft.TemplateEngine.Authoring.Templates
   

2. パッケージ 化プロジェクトを作成します。

   dotnet new templatepack -n <PackageName>
   

生成されたプロジェクトには、正しい .csproj 設定、テンプレートの content フォルダー、テンプレート検証とオプションのローカライズのための MSBuild タスクが含まれます。

テンプレート パッケージの作成、パッキング、発行の完全なチュートリアルについては、「 チュートリアル: テンプレート パッケージを作成する」を参照してください。

テンプレートをローカルでテストする

テンプレートの開発時に、最初にパッケージをビルドせずに、そのフォルダーから直接テンプレートをインストールしてテストします。 .template.config フォルダーを含むディレクトリへのパスを渡します。

dotnet new install ./mytemplate/

インストールされているすべてのテンプレート パッケージと、各パッケージをアンインストールするための正確なコマンドを表示するには、引数なしで dotnet new uninstall を実行します。

dotnet new uninstall

ディレクトリからインストールされたテンプレートをアンインストールするには、インストールに使用したのと同じディレクトリ パスを渡します。

dotnet new uninstall ./mytemplate/

テンプレートを共有する準備ができたら、それを NuGet パッケージとしてパックし ( テンプレート パッケージを参照)、配布します。 ユーザーは、 dotnet new install と次のいずれかのソース引数を使用して、発行されたテンプレートをインストールします。

• NuGet パッケージ ID。現在のディレクトリ用に構成された NuGet ソースから最新の安定バージョンをインストールします。

  dotnet new install AdatumCorporation.ConsoleTemplate.CSharp
  

• カスタム フィード URL を持つ NuGet パッケージ ID。 --nuget-source オプションでは、構成済みの NuGet ソースに加えて、指定したフィードが、そのインストールでのみ使用されます。

  dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json
  

• ローカル .nupkg ファイルへのパス:

  dotnet new install ./AdatumCorporation.ConsoleTemplate.CSharp.1.0.0.nupkg
  

NuGet ソースまたはローカル .nupkg ファイルからインストールされているパッケージをアンインストールするには、NuGet パッケージ ID を使用します。

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

組み込みの SDK テンプレートはアンインストールリストに表示されないため、 dotnet new uninstallでは削除できません。

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

.NET テンプレート エンジンは、テンプレート メタデータのオプションのローカライズをサポートしています。 ローカライズ ファイルを指定すると、dotnet newや [Visual Studio新しいProject] ダイアログなどのホストに、元の作成された言語ではなく、テンプレートの名前、説明、シンボル情報がユーザーの言語で表示されます。

次のテンプレート フィールドはローカライズをサポートしています。

• name
• author
• description
• シンボル description と displayName
• 選択肢パラメーター内の各選択肢の説明と表示名
• アクションの description 後と manualInstructions

ローカライズを追加するには、.template.config内に localize サブフォルダーを作成し、言語ごとに 1 つの JSON ファイルを追加します。 各ファイルtemplatestrings.<lang-code>.jsonに名前を付けます。<lang-code>は、pt-BR、zh-Hans、deなど、有効なCultureInfo名と一致します。 各ファイルには、入れ子になったフィールドの区切り記号として/を使用して、キーがtemplate.json内の要素へのパスであるキーと値のペアが含まれています。

たとえば、次の内容の template.json を指定します。

{
  "$schema": "https://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."
}

テンプレート エンジンは、テンプレート情報を読み込むときにこれらのファイルを解析し、現在の UI カルチャに基づいてローカライズされた値を自動的に返します。ユーザーに追加の手順は必要ありません。

ローカライズは省略可能です。 ローカライズ ファイルを含めない場合、テンプレートは正常に動作し、常に template.jsonの値が表示されます。 詳細については、 dotnet/templating Wiki のローカライズ ページを参照してください。

Visual Studio の統合

Visual Studioの [新しいプロジェクトの作成] ダイアログでは、プロジェクト テンプレートに.NET テンプレート エンジン.NET使用します。 dotnet new用に作成したテンプレートは、追加の構成なしで、Visual Studioでも機能します。 ユーザーがdotnet new installを使用してテンプレート パッケージをインストールすると、Visual Studioは自動的にテンプレートを検出し、ダイアログに表示します。

Projectとソリューション テンプレートは、組み込みの SDK テンプレートと共に [新しいprojectの作成] ダイアログに表示されます。 ユーザーは、テンプレートのtemplate.json ファイルの classifications フィールドから、名前、言語、またはタグでテンプレートを検索できます。 正確な分類は、テンプレートが適切なフィルター カテゴリに表示されるのに役立つため、慎重に選択してください。 ダイアログでテンプレートを洗練された外観にするには、.template.config フォルダーにicon.pngを追加Visual Studio、テンプレートの名前の横に表示されます。

アイテム テンプレートは 現在、[ 追加>新しいアイテム ] ダイアログには表示されません。 ユーザーは、ターミナルの dotnet new コマンドで項目テンプレートを引き続き使用できます。

まだインストールしていないユーザー Visual Studioテンプレートを検出できるようにするには、テンプレート パッケージを nuget.org に発行します。[新しいプロジェクトの作成] ダイアログには、テンプレート パッケージの nuget.org を検索するオンライン検索オプションからさらにテンプレートをインストールする機能が含まれています。 ユーザーがそのオプションを使用してパッケージをインストールすると、Visual Studioはdotnet new installと同じインストール メカニズムを使用します。

テンプレートの並べ替え順序の制御や IDE 固有の追加オプションの構成など、Visual Studio固有の統合に関する詳細なガイダンスについては、Sayed Hashimi のテンプレート サンプル リポジトリを参照してください。

関連するコンテンツ

• チュートリアル: 項目テンプレートを作成する
• チュートリアル: プロジェクト テンプレートを作成する
• チュートリアル: テンプレート パッケージを作成する
• dotnet new コマンド
• dotnet/templating GitHub repo wiki
• テンプレートのサンプル