template-validation

テンプレートの検証

このスキルは、公開前にカスタムの dotnet new テンプレートが正しいかどうかを検証するのに役立ちます。テンプレートの作成ミスとしてよくあるもの、つまり、テンプレートが気付かれないまま失敗したり、壊れたプロジェクトを生成したり、dotnet new list に表示されなくなったりする原因を見つける検証ルールがまとめられています。

使用する場合

• ユーザーが template.json ファイルの確認や検証を求めている
• 「インストールしたのにテンプレートが表示されない」とユーザーが報告している
• ユーザーが NuGet にパッケージ化して公開する前にテンプレートをレビューしたい
• ユーザーがカスタムテンプレートの予期しない動作に遭遇している

使用しない場合

• ユーザーが既存のテンプレートを探したり使用したりしたい場合は、template-discovery に案内します
• ユーザーがプロジェクトを作成したい場合は、template-instantiation に案内します
• ユーザーが既存のプロジェクトからテンプレートを作成したい場合は、template-authoring に案内します

入力

入力	必須	説明
template.json のパス	はい	template.json ファイル、または .template.config/template.json を含むテンプレートディレクトリのパス

検証ルール

template.json をレビューする際は、以下のすべてのカテゴリを体系的に確認します。各指摘事項をエラー、警告、または提案として報告します。

構文解析ゲート — 構文エラーがあれば停止します。 意味に関するルールを適用する前に JSON を解析します。解析に失敗した場合は、パーサーが示す行と列を報告し、具体的な構文修正を最小限だけ示して停止します。解析できなかったドキュメントから、必須フィールド、シンボル、後処理アクション、または検出可能性に関する指摘事項を推測してはいけません。意味に関する主張を行う前に、修正後の JSON を再解析します。

不正な JSON に対する最終回答は、解析結果を示す1行と、正確な編集内容を示す修正済みスニペットの2つだけで構成します。意味に関する推奨事項、任意のメタデータ、またはマニフェスト全体の置き換えを追加してはいけません。

1. 必須フィールド

フィールド	重要度	ルール
identity	エラー	存在し、空でないこと
name	エラー	存在し、空でないこと
shortName	エラー	存在し、空でないこと
sourceName	警告	これがないと、--name で生成されるプロジェクト名をカスタマイズできません
author	警告	テンプレートの検出可能性が高まります
description	提案	テンプレートが何を作成するかをユーザーが理解するのに役立ちます
classifications	提案	検索や分類の改善に役立ちます（例：["Web", "API"]）
defaultName	提案	--name が指定されていない場合のデフォルトのプロジェクト名を設定できます

2. Identity の形式

• identity にスペースが含まれている場合はエラーです — ドットまたはハイフンを使用します（例：MyCompany.WebApi.CSharp）
• identity に名前空間の区切り文字（. または -）が含まれていない場合は警告です — 逆 DNS 形式を使用します

3. ShortName の競合

shortName が dotnet new のサブコマンドと一致すると競合します。dotnet new <name> がテンプレートのインスタンス化ではなく、そのサブコマンドとして解析されるためです。インストール済み SDK の予約済み一覧は、dotnet new --help の Commands: セクションから読み取ります。これは信頼できる情報源であり、このルールが古くなるのを防げます。

現在の SDK に含まれるサブコマンドは次のとおりです（あくまで例示であり、バージョンによって異なります。この一覧をハードコードしないでください。実行時の dotnet new --help の出力が基準です）：install、uninstall、update、list、search、details、create。build、run、test、publish などのトップレベルの dotnet 動詞は競合しないことに注意してください。dotnet new test は dotnet test と競合しません。

• shortName が dotnet new --help に表示されるサブコマンドのいずれかと一致する場合（大文字と小文字を区別しない）はエラーです
• shortName が1文字だけの場合は警告です — 検出可能性を高めるには短すぎます
• 注：shortName は文字列または文字列の配列です。すべての値を確認してください

4. シンボルの検証

symbols オブジェクト内の各シンボルについて：

• type フィールドがない場合は ERROR
• type: "parameter" の場合：
  • datatype が指定されていない場合は WARNING（既定値は string）
  • description がない場合は SUGGESTION（--help の出力が改善されます）
  • datatype: "choice" の場合：
    • choices が定義されていない場合は ERROR
    • choices が空の場合は ERROR
    • defaultValue が選択肢のリストに含まれていない場合は ERROR
    • 省略可能（isRequired ではない）で、defaultValue がない場合は WARNING — ユーザーが予期しない動作に遭遇する可能性があります
  • datatype: "bool" の場合：
    • defaultValue が有効なブール値でない場合は ERROR
  • datatype: "int" の場合：
    • defaultValue が有効な整数でない場合は ERROR
  • 有効なデータ型：string、bool、choice、int、float、hex、text
  • データ型が有効なリストにない場合は ERROR
• type: "computed" の場合：
  • value 式がない場合は ERROR
• type: "generated" の場合：
  • generator フィールドがない場合は ERROR
  • 有効なジェネレーター：casing、coalesce、constant、port、guid、now、random、regex、regexMatch、switch、join

カスタムパラメーターのヘルプはテンプレート固有です。グローバルな dotnet new --help ではなく、dotnet new <shortName> --help の下に表示されます。必要に応じてこの前提を正し、どのシンボル定義が無効だとパラメーターが確実に表示されなくなるかを説明してください。

有効な選択肢パラメーターでは、次の例のように、空でない choices オブジェクトを使用します：

"Color": {
  "type": "parameter",
  "datatype": "choice",
  "defaultValue": "Blue",
  "choices": {
    "Blue": { "displayName": "Blue" },
    "Green": { "displayName": "Green" }
  }
}

パラメータープレフィックスの衝突：あるパラメーター名が別のパラメーター名のプレフィックスになっている場合（例：Auth と AuthMode）、WARNING — 式のコンテキストで解析が曖昧になります。

5. ソースの検証

ソース修飾子の条件について：

• 条件文字列でシンボル名が括弧で囲まれていない場合は WARNING — 想定される形式は裸の symbolName ではなく (symbolName) です

6. 後処理の検証

各後処理について：

• actionId がない場合は ERROR
• description がない場合は WARNING — このテキストは、アクションに手動の手順が必要な場合にユーザーに表示されます
• manualInstructions がない場合は SUGGESTION — アクションを自動実行できない場合（例：IDE 内）に表示されます

7. 制約の検証

各制約について：

• type フィールドがない場合は ERROR
• args がない場合は WARNING — ほとんどの制約タイプで引数が必要です
• type: "host" の場合、args がないと ERROR です。args は必須の配列であり、各エントリには hostname が必要です。サポートされている組み込み識別子には、dotnetcli、vs、vs-mac、ide、dotnetcli-preview があります。省略可能な version には、[10.0.100,) のような NuGet のバージョン／範囲構文を使用します。エンジンは引数キーを大文字と小文字を区別せずに照合するため、ドキュメントに記載されている hostName という表記も有効です。pattern や value など、無関係なフィールドは拒否します。
• type: "sdk-version" の場合、args は同じ構文を使用するバージョン文字列または配列です。

8. タグの検証

• language タグがない場合は SUGGESTION — tags.language（例："C#"）を追加すると、dotnet new list --language での絞り込みが改善されます
• type タグがない場合は SUGGESTION — tags.type（例："project" または "item"）を追加すると、分類が改善されます

ワークフロー

ステップ 1：template.json の場所を特定する

ファイルは次の場所にあります：

• 直接指定したパス：path/to/template.json
• テンプレートディレクトリ内：path/to/.template.config/template.json
• .template.config ディレクトリ内：path/.template.config/template.json

ステップ 2：解析して検証する

JSON を読み取ります。形式が正しくない場合は、行番号と列番号を含めて JSON 解析エラーを報告します。 絶対パスでの読み取りに失敗した場合は、ファイルが利用できないと結論づける前に、作業ディレクトリからユーザーが指定した相対パスを使って再試行します。

解析に成功した後に限り、上記の 8 つの検証カテゴリすべてを実行します。エラー、警告、提案はそれぞれ分けて収集します。スキーマに依存する主張は、インストール済みの SDK または現在のテンプレートエンジンのスキーマで確認し、フィールド名だけから実行時の失敗を推測しないでください。

ステップ 3: 結果をレポートする

まず 1 行の判定を先頭に示し、その後に単一の検出事項テーブルを続けます。この断定的な形式が必須です — 検出事項を散文の段落に散りばめないでください。

判定ヘッダー (いずれかを選択):

• ❌ Not ready — N error(s), M warning(s) — エラーがある場合
• ⚠️ Publishable but N warning(s) — エラーはなく、警告がある場合
• ✅ Ready to publish — 0 errors, 0 warnings — エラーも警告もない場合 (任意の提案が依然として該当する場合があります)

次に 1 つのテーブルを、エラー → 警告 → 提案の順に並べます:

Severity	Location (JSON path or line:col)	Issue	Fix
ERROR	shortName	"list" が dotnet new サブコマンドと競合します	distinctive な値に変更します (例: "my-list")
ERROR	symbols.maxRetries.defaultValue	"abc" は有効な int ではありません	数値の既定値を設定します (例: "3")
WARNING	sourceName	置換トークンがありません	ソースプロジェクト名に設定します

すべての ERROR と WARNING には、具体的な修正を含めなければなりません — 修正後の値、JSON スニペット、または具体的な編集指示 (例: 「末尾のカンマを削除する」) であり、問題の言い換えだけではいけません。実行可能な修正を伴わない検出事項は不完全です。これが、有用な検証と一般的な lint を分ける最大の要素です。

最後に合計を記載して締めくくります: 「N error(s), M warning(s), K suggestion(s).」

不正な形式の JSON の場合、出力は意図的に小さくなり、正確に 2 つの部分からなります:

❌ Not ready — JSON parse error at line N, column M: <message>.

<smallest corrected fragment showing the exact edit>

修正されたファイルがパースできるまで、検出事項テーブルや意味的な合計を追加しないでください。

よくある落とし穴

落とし穴	影響
ShortName = "list" または "search"	テンプレートを決して作成できません — dotnet new サブコマンドと競合します
sourceName の欠落	--name MyProject が生成されたファイル内で何も名前変更しません
defaultValue のない Choice パラメーター	任意の choice パラメーターでユーザー体験を混乱させます
無効な datatype 値	テンプレートエンジンがシンボルを無視し、サイレントな失敗を引き起こします
value のない Computed シンボル	テンプレートエンジンがインスタンス化時に例外をスローします
パラメーターのプレフィックス衝突 (Auth と AuthMode)	式の評価が曖昧になります
かっこを伴わないソース条件	条件が正しく評価されない可能性があります
JSON パースが失敗した後に意味的な検証を続行する	検出事項は推測になります。正確なパース修正をレポートして停止してください。
ホスト制約がスカラーの args、無効な dotnet-cli ホスト ID、または無関係なフィールドを使用している	args: [{ "hostname": "dotnetcli", "version": "[10.0.100,)" }] を使用してください; hostName も大文字小文字を区別せずに受け付けられます。

詳細情報

• template.json リファレンス — 完全なスキーマ
• 利用可能なシンボルジェネレーター — ジェネレーターの種類
• ポストアクション レジストリ — アクション ID
• 制約 — 制約の種類