template-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Template Authoring

模板创作

This skill helps an agent create and validate custom

dotnet new

templates. It guides bootstrapping templates from existing projects and validates

template.json

files for authoring issues before publishing.

本Skill可帮助Agent创建和验证自定义

dotnet new

模板。它指导用户从现有项目初始化模板，并在发布前验证

template.json

文件是否存在创作问题。

When to Use

适用场景

User wants to create a reusable template from an existing .csproj
User wants to validate a template.json for correctness
User is setting up
```
.template.config/template.json
```
from scratch
User wants to package a template for NuGet distribution

用户希望从现有.csproj创建可复用模板
用户希望验证template.json的正确性
用户从零开始设置
```
.template.config/template.json
```
用户希望将模板打包为NuGet包进行分发

When Not to Use

不适用场景

User wants to find or use existing templates — route to
```
template-discovery
```
or
```
template-instantiation
```
User has MSBuild issues unrelated to template authoring — route to
```
dotnet-msbuild
```
plugin

用户希望查找或使用现有模板 —— 请转至
```
template-discovery
```
或
```
template-instantiation
```
用户遇到与模板创作无关的MSBuild问题 —— 请转至
```
dotnet-msbuild
```
插件

Inputs

输入参数

Input	Required	Description
Source project path	For creation	Path to the .csproj to use as template source
template.json path	For validation	Path to an existing template.json to validate
Template name	For creation	Human-readable name for the template
Short name	Recommended	Short name for `dotnet new <shortname>` usage

输入项	是否必填	描述
源项目路径	创建模板时必填	作为模板源的.csproj文件路径
template.json路径	验证模板时必填	待验证的现有template.json文件路径
模板名称	创建模板时必填	模板的可读名称
短名称	推荐填写	用于 `dotnet new <shortname>` 命令的短名称

Workflow

工作流程

Step 1: Bootstrap from existing project

步骤1：从现有项目初始化模板

Analyze the source

.csproj

and create a

.template.config/template.json

Create
```
.template.config
```
directory next to the project
Generate
```
template.json
```
with
```
identity
```
(reverse-DNS),
```
name
```
,
```
shortName
```
,
```
sourceName
```
(project name for replacement),
```
classifications
```
, and
```
tags
```
Preserve from source: SDK type, package references with metadata (PrivateAssets, IncludeAssets), properties (OutputType, TreatWarningsAsErrors), CPM patterns

Minimal example:

json

{
  "$schema": "http://json.schemastore.org/template",
  "author": "MyOrg",
  "classifications": ["Library"],
  "identity": "MyOrg.Templates.MyLib",
  "name": "My Library Template",
  "shortName": "mylib",
  "sourceName": "MyLib",
  "tags": { "language": "C#", "type": "project" }
}

分析源

.csproj

文件并创建

.template.config/template.json

：

在项目旁创建
```
.template.config
```
目录
生成包含
```
identity
```
（反向DNS格式）、
```
name
```
、
```
shortName
```
、
```
sourceName
```
（用于替换的项目名称）、
```
classifications
```
和
```
tags
```
的
```
template.json
```
保留源项目中的以下内容：SDK类型、带有元数据（PrivateAssets、IncludeAssets）的包引用、属性（OutputType、TreatWarningsAsErrors）、CPM模式

最小示例：

json

{
  "$schema": "http://json.schemastore.org/template",
  "author": "MyOrg",
  "classifications": ["Library"],
  "identity": "MyOrg.Templates.MyLib",
  "name": "My Library Template",
  "shortName": "mylib",
  "sourceName": "MyLib",
  "tags": { "language": "C#", "type": "project" }
}

Step 2: Validate template.json

步骤2：验证template.json

Read and review the

template.json

for common authoring issues:

Validation checks to perform:

Required fields — verify
```
identity
```
,
```
name
```
, and
```
shortName
```
are present
Identity format — use reverse-DNS format (e.g.,
```
MyOrg.Templates.WebApi
```
)
Parameter issues — check datatypes are valid (
```
string
```
,
```
bool
```
,
```
choice
```
,
```
int
```
,
```
float
```
), choices have defaults, descriptions are present
ShortName conflicts — avoid names that collide with built-in CLI commands (
```
build
```
,
```
run
```
,
```
test
```
,
```
publish
```
). Check with
```
dotnet new list
```
to see if the name is already taken
Post-action completeness — verify post-actions have all required configuration
Tags — ensure language, type, and classification tags are set for discoverability

读取并检查

template.json

，排查常见创作问题：

需执行的验证检查：

必填字段 —— 确认
```
identity
```
、
```
name
```
和
```
shortName
```
已存在
Identity格式 —— 使用反向DNS格式（例如：
```
MyOrg.Templates.WebApi
```
）
参数问题 —— 检查数据类型是否有效（
```
string
```
、
```
bool
```
、
```
choice
```
、
```
int
```
、
```
float
```
）、选项是否有默认值、是否包含描述信息
ShortName冲突 —— 避免与内置CLI命令（
```
build
```
、
```
run
```
、
```
test
```
、
```
publish
```
）重名。可通过
```
dotnet new list
```
命令检查名称是否已被占用
Post-action完整性 —— 验证post-actions是否包含所有必需配置
标签 —— 确保设置了语言、类型和分类标签以提升可发现性

Step 3: Refine the template

步骤3：优化模板

Based on validation results and user requirements:

Add parameters with appropriate types (string, bool, choice), defaults, and descriptions
Add conditional content using
```
#if
```
preprocessor directives for optional features
Configure post-actions for solution add, restore, or custom scripts
Set constraints to restrict which SDKs or workloads the template supports
Add classifications and tags for discoverability

根据验证结果和用户需求：

添加参数，设置合适的类型（string、bool、choice）、默认值和描述
添加条件内容，使用
```
#if
```
预处理指令实现可选功能
配置post-actions，用于添加解决方案、还原依赖或执行自定义脚本
设置约束，限制模板支持的SDK或工作负载
添加分类和标签，提升模板的可发现性

Step 4: Test the template locally

步骤4：本地测试模板

bash

dotnet new install ./path/to/template/root
dotnet new mylib --name TestProject --dry-run
dotnet new mylib --name TestProject --output ./test-output
dotnet build ./test-output/TestProject