template-instantiation

テンプレートのインスタンス化

このスキルでは、dotnet new CLI コマンドを使ってテンプレートから .NET プロジェクトを作成し、パラメーターの検証、Central Package Management への対応、複数プロジェクトの構成について説明します。

ワークスペースに合わせてから、作業を終えます。 最も重要なのは、新しいプロジェクトを配置先のリポジトリに合わせることです。CPM（Directory.Packages.props）と、近隣の .csproj ファイルで使われているターゲットフレームワークを検出し、両方を踏襲します。検出したターゲットフレームワークは明示的な選択として扱い、template-smart-defaults に上書きされないよう --framework で指定します。変更するのは、要求された機能と互換性がない場合だけです（その場合は競合を伝えます）。手順はできるだけ少なくします。通常は --dry-run、作成、確認のための dotnet build で十分です。結果を改善しない追加の探索は、コストを増やすだけです。

要求された作成を実行します。 計画や実行する意思の表明だけを返してはいけません。 状態に依存するコマンドは、順番に実行します。調査、ドライラン、作成、 その後にビルドします。作成とビルドを並行して起動してはいけません。作成前にビルドすると競合が発生し、誤った失敗につながります。

状況	必須の対応
シンプルなスタンドアロンプロジェクト	要求されたテンプレートのみを調査し、指定された正確なパスに作成してからビルドします
近隣に既存のプロジェクトがある	まずそれらの TFM を読み取り、対応している一致した --framework を明示的に指定します
Directory.Packages.props が見つかった	対応している場合は --no-restore を指定して作成し、生成されたパッケージ参照を正規化してから、復元／ビルドを一度だけ行います
複数プロジェクトのソリューション	各プロジェクトを最終パスに作成し、参照を追加し、すべてのプロジェクトをソリューションに追加してから、ソリューションを一度だけビルドします
ユーザーが .sln を明示的に要求	dotnet new sln --help を調べ、対応している場合は --format sln を指定します。対応していない場合は、旧 SDK のデフォルトの .sln 出力を使います

生成されるターゲットフレームワークを予測してはいけません。ユーザーやワークスペースから指定が得られない場合は、dotnet new <template> --help を調べ、対応している値（通常はドキュメントに記載されたデフォルト値）を選び、明示的に指定してから、生成された .csproj を確認します。現在のテンプレートの選択肢に根拠のない中間的なフレームワークの推測を、決定事項として伝えてはいけません。

使用する場合

• ユーザーが新しい .NET プロジェクト、アプリ、またはサービスの作成を求めている場合
• ユーザーが複数のプロジェクト（API + テスト + ライブラリ）からなるソリューションを必要としている場合
• ユーザーが既存の Directory.Packages.props に準拠したプロジェクトの作成を求めている場合
• ユーザーがテンプレートパッケージのインストールや管理を必要としている場合

使用しない場合

• ユーザーがテンプレートを探している場合 — template-discovery スキルに案内します。詳細な並列比較を求めている場合は、template-comparison スキルに案内します
• ユーザーがカスタムテンプレートの作成を求めている場合 — template-authoring スキルに案内します
• ユーザーが既存のプロジェクトにパッケージを追加したい場合 — dotnet add package を直接使います

入力

入力	必須	説明
テンプレート名または意図	はい	テンプレートの短い名前（例：webapi）または自然言語による説明
プロジェクト名	はい	作成するプロジェクトの名前
出力パス	推奨	プロジェクトを作成するディレクトリ
パラメーター	いいえ	テンプレート固有のパラメーター（例：--framework、--auth、--aot）

ワークフロー

ステップ 1：テンプレートとパラメーターを解決する

ユーザーが自然言語で説明を提示した場合は、テンプレートの短縮名に対応付けます（template-discovery スキルのキーワード表を参照）。テンプレート名を提示した場合は、そのまま進みます。

ユーザーが指定していないパラメーターについては、dotnet new <template> --help を使って、利用可能なパラメーター、既定値、型を確認します。

ユーザーが選んだパラメーターから、未設定の関連するパラメーターの値が決まる場合は、コマンドラインを組み立てる前に、template-smart-defaults スキルを呼び出して不足を解決します。たとえば、ネイティブ AOT を選ぶ場合は、AOT に対応した新しいターゲットフレームワークが必要です。また、--auth に None 以外を指定した場合は HTTPS を有効のままにする必要があるため、--no-https を追加してはいけません。さらに、--use-controllers を指定した場合は、最小 API オプションを併用できません。スマートデフォルトで補えるのは不足している値だけです。ユーザーが明示的に設定した値を上書きしてはいけません。ステップ 2 で確認したワークスペースのフレームワークも明示的な値として扱います。未設定の項目として扱われないよう、選択した --framework としてスマートデフォルトに渡してください。要求された機能やテンプレートと互換性がない場合に限り、別の値を選び、その競合をユーザーに伝えます。

ステップ 2：ワークスペースを分析する

作成前に、既存のソリューション構成を確認します。

• Central Package Management（CPM）が有効かどうか。Directory.Packages.props を確認します
• 使用中のターゲットフレームワーク。既存の .csproj ファイルを確認します
• SDK のバージョンを固定する global.json があるかどうか

これにより、新しいプロジェクトをワークスペースに合わせられます。

ステップ 3：作成内容をプレビューする

dotnet new <template> --dry-run を使い、作成されるファイルをユーザーに提示します。続行する前に確認を求めます。

dotnet new webapi --name MyApi --framework net10.0 --dry-run

ステップ 4：プロジェクトを作成する

テンプレート名とすべてのパラメーターを指定して dotnet new を実行します。

dotnet new webapi --name MyApi --output ./src/MyApi --framework net10.0 --auth Individual

実行前に、簡潔な判断行を 1 行出力します。

Creating <template> at <path>; framework=<value> (<user|workspace|template>); CPM=<on|off>.

これにより、長いレポートを追加することなく、ワークスペースに合わせた変更を明示できます。

一般的なパラメーターの組み合わせ

テンプレート	パラメーター	例
webapi	--auth (None、Individual、SingleOrg、Windows)、--aot (ネイティブ AOT)	dotnet new webapi -n MyApi --auth Individual --aot
webapi	--use-controllers (コントローラーと最小 API のどちらを使うか)	dotnet new webapi -n MyApi --use-controllers
blazor	--interactivity (None、Server、WebAssembly、Auto)、--auth	dotnet new blazor -n MyApp --interactivity Server
grpc	--aot (ネイティブ AOT)	dotnet new grpc -n MyService --aot
worker	--aot (ネイティブ AOT)	dotnet new worker -n MyWorker --aot

注: 任意のテンプレートで利用可能なすべてのパラメーターを確認するには、dotnet new <template> --help を使用してください。

作成後は、プロジェクトを集中パッケージ管理 (CPM) に適合させ、古くなったバージョンを更新します:

1. 作成前に CPM を検出する — 作成先から上位に向かって Directory.Packages.props を探します。
2. 失敗が確定している自動復元を避ける — CPM が有効で、テンプレートが --no-restore を公開している場合は、作成時にそれを渡して、まずパッケージの集中化が行われるようにします。
3. インラインのバージョンを削除する — 生成された各 <PackageReference Include="X" Version="Y" /> について、Version 属性を削除します (<PackageReference Include="X" /> を残します)。
4. バージョンを集中化する — Directory.Packages.props に <PackageVersion Include="X" Version="Y" /> エントリを追加またはマージします。無関係な既存のエントリは保持します。
5. 必要に応じて古くなったテンプレート既定バージョンを更新する — テンプレートは古いバージョンをハードコードしていることがよくあります。既定ではテンプレートのバージョンを維持します (再現性と制御されたアップグレードのために最も安全です)。更新するのはユーザーが求めた場合のみとし、その際は:
   • ツール駆動のフローを優先します: dotnet list package --outdated を実行し、何かを変更する前に提案されたバンプをユーザーに確認します。
   • クロスメジャーのバンプは破壊的変更を招く可能性があるため、ユーザーが明示的に大きなアップグレードを選択しない限り、アップグレードを同じ メジャー (またはメジャー/マイナー) バージョンに制限します。
   • パッケージの最新の 安定 バージョンを概念的には把握しつつ確認する場合、そのパッケージ ID の NuGet V3 フラットコンテナーの index.json エンドポイントに公開済みバージョンが一覧表示されます。要求されない限り、プレリリースを選択しないでください。
6. ビルド — dotnet build を一度実行して復元し、集中化/更新されたバージョンが解決されることを確認します。

ステップ 5: マルチプロジェクトの構成 (任意)

複雑な構造の場合は、各プロジェクトを順番に作成し、それらを連携させます:

dotnet new webapi --name MyApi --output ./src/MyApi
dotnet new xunit --name MyApi.Tests --output ./tests/MyApi.Tests
dotnet add ./tests/MyApi.Tests reference ./src/MyApi
dotnet sln add ./src/MyApi ./tests/MyApi.Tests

ステップ 6: テンプレートパッケージの管理

テンプレートパッケージをインストールまたはアンインストールします:

dotnet new install Microsoft.DotNet.Web.ProjectTemplates.10.0
dotnet new uninstall Microsoft.DotNet.Web.ProjectTemplates.10.0

ステップ 7: 作成後の検証

1. プロジェクトがビルドできることを確認します: dotnet build
2. console のような実行可能なテンプレートの場合、リクエストが 単純で外部サービスが不要であれば、生成されたアプリを実行します。ビルドの成功だけでなく、 観察された出力を報告します。
3. ソリューションに追加した場合は、ソリューションレベルで dotnet build を検証します
4. CPM を適合させた場合は、Directory.Packages.props に新しいエントリがあることを検証します

検証

• プロジェクトが期待されるファイルとともに正常に作成された
• プロジェクトが dotnet build でクリーンにビルドされる
• CPM が有効な場合、.csproj にバージョン属性がなく、Directory.Packages.props に対応するエントリがある
• プロジェクト内のパッケージバージョンが最新である (古いテンプレート既定値ではない)
• マルチプロジェクトの場合、すべてのプロジェクトがビルドされ、正しく相互参照している

よくある落とし穴

落とし穴	解決策
プロジェクトを作成する前に CPM を確認しない	Directory.Packages.props が存在する場合、dotnet new はインラインバージョンを含むプロジェクトを作成するため、競合が発生します。作成後、バージョンを Directory.Packages.props に移し、.csproj から削除してください。
CPM に対応する前にテンプレートの復元を失敗させてしまう	まず CPM を検出し、利用可能な場合はテンプレートの --no-restore オプションを使用してください。最初の復元／ビルドの前にバージョンを一元管理してください。
フレームワークを指定せずにプロジェクトを作成する	古いバージョンがデフォルトで選択されるのを避けるため、テンプレートが複数の TFM をサポートしている場合は、必ず --framework を指定してください。
ソリューションにプロジェクトを追加しない	作成後、dotnet sln add を実行してプロジェクトをソリューションに含めてください。
プロジェクトがビルドできることを確認しない	不足している依存関係やパラメーターの問題を早期に検出するため、作成後は必ず dotnet build を実行してください。

詳細情報

• 中央パッケージ管理 — CPM のドキュメント
• dotnet new — CLI リファレンス