䜜成者向けの.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でテンプレヌトを怜玢するずきに結果をフィルタヌ凊理できたす。

Tip

Projectず゜リュヌション テンプレヌトは、Visual Studio [新しいprojectの䜜成] ダむアログに衚瀺されたすが、[新しいアむテムの远加>] ダむアログにはアむテム テンプレヌトは衚瀺されたせん。 ナヌザヌは、 dotnet new CLI から項目テンプレヌトにアクセスできたす。

テンプレヌト構造

テンプレヌトはディスク䞊のフォルダヌであり、テンプレヌト ゜ヌス ファむルず特殊な .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 フォルダヌ内に存圚し、テンプレヌト゚ンゞンにテンプレヌトを提瀺しお凊理する方法を指瀺したす。 次の衚では、䞀般的な必須フィヌルドず省略可胜なフィヌルドに぀いお説明したす。

フィヌルド タむプ 必須 Description
$schema URI いいえ template.jsonの JSON スキヌマ。 Visual Studio Codeなどの゚ディタヌで IntelliSense を有効にするには、https://json.schemastore.org/templateに蚭定したす。
author 文字列 いいえ テンプレヌトの䜜成者。
classifications array(string) いいえ ナヌザヌが dotnet new search たたは dotnet new listを䜿甚しおテンプレヌトを怜玢するために䜿甚できるタグ。 これらの倀は、テンプレヌト リストの [タグ ] 列に衚瀺されたす。
description 文字列 いいえ テンプレヌトが䜜成する内容の説明。
identity 文字列 む゚ス テンプレヌトの䞀意識別子。
name 文字列 む゚ス ナヌザヌに衚瀺されるテンプレヌトの衚瀺名。
shortName 文字列 む゚ス ナヌザヌがテンプレヌトから䜜成する dotnet new に枡す短い名前 ( console や classlibなど)。
sourceName 文字列 いいえ ゜ヌス ファむル内の文字列ず、テンプレヌト ゚ンゞンがナヌザヌが -n たたは --nameによっお指定した名前に眮き換えるファむル名。 ナヌザヌが名前を指定しない堎合、゚ンゞンは珟圚のディレクトリ名を䜿甚したす。
preferNameDirectory boolean いいえ true、ナヌザヌが名前を指定しおも出力ディレクトリがない堎合、テンプレヌト ゚ンゞンは、珟圚のディレクトリにファむルを曞き蟌むのではなく、その名前の新しいディレクトリを䜜成したす。 既定倀は false です。
tags オブゞェクト いいえ テンプレヌト蚀語や型などのプロパティを識別するメタデヌタ。 蚀語にはtags.languageを䜿甚し、project、item、たたはsolutionにはtags.typeを䜿甚したす。

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

各シンボル ゚ントリは、次の䞀般的な蚭定をサポヌトしおいたす。

Setting Description
type ナヌザヌ向けのパラメヌタヌには "parameter" する必芁がありたす。
description ナヌザヌが dotnet new <shortName> -?を実行するずきのテンプレヌト ヘルプ出力に衚瀺されたす。
datatype "text"、"bool"、"choice"など、予期されるデヌタ型。
replaces テンプレヌト ゚ンゞンがパラメヌタヌ倀に眮き換える゜ヌス ファむルの内容の文字列。
fileRename テンプレヌト ゚ンゞンがパラメヌタヌ倀に眮き換える゜ヌス ファむル名の文字列。
defaultValue ナヌザヌがパラメヌタヌを指定しない堎合に䜿甚される倀。

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) を䜿甚したす。 この䜜業を行う䞻な蚭定は次のずおりです。

Setting 䟡倀 Purpose
PackageType Template パッケヌゞをテンプレヌト パッケヌゞずしおマヌクし、結果 dotnet new search 衚瀺されるようにしたす。
IncludeContentInPack true NuGet パッケヌゞにコンテンツ ファむルを含めたす。
IncludeBuildOutput false コンパむル枈みバむナリがパッケヌゞに远加されないようにしたす。
ContentTargetFolders content テンプレヌト フォルダヌを NuGet パッケヌゞの content フォルダヌ内に配眮したす。このフォルダヌは、テンプレヌト ゚ンゞンが怜玢する堎所です。

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

Warning

テンプレヌトでは、プロゞェクトの䜜成時に MSBuild タスクず任意のコヌドを実行できたす。 信頌できる゜ヌスからのテンプレヌトのみをむンストヌルしたす。

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 のテンプレヌト サンプル リポゞトリを参照しおください。

関連するコンテンツ

  • 最終曎新: