Back to Details

template-instantiation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Template Instantiation

模板实例化

This skill creates .NET projects from templates using 
dotnet new
CLI commands, with guidance for parameter validation, Central Package Management adaptation, and multi-project composition.
本Skill通过
dotnet new
CLI命令从模板创建.NET项目，提供参数验证、中央包管理（CPM）适配以及多项目组合的指导。

When to Use

适用场景

  • User asks to create a new .NET project, app, or service
  • User needs a solution with multiple projects (API + tests + library)
  • User wants to create a project that respects existing 
    Directory.Packages.props
  • User needs to install or manage template packages
  • 用户请求创建新的.NET项目、应用或服务
  • 用户需要包含多个项目的解决方案（API + 测试 + 类库）
  • 用户希望创建遵循现有
    Directory.Packages.props
    的项目
  • 用户需要安装或管理模板包

When Not to Use

不适用场景

  • User is searching for or comparing templates — route to 
    template-discovery
    skill
  • User wants to author a custom template — route to 
    template-authoring
    skill
  • User wants to add packages to an existing project — use 
    dotnet add package
    directly
  • 用户正在搜索或对比模板 — 转至
    template-discovery
    Skill
  • 用户想要创作自定义模板 — 转至
    template-authoring
    Skill
  • 用户想要向现有项目添加包 — 直接使用
    dotnet add package

Inputs

输入参数

InputRequiredDescription
Template name or intentYesTemplate short name (e.g., 
webapi
) or natural-language description
Project nameYesName for the created project
Output pathRecommendedDirectory where the project should be created
ParametersNoTemplate-specific parameters (e.g., 
--framework
, 
--auth
, 
--aot
)
输入项是否必填描述
模板名称或意图是模板简称（例如：
webapi
）或自然语言描述
项目名称是待创建项目的名称
输出路径推荐项目创建的目标目录
参数否模板特定参数（例如：
--framework
, 
--auth
, 
--aot
）

Workflow

工作流程

Step 1: Resolve template and parameters

步骤1：解析模板和参数

If the user provides a natural-language description, map it to a template short name (see the keyword table in the 
template-discovery
skill). If they provide a template name, proceed directly.
Use 
dotnet new <template> --help
to review available parameters, defaults, and types for any parameters the user did not specify.
如果用户提供自然语言描述，将其映射为模板简称（参考
template-discovery
Skill中的关键字表）。如果用户已提供模板名称，则直接进入下一步。
使用
dotnet new <template> --help
查看用户未指定的参数的可用选项、默认值和类型。

Step 2: Analyze the workspace

步骤2：分析工作区

Check the existing solution structure before creating:
  • Is Central Package Management (CPM) enabled? Look for 
    Directory.Packages.props
  • What target frameworks are in use? Check existing 
    .csproj
    files
  • Is there a 
    global.json
    pinning the SDK?
This ensures the new project is consistent with the workspace.
创建前检查现有解决方案结构：
  • 是否启用了中央包管理（CPM）？查找
    Directory.Packages.props
    文件
  • 当前使用的目标框架是什么？检查现有
    .csproj
    文件
  • 是否存在
    global.json
    固定了SDK版本？
这确保新项目与工作区保持一致。

Step 3: Preview the creation

步骤3：预览创建过程

Use 
dotnet new <template> --dry-run
to show the user what files would be created. Confirm before proceeding.
bash
dotnet new webapi --name MyApi --framework net10.0 --dry-run
使用
dotnet new <template> --dry-run
向用户展示将创建的文件，确认后再继续。
bash
dotnet new webapi --name MyApi --framework net10.0 --dry-run

Step 4: Create the project

步骤4：创建项目

Use 
dotnet new
with the template name and all parameters:
bash
dotnet new webapi --name MyApi --output ./src/MyApi --framework net10.0 --auth Individual
使用
dotnet new
命令搭配模板名称和所有参数：
bash
dotnet new webapi --name MyApi --output ./src/MyApi --framework net10.0 --auth Individual

Common parameter combinations

常见参数组合

TemplateParametersExample
webapi
--auth
(None, Individual, SingleOrg, Windows), 
--aot
(native AOT)
dotnet new webapi -n MyApi --auth Individual --aot
webapi
--use-controllers
(use controllers vs minimal APIs)
dotnet new webapi -n MyApi --use-controllers
blazor
--interactivity
(None, Server, WebAssembly, Auto), 
--auth
dotnet new blazor -n MyApp --interactivity Server
grpc
--aot
(native AOT)
dotnet new grpc -n MyService --aot
worker
--aot
(native AOT)
dotnet new worker -n MyWorker --aot
Note: Use 
dotnet new <template> --help
to see all available parameters for any template.
After creation, if the workspace uses CPM:
  1. Check 
    .csproj
    for inline 
    <PackageReference>
    versions
  2. Move version attributes to 
    Directory.Packages.props
    as 
    <PackageVersion>
    entries
  3. Remove 
    Version
    attributes from the 
    .csproj
模板参数示例
webapi
--auth
（None, Individual, SingleOrg, Windows）、
--aot
（原生AOT）
dotnet new webapi -n MyApi --auth Individual --aot
webapi
--use-controllers
（使用控制器vs最小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. 检查
    .csproj
    文件中的内联
    <PackageReference>
    版本
  2. 将版本属性移至
    Directory.Packages.props
    中作为
    <PackageVersion>
    条目
  3. 从
    .csproj
    中移除
    Version
    属性

Step 5: Multi-project composition (optional)

步骤5：多项目组合（可选）

For complex structures, create each project sequentially and wire them together:
bash
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
对于复杂结构，依次创建每个项目并将它们关联起来：
bash
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

Step 6: Template package management

步骤6：模板包管理

Install or uninstall template packages:
bash
dotnet new install Microsoft.DotNet.Web.ProjectTemplates.10.0
dotnet new uninstall Microsoft.DotNet.Web.ProjectTemplates.10.0
安装或卸载模板包：
bash
dotnet new install Microsoft.DotNet.Web.ProjectTemplates.10.0
dotnet new uninstall Microsoft.DotNet.Web.ProjectTemplates.10.0

Step 7: Post-creation verification

步骤7：创建后验证

  1. Verify the project builds: 
    dotnet build
  2. If added to a solution, verify 
    dotnet build
    at the solution level
  3. If CPM was adapted, verify 
    Directory.Packages.props
    has the new entries
  1. 验证项目是否构建成功：
    dotnet build
  2. 如果已添加到解决方案，验证在解决方案级别执行
    dotnet build
    是否成功
  3. 如果适配了CPM，验证
    Directory.Packages.props
    是否包含新条目

Validation

验证清单

  • Project was created successfully with the expected files
  • Project builds cleanly with 
    dotnet build
  • If CPM is active, 
    .csproj
    has no version attributes and 
    Directory.Packages.props
    has matching entries
  • Package versions in the project are current (not stale template defaults)
  • If multi-project, all projects build and reference each other correctly
  • 项目已成功创建，包含预期文件
  • 项目通过
    dotnet build
    可干净构建
  • 如果CPM处于激活状态，
    .csproj
    无版本属性且
    Directory.Packages.props
    有匹配条目
  • 项目中的包版本为当前最新版本（而非过时的模板默认值）
  • 如果是多项目结构，所有项目均可构建且引用关系正确

Common Pitfalls

常见陷阱

PitfallSolution
Not checking for CPM before creating a projectIf 
Directory.Packages.props
exists, 
dotnet new
creates projects with inline versions that conflict. After creation, move versions to 
Directory.Packages.props
and remove them from 
.csproj
.
Creating projects without specifying the frameworkAlways specify 
--framework
when the template supports multiple TFMs to avoid defaulting to an older version.
Not adding the project to the solutionAfter creation, run 
dotnet sln add
to include the project in the solution.
Not verifying the project buildsAlways run 
dotnet build
after creation to catch missing dependencies or parameter issues early.
陷阱解决方案
创建项目前未检查CPM如果存在
Directory.Packages.props
，
dotnet new
创建的项目会带有内联版本，导致冲突。创建完成后，将版本移至
Directory.Packages.props
并从
.csproj
中移除。
创建项目时未指定框架当模板支持多个目标框架（TFM）时，务必指定
--framework
，避免默认使用旧版本。
未将项目添加到解决方案创建完成后，运行
dotnet sln add
将项目纳入解决方案。
未验证项目是否可构建创建后务必运行
dotnet build
，尽早发现缺失的依赖项或参数问题。

More Info

更多信息