template-instantiation

模板实例化

此技能使用 dotnet new CLI 命令从模板创建 .NET 项目，并提供参数验证、适配 Central Package Management 以及组合多个项目的指导。

与工作区保持一致，然后停止。 最有价值的做法是让新项目与其所在的仓库保持一致：检测是否使用 CPM（Directory.Packages.props），并查看相邻 .csproj 文件所用的目标框架，然后两者都照此配置。将发现的目标框架视为明确选择——通过 --framework 传入，避免 template-smart-defaults 覆盖它；只有在该框架与所需功能不兼容时才偏离（此时请指出冲突）。尽可能用最少步骤完成：通常只需 --dry-run、创建项目，然后运行一次 dotnet build 确认即可。额外的探索步骤会增加成本，却不会改善结果。

执行用户要求的创建操作。 不要只返回计划或意向说明。 按顺序运行依赖当前状态的命令：检查、试运行、创建，然后构建。绝不要并行启动创建和构建；先构建后创建会导致错误的失败结果。

情况	必需操作
简单的独立项目	仅检查用户要求的模板，在指定的确切路径创建，然后构建
存在相邻项目	先读取它们的 TFM，然后显式传入匹配且受支持的 --framework
找到 Directory.Packages.props	在支持时使用 --no-restore 创建，规范化生成的包引用，然后只还原并构建一次
多项目解决方案	在各项目的最终路径创建项目，添加引用，将所有项目添加到解决方案，然后只构建一次解决方案
用户明确要求 .sln	检查 dotnet new sln --help；在支持时传入 --format sln，否则使用旧版 SDK 默认生成的 .sln

不要推测生成的目标框架。如果用户和工作区都未指定目标框架，请检查 dotnet new <template> --help，选择一个受支持的值（通常为文档中注明的默认值），显式传入，然后确认生成的 .csproj。切勿宣布一个没有依据、也不属于模板当前选项的中间框架猜测。

适用场景

• 用户要求创建新的 .NET 项目、应用或服务
• 用户需要包含多个项目的解决方案（API + 测试 + 库）
• 用户想创建遵循现有 Directory.Packages.props 的项目
• 用户需要安装或管理模板包

不适用场景

• 用户正在搜索模板——转到 template-discovery 技能；如需详细的并列比较，则转到 template-comparison 技能
• 用户想编写自定义模板——转到 template-authoring 技能
• 用户想向现有项目添加包——直接使用 dotnet add package

输入

输入	必填	说明
模板名称或意图	是	模板短名称（例如 webapi）或自然语言描述
项目名称	是	要创建的项目名称
输出路径	建议提供	创建项目的目录
参数	否	模板专用参数（例如 --framework、--auth、--aot）

工作流

第 1 步：确定模板和参数

如果用户提供的是自然语言描述，请将其映射到模板短名称（参见 template-discovery 技能中的关键词表）。如果用户提供了模板名称，则直接继续。

使用 dotnet new <template> --help 查看用户未指定参数的可用选项、默认值和类型。

如果用户选择的参数会影响某个未设置的相关参数，请调用 template-smart-defaults 技能，在组装命令行之前补全缺失项。例如，原生 AOT 意味着应使用近期支持 AOT 的目标框架；选择非 None 的 --auth 值意味着必须保持启用 HTTPS（不要添加 --no-https）；而 --use-controllers 与最小 API 选项互斥。智能默认值只能补全缺失项，绝不能覆盖用户明确设置的值。第 2 步中发现的工作区框架也视为明确设置的值——将其作为所选的 --framework 传递给智能默认值，以免它被当作未设置项；只有在它与请求的功能或模板不兼容时才可偏离（此时请向用户说明冲突）。

第 2 步：分析工作区

创建项目前，检查现有解决方案结构：

• 是否启用了 Central Package Management (CPM)？查找 Directory.Packages.props
• 正在使用哪些目标框架？检查现有的 .csproj 文件
• 是否有 global.json 固定 SDK 版本？

这样可以确保新项目与工作区保持一致。

第 3 步：预览创建内容

使用 dotnet new <template> --dry-run 向用户展示将创建哪些文件。继续前请先确认。

dotnet new webapi --name MyApi --framework net10.0 --dry-run

第 4 步：创建项目

使用 dotnet new，并指定模板名称和所有参数：

dotnet new webapi --name MyApi --output ./src/MyApi --framework net10.0 --auth Individual

运行命令前，输出一行简洁的决策信息：

Creating <template> at <path>; framework=<value> (<user|workspace|template>); CPM=<on|off>.

这样可以明确说明对工作区所做的适配，而无需提供冗长报告。

常见参数组合

模板	参数	示例
webapi	--auth（None、Individual、SingleOrg、Windows）、--aot（原生 AOT）	dotnet new webapi -n MyApi --auth Individual --aot
webapi	--use-controllers（使用控制器而非最简 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 查看任何模板的所有可用参数。

创建后，请调整项目以适配 Central Package Management，并更新过时的版本：

1. 创建前检测 CPM — 从目标位置向上查找 Directory.Packages.props。
2. 避免注定失败的自动还原 — 如果已启用 CPM，且模板支持 --no-restore，请在创建时传入该参数，以便先集中管理包。
3. 移除内联版本 — 对每个生成的 <PackageReference Include="X" Version="Y" />，移除 Version 属性（保留 <PackageReference Include="X" />）。
4. 集中管理版本 — 在 Directory.Packages.props 中添加或合并 <PackageVersion Include="X" Version="Y" /> 条目；保留无关的现有条目。
5. 可选：更新过时的模板默认版本 — 模板通常会硬编码旧版本。默认保留模板中的版本（这是确保可重现性和受控升级的最稳妥做法）。仅在用户提出要求时才更新；更新时：
   • 优先采用由工具驱动的流程：运行 dotnet list package --outdated，并在更改前与用户确认建议的版本升级。
   • 除非用户明确同意更大幅度的升级，否则将升级限制在相同的主版本（或主/次版本）内，因为跨主版本升级可能会引入破坏性更改。
   • 在概念上检查某个包的最新稳定版时，该包 ID 对应的 NuGet V3 扁平容器 index.json 端点会列出已发布的版本；除非用户要求，否则绝不选择预发布版本。
6. 构建 — 运行一次 dotnet build，以还原并确认集中管理的版本能够正常解析。

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

对于复杂结构，请依次创建每个项目并将它们连接起来：

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

步骤 6：模板包管理

安装或卸载模板包：

dotnet new install Microsoft.DotNet.Web.ProjectTemplates.10.0
dotnet new uninstall Microsoft.DotNet.Web.ProjectTemplates.10.0

步骤 7：创建后验证

1. 验证项目是否可以构建：dotnet build
2. 对于 console 等可运行模板，如果请求简单且不需要外部服务，请运行生成的应用；报告实际观察到的输出，而不只是构建成功。
3. 如果已添加到解决方案，请在解决方案级别验证 dotnet build
4. 如果已调整以适配 CPM，请验证 Directory.Packages.props 中是否包含新增条目

验证

• 已成功创建项目，且包含预期文件
• 项目通过 dotnet build 成功构建，且无错误
• 如果已启用 CPM，.csproj 中没有版本属性，且 Directory.Packages.props 中包含对应条目
• 项目中的包版本均为最新版本（不是过时的模板默认版本）
• 如果是多项目结构，所有项目均可构建，且彼此引用正确

常见陷阱

陷阱	解决方案
创建项目前未检查是否启用 CPM	如果存在 Directory.Packages.props，dotnet new 创建的项目会包含内联版本，这些版本会产生冲突。创建后，将版本移至 Directory.Packages.props，并从 .csproj 中移除。
适配 CPM 前就让模板还原失败	先检测 CPM；如果模板支持 --no-restore 选项，则使用该选项；在首次还原/生成前集中管理版本。
创建项目时未指定框架	如果模板支持多个 TFM，请始终指定 --framework，以避免默认使用较旧版本。
未将项目添加到解决方案	创建后，运行 dotnet sln add 将项目添加到解决方案中。
未验证项目能否生成	创建后始终运行 dotnet build，以便尽早发现缺失的依赖项或参数问题。

更多信息

• 中央包管理 — CPM 文档
• dotnet new — CLI 参考