template-discovery

模板发现

此技能可帮助 Agent 使用 dotnet new CLI 命令进行搜索、列出模板并检查参数，从而为给定任务找到、检查并选择合适的 dotnet new 模板。

适用场景

• 用户询问“有哪些适用于 X 的模板？”
• 用户用自然语言描述项目（“我需要一个带身份验证的 Web API”）
• 用户想比较模板，或在创建项目之前了解参数
• 用户需要在决定采用之前了解模板会生成什么（文件、结构）

不适用场景

• 用户想创建项目——转到 template-instantiation 技能
• 用户想编写或验证自定义模板——转到 template-authoring 技能
• 用户想详细并排比较模板——转到 template-comparison 技能
• 用户想在创建期间智能设置跨参数默认值——转到 template-smart-defaults 技能
• 用户正在排查生成问题——转到 dotnet-msbuild 插件

收到推荐请求时，先回答，再确认。收到检查请求时，先检查。 对于一般的“该用哪个模板？”问题，请从步骤 1 中的映射开始，以免 CLI 临时故障导致用户得不到答案。如果用户明确询问已安装的模板、要求提供准确选项或默认值，或要求提供试运行输出，请在撰写最终答案前运行相关的 dotnet new 命令。不要以调用 dotnet new 或“我来确认一下……”作为本轮回复的结尾。

检查请求必须实际检查。 如果用户询问已安装的选项、准确的参数或默认值、兼容性限制，或准确的试运行文件列表，请运行相应的 dotnet new 命令。不要用记忆中的标志替代实际观察到的数据。只有当当前模板的 --help 输出中包含某个标志时，才报告该标志。

输入

输入	必需	说明
用户意图或关键词	是	自然语言描述或关键词（例如，“Web API”“控制台应用”“MAUI”）
语言偏好	否	C#、F# 或 VB——默认为 C#
框架偏好	否	目标框架（例如，net10.0、net9.0）

工作流

对于推荐请求，请先执行步骤 1，再执行步骤 2–4。对于明确的检查请求，请先执行所请求的检查，并仅在必要时将步骤 1 用作后备方案。

步骤 1：将意图映射到模板候选项

使用以下映射，将用户的自然语言描述对应到模板简称和参数。

意图 → 模板简称：

意图 / 表述	模板简称
web api、web service、rest api、restful、api、minimal api	webapi
web app、web application	webapp、blazorserver
mvc	mvc
razor、razor pages	webapp
blazor、blazor web app	blazor
blazor server	blazorserver
blazor wasm、blazor webassembly	blazorwasm
grpc	grpc
signalr	webapi、webapp
console、console app、command line、cli	console
worker、background service、daemon、windows service	worker
class library、library、lib、nuget package	classlib
maui、mobile、cross-platform app、ios、android	maui
desktop	maui、wpf、winforms
wpf	wpf
winforms、windows forms	winforms
winui、winui3	winui3
test、unit test	xunit、nunit、mstest
xunit / nunit / mstest	xunit / nunit / mstest
solution	sln
aspire、.net aspire	aspire-starter、aspire
azure functions、function app、serverless	func
orleans	orleans
razor component、web component	razorcomponent
razor class library	razorclasslib
gitignore / editorconfig / nuget config / global json	gitignore / editorconfig / nugetconfig / globaljson

关键词 → 参数：

关键词 / 表述	参数	值
authentication、auth、individual auth、individual accounts	--auth	Individual
windows auth	--auth	Windows
azure ad、entra id	--auth	SingleOrg
no auth、no authentication	--auth	None
controllers、with controllers	--use-controllers	（标志）
minimal api	（默认）	—
aot、native aot	--aot	（标志）
docker、container	模板的 Docker/容器选项	因模板而异 — 使用 --help 确认（并非所有模板都提供此选项）
net8 / .net 8 / dotnet 8	--framework	net8.0
net9 / .net 9 / dotnet 9	--framework	net9.0
net10 / .net 10 / dotnet 10	--framework	net10.0

以上仅为初步判断。务必使用 dotnet new <template> --help 确认实际参数名称和可选值，因为不同模板的参数名称可能不同（例如，--auth 与 --Authentication）。

某些映射到的简称在默认 SDK 安装中并不存在 — maui、winui3、aspire-starter/aspire、func 和 orleans 等模板通常需要工作负载（dotnet workload install <id>）和／或额外的模板包（dotnet new install <package>）。如果映射到的简称未出现在 dotnet new list 中，请使用 dotnet new list/dotnet new search 查找合适的模板，以及提供该模板的包／工作负载，然后再进行推荐。

容错 — 即使 CLI 调用失败也要始终作答。 上述意图映射本身即可作为可用答案。请按顺序逐个运行 dotnet new 命令 — 模板引擎使用全局互斥锁，因此并发执行多个 dotnet new <template> --help/--dry-run 调用可能会导致临时的“mutex”/“persistence”错误和空输出。如果命令失败，请重试一次；若仍然失败，则退回到此意图／参数映射并给出明确建议，同时说明无法通过 CLI 确认确切的参数名称／可选值。切勿因为 CLI 调用报错而在本轮中不给出答案。

步骤 2：搜索模板

使用 dotnet new search，通过关键字搜索本地已安装模板和 NuGet.org 上的模板：

dotnet new search blazor

使用 dotnet new list 仅显示已安装的模板，也可以添加筛选条件：

dotnet new list --language C# --type project
dotnet new list web

如果用户明确要求同时检查已安装的模板和 NuGet.org，请运行并报告这两项搜索，即使 SDK 已包含合适的模板也不例外。请区分内置选项和可安装的替代方案：

• 对于 SDK 随附的模板，请说明 “无需安装 — SDK 已随附”，不要凭空要求安装包。
• 对于你推荐的每个相关 NuGet 搜索结果，请从实际搜索输出中复制包 ID，并给出 dotnet new install <package-id>。
• 如果 NuGet 搜索没有返回可信的替代方案，请明确说明；本地匹配结果仍可满足用户的请求。

步骤 3：检查模板详情

使用 dotnet new <template> --help 获取特定模板的完整参数详情，包括参数名称、类型、默认值和允许的值：

dotnet new webapi --help

在回答中复制观察到的选项名称、选项值、默认值和兼容性说明。 例如，Windows Service 支持并非所有 worker 模板都通过标志提供。如果已安装的 worker --help 未列出相关选项，请如实说明，并区分模板创建与创建后的托管配置；切勿凭空编造 --windows 或 --use-windows-service。

步骤 4：预览输出

使用 dotnet new <template> --dry-run 查看模板会创建哪些文件和目录，而不将任何内容写入磁盘：

dotnet new webapi --name MyApi --auth Individual --dry-run

如果 dry-run 失败（出现暂时性的“mutex”/“persistence”错误），请重试一次；如果仍然失败，请提供一个代表性结构（模板类别和典型文件类型），并注明该结构未经 CLI 确认。不要编造具体值、选项或文件路径。dry-run 成功时，请保留输出中的所有实际路径。如果列表很长，请将这些路径整理成目录树，而不是罗列一长串完整路径；不得遗漏或编造条目。在目录树后，用一行说明每个关键入口文件的用途（例如 Program.cs、App.razor 和项目文件）。只提供文件列表而不说明用途，内容并不完整。

如果无法执行命令，不要只让用户“自行运行”。请根据已知模板类别提供代表性目录树和关键文件说明，并明确标注未经确认，让用户仍能获得有用的预览。

如果用户要求不要创建文件，每条可复制粘贴的创建命令都必须包含 --dry-run。即使你自己没有执行命令，普通的 dotnet new ... 命令也与该要求相矛盾。

步骤 5：呈现结果

先给出可直接运行的命令，再说明理由。格式如下：

使用 <template> — 用一行说明理由。

dotnet new <template> --name <Name> [--key params]

然后补充以下信息：

• 关键参数和推荐值（包括可选值，例如 --auth：None | Individual | SingleOrg | Windows）
• 预期结果（创建的文件、项目结构）
• 所需前置条件——写出确切的安装包（dotnet new install <id>），或者对于内置模板说明 “无需安装 — SDK 已随附”

如果回答没有提供具体且可复制粘贴的命令，就和普通回复没什么区别——务必给出下一步要运行的命令。

验证

• 至少找到一个符合用户意图的模板
• 说明模板参数的类型和默认值
• 用户在继续创建前了解模板会生成什么
• 关于具体选项的说法均来自该模板实际观察到的 --help 输出
• 不得创建文件的建议性命令均包含 --dry-run

常见陷阱

陷阱	解决方案
本地存在模板时，跳过明确要求的 NuGet 搜索	运行 dotnet new list <keyword> 和 dotnet new search <keyword>，然后区分内置模板与真正可安装的替代方案。
没有本地匹配的模板时，未搜索 NuGet	使用 dotnet new search <keyword>，查找 NuGet.org 上可安装的模板。
未检查模板的约束条件	有些模板需要特定的 SDK 或工作负载。建议前，使用 dotnet new <template> --help 明确约束条件。
未预览输出就推荐模板	始终使用 dotnet new <template> --dry-run，确认模板生成的内容符合用户预期。
dotnet new 调用因 “mutex”/“persistence” 错误失败后未提供任何内容	这类错误是暂时性的（通常由并发调用引起）。按顺序运行 dotnet new 调用，重试一次，然后回退到步骤 1 的意图映射，仍要给用户一个明确的答复。
根据其他 SDK/模板猜测 Windows Service 或 AOT 标志	只引用在 dotnet new <template> --help 中看到的选项；否则说明创建后的操作方法。

更多信息

• dotnet new 模板 — 内置模板参考
• 模板引擎 Wiki — 模板引擎内部机制