template-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Template Validation

模板验证

This skill helps validate custom

dotnet new

templates for correctness before publishing. It encodes the validation rules that catch common authoring mistakes — issues that cause templates to silently fail, produce broken projects, or not appear in

dotnet new list

本技能可帮助在发布前验证自定义

dotnet new

模板的正确性。它内置了验证规则，能够捕获常见的创作错误——这些错误会导致模板静默失败、生成损坏的项目或无法在

dotnet new list

中显示。

When to Use

适用场景

User asks to check or validate a template.json file
User reports "my template doesn't show up after installing"
User wants to review a template before packaging and publishing to NuGet
User encounters unexpected behavior from a custom template

用户要求检查或验证template.json文件
用户反馈“我的模板安装后不显示”
用户希望在打包并发布到NuGet前审查模板
用户遇到自定义模板的意外行为

When Not to Use

不适用场景

User wants to find or use existing templates — route to
```
template-discovery
```
User wants to create a project — route to
```
template-instantiation
```
User wants to create a template from an existing project — route to
```
template-authoring
```

用户想要查找或使用现有模板——请转至
```
template-discovery
```
用户想要创建项目——请转至
```
template-instantiation
```
用户想要从现有项目创建模板——请转至
```
template-authoring
```

Inputs

输入参数

Input	Required	Description
template.json path	Yes	Path to the template.json file or the template directory containing `.template.config/template.json`

输入	是否必填	描述
template.json路径	是	template.json文件的路径，或包含 `.template.config/template.json` 的模板目录路径

Validation Rules

验证规则

When reviewing a template.json, check ALL of the following categories systematically. Report every finding as an error, warning, or suggestion.

审查template.json时，请系统检查以下所有类别。将每个发现结果报告为错误、警告或建议。

1. Required Fields

1. 必填字段

Field	Severity	Rule
`identity`	ERROR	Must be present and non-empty
`name`	ERROR	Must be present and non-empty
`shortName`	ERROR	Must be present and non-empty
`sourceName`	WARNING	Without it, `--name` won't customize the generated project name
`author`	WARNING	Improves template discoverability
`description`	SUGGESTION	Helps users understand what the template creates
`classifications`	SUGGESTION	Improves search and categorization (e.g., `["Web", "API"]` )
`defaultName`	SUGGESTION	Provides a fallback project name when `--name` is not specified

字段	严重程度	规则
`identity`	错误	必须存在且非空
`name`	错误	必须存在且非空
`shortName`	错误	必须存在且非空
`sourceName`	警告	缺少该字段时， `--name` 参数无法自定义生成的项目名称
`author`	警告	有助于提高模板的可发现性
`description`	建议	帮助用户理解模板创建的内容
`classifications`	建议	有助于搜索和分类（例如： `["Web", "API"]` ）
`defaultName`	建议	当未指定 `--name` 时，提供一个备用项目名称

2. Identity Format

2. 标识格式

ERROR if identity contains spaces — use dots or dashes (e.g.,
```
MyCompany.WebApi.CSharp
```
)
WARNING if identity has no namespace separator (
```
.
```
or
```
-
```
) — use reverse-DNS format

如果identity包含空格则为错误——请使用点或短横线（例如：
```
MyCompany.WebApi.CSharp
```
）
如果identity没有命名空间分隔符（
```
.
```
或
```
-
```
）则为警告——请使用反向DNS格式

3. ShortName Conflicts

3. ShortName冲突

The following short names conflict with dotnet CLI commands and will cause problems:

new

build

run

test

publish

restore

clean

pack

add

remove

list

nuget

tool

sln

help

ERROR if shortName matches any reserved name (case-insensitive)
WARNING if shortName is only 1 character — too short for discoverability
Note: shortName can be a string or an array of strings; check all values

以下短名称与dotnet CLI命令冲突，会导致问题：

new

build

run

test

publish

restore

clean

pack

add

remove

list

nuget

tool

sln

help

如果shortName与任何保留名称匹配（不区分大小写）则为错误
如果shortName仅为1个字符则为警告——太短不利于发现
注意：shortName可以是字符串或字符串数组；请检查所有值

4. Symbol Validation

4. 符号验证

For each symbol in the

symbols

object:

ERROR if a symbol is missing the
```
type
```
field
For
```
type: "parameter"
```
:
- WARNING if no
```
datatype
```
  specified (defaults to
```
string
```
  )
- SUGGESTION if no
```
description
```
  (improves
```
--help
```
  output)
- If
```
datatype: "choice"
```
  :
  - ERROR if no
```
choices
```
    defined
  - ERROR if
```
choices
```
    is empty
  - ERROR if
```
defaultValue
```
    is not in the choices list
  - WARNING if optional (not
```
isRequired
```
    ) and no
```
defaultValue
```
    — users get unexpected behavior
- If
```
datatype: "bool"
```
  :
  - ERROR if
```
defaultValue
```
    is not a valid boolean
- If
```
datatype: "int"
```
  :
  - ERROR if
```
defaultValue
```
    is not a valid integer
- Valid datatypes:
```
string
```
  ,
```
bool
```
  ,
```
choice
```
  ,
```
int
```
  ,
```
float
```
  ,
```
hex
```
  ,
```
text
```
- ERROR if datatype is not in the valid list
For
```
type: "computed"
```
:
- ERROR if missing
```
value
```
  expression

For

type: "generated"

ERROR if missing
```
generator
```
field

Valid generators:

casing

coalesce

constant

port

guid

now

random

regex

regexMatch

switch

join

Parameter prefix collisions: WARNING if any parameter name is a prefix of another parameter name (e.g.,

Auth

and

AuthMode

) — this creates ambiguous parsing in expression contexts.

对于

symbols

对象中的每个符号：

如果符号缺少
```
type
```
字段则为错误
对于
```
type: "parameter"
```
：
- 如果未指定
```
datatype
```
  则为警告（默认值为
```
string
```
  ）
- 如果没有
```
description
```
  则为建议（有助于提升
```
--help
```
  输出的可读性）
- 如果
```
datatype: "choice"
```
  ：
  - 如果未定义
```
choices
```
    则为错误
  - 如果
```
choices
```
    为空则为错误
  - 如果
```
defaultValue
```
    不在choices列表中则为错误
  - 如果是可选参数（未设置
```
isRequired
```
    ）且没有
```
defaultValue
```
    则为警告——用户会遇到意外行为
- 如果
```
datatype: "bool"
```
  ：
  - 如果
```
defaultValue
```
    不是有效的布尔值则为错误
- 如果
```
datatype: "int"
```
  ：
  - 如果
```
defaultValue
```
    不是有效的整数则为错误
- 有效的数据类型：
```
string
```
  ,
```
bool
```
  ,
```
choice
```
  ,
```
int
```
  ,
```
float
```
  ,
```
hex
```
  ,
```
text
```
- 如果datatype不在有效列表中则为错误
对于
```
type: "computed"
```
：
- 如果缺少
```
value
```
  表达式则为错误

对于

type: "generated"

：

如果缺少
```
generator
```
字段则为错误

有效的生成器：

casing

coalesce

constant

port

guid

now

random

regex

regexMatch

switch

join

参数前缀冲突：如果任何参数名称是另一个参数名称的前缀（例如：

Auth

和

AuthMode

）则为警告——这会在表达式上下文中导致解析歧义。

5. Sources Validation

5. 源验证

For source modifier conditions:

WARNING if a condition string doesn't contain parentheses around symbol names — expected format is
```
(symbolName)
```
, not bare
```
symbolName
```

对于源修饰符条件：

如果条件字符串中的符号名称没有用括号包裹则为警告——预期格式为
```
(symbolName)
```
，而非裸写的
```
symbolName
```

6. Post-Action Validation

6. Post-Action验证

For each post-action:

ERROR if missing
```
actionId
```
WARNING if missing
```
description
```
— this text is shown to users when the action requires manual steps
SUGGESTION if missing
```
manualInstructions
```
— these are shown when the action can't run automatically (e.g., in an IDE)

对于每个post-action：

如果缺少
```
actionId
```
则为错误
如果缺少
```
description
```
则为警告——当操作需要手动步骤时，该文本会显示给用户
如果缺少
```
manualInstructions
```
则为建议——当操作无法自动运行时（例如在IDE中）会显示这些说明

7. Constraint Validation

7. 约束验证

For each constraint:

ERROR if missing
```
type
```
field
WARNING if missing
```
args
```
— most constraint types require arguments

对于每个约束：

如果缺少
```
type
```
字段则为错误
如果缺少
```
args
```
则为警告——大多数约束类型需要参数

8. Tags Validation

8. 标签验证

SUGGESTION if no
```
language
```
tag — adding
```
tags.language
```
(e.g.,
```
"C#"
```
) improves filtering in
```
dotnet new list --language
```
SUGGESTION if no
```
type
```
tag — adding
```
tags.type
```
(e.g.,
```
"project"
```
or
```
"item"
```
) improves categorization

如果没有
```
language
```
标签则为建议——添加
```
tags.language
```
（例如：
```
"C#"
```
）有助于在
```
dotnet new list --language
```
中进行筛选
如果没有
```
type
```
标签则为建议——添加
```
tags.type
```
（例如：
```
"project"
```
或
```
"item"
```
）有助于分类

Workflow

工作流程

Step 1: Locate the template.json

步骤1：定位template.json

The file can be at:

Direct path:
```
path/to/template.json
```
In a template directory:
```
path/to/.template.config/template.json
```

In a

.template.config

directory:

path/.template.config/template.json

文件可能位于：

直接路径：
```
path/to/template.json
```
模板目录中：
```
path/to/.template.config/template.json
```

.template.config

目录中：

path/.template.config/template.json

Step 2: Parse and validate

步骤2：解析并验证

Read the JSON. If it's malformed, report the JSON parse error with line number.

Run all 8 validation categories above. Collect errors, warnings, and suggestions separately.

读取JSON。如果格式错误，报告JSON解析错误及行号。

运行上述所有8个验证类别。分别收集错误、警告和建议。

Step 3: Report results

步骤3：报告结果

Present findings organized by severity:

Errors (must fix) — template will not work correctly
Warnings (should fix) — template may cause confusion or limited functionality
Suggestions (nice to have) — improvements for discoverability and user experience

Include the total: "X error(s), Y warning(s), Z suggestion(s)"

按严重程度组织展示发现结果：

错误（必须修复）——模板无法正常工作
警告（应该修复）——模板可能导致混淆或功能受限
建议（可选优化）——提升可发现性和用户体验

包含统计总数：“X个错误，Y个警告，Z个建议”

Common Pitfalls

常见陷阱

Pitfall	Impact
ShortName = "test" or "build"	Template can never be created — conflicts with CLI
Missing `sourceName`	`--name MyProject` doesn't rename anything in the generated files
Choice parameter without `defaultValue`	Confusing user experience on optional choice params
Invalid `datatype` value	Template engine ignores the symbol, causing silent failures
Computed symbol without `value`	Template engine throws at instantiation time
Parameter prefix collision ( `Auth` vs `AuthMode` )	Ambiguous expression evaluation
Source condition without parentheses	Condition may not evaluate correctly

陷阱	影响
ShortName = "test"或"build"	模板永远无法创建——与CLI命令冲突
缺少 `sourceName`	`--name MyProject` 无法重命名生成文件中的任何内容
选择参数没有 `defaultValue`	可选选择参数的用户体验混乱
无效的 `datatype` 值	模板引擎会忽略该符号，导致静默失败
计算符号没有 `value`	模板引擎在实例化时抛出错误
参数前缀冲突（ `Auth` vs `AuthMode` ）	表达式求值歧义
源条件没有括号	条件可能无法正确求值