dotnet-template-engine 实战：用 Template Comparison 技能对 dotnet new 模板做并排对比与选型决策

dotnet-template-engine 实战用 Template Comparison 技能对 dotnet new 模板做并排对比与选型决策【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skillsdotnet new提供了数十种项目模板而webapi与webapp、blazor与blazorwasm、worker与console这类看起来很像的模板常常让开发者难以抉择。本仓库dotnet-template-engine插件中的template-comparison技能定义于 SKILL.md专门解决这个问题它引导 AI Agent 逐个检查待选模板的真实参数与特性支持产出并排对比表并以一条决定性推荐收尾。读完本文你将掌握这套证据契约 决策契约的对比方法论、常用模板对的选型捷径以及如何将其与模板发现、项目创建等其他技能衔接成完整工作流。技能定位何时用、何时不用template-comparison是 dotnet-template-engine 插件六个模板技能中的一环其余为template-discovery、template-instantiation、template-smart-defaults、template-authoring、template-validation。插件在 plugin.json 中声明其能力为发现与搜索模板、检查模板参数与目标框架net8.0/net9.0/net10.0、脚手架解决方案、创作与验证自定义模板、从 NuGet 安装模板包而对比选型正是其中承上启下的一环。When to Use何时使用用户正在几个相似模板之间做决定例如webapivswebapp、blazorvsblazorwasm、consolevsworker用户问我应该用哪个模板做 X用户在创建项目之前想先理解两个或多个模板之间的差异。When Not to Use何时不用用户想创建项目——应路由到template-instantiation技能用户想创作或验证自定义模板——应路由到template-authoring或template-validation技能用户只需要查找或检查单个模板——应路由到template-discovery技能。在 template-engine.agent.md 的 Triage and Routing 表中这一路由关系被固化下来Compare templates X vs Y / which template should I use 直接映射到template-comparison技能避免 Agent 用创建流程去回答选型问题。输入定义输入是否必需说明模板短名称Template short names是两个或更多待对比的模板短名称如webapi、webapp对比焦点Comparison focus否可选的侧重维度如 auth、AOT、框架、交互性 interactivity对比焦点是可选参数但它决定了 Step 2 中对比表的决策维度——技能要求围绕用户声明的决策来组织表格而不是堆一个无差别的超大表格。工作流总览两份核心契约整个对比流程建立在一个三层结构中其中前两层是这份技能的灵魂证据契约Evidence contract并排对比表只有在每个选项声明都基于当前已安装模板时才有价值。因此每个--help调用必须逐个顺序执行为每个模板捕获相同的请求维度对不可用的选项要标注为Not exposed而不是猜测或从另一个模板借用标志。决策契约Decision contract对比要围绕用户的实际决策优化而不是追求表格体积。要覆盖每个请求维度、省略无关选项行、给出针对场景的理由并在推荐起点可执行时附带一条安全的--dry-run命令。第三层则是具体的三个执行步骤检查模板Inspect→ 构建对比表Build the comparison table→ 给出推荐Recommend。Step 1逐个检查每个模板对每个待对比模板运行dotnet new template --help收集其参数名称、类型、默认值、选项 choices以及支持的框架dotnet new webapi --help dotnet new webapp --help如果某个模板未安装先搜索其提供方provider并报告缺失的前提条件只有用户明确要求修改环境或同意安装时才执行安装——对比技能本身不改变环境。为什么必须顺序执行 --help--help调用必须顺序执行。模板引擎使用全局互斥锁global mutex并发运行多个dotnet new template --help命令会以瞬时的 mutex/persistence 错误和空输出失败。请一次只检查一个模板若调用失败重试一次再继续并仍然基于你已有的参数知识产出对比而不是以无答案结束。这一约束在仓库中反复出现template-discovery的 SKILL.md 与template-comparison的 SKILL.md 都明确写出同样的警告fire severaldotnet new template --help/--dry-runcalls concurrently can produce a transient mutex/persistence error。这是 .NET Template Engine 实际运行时的已知特性也是本技能要求一次只跑一条命令的底层原因。对于 Agent 而言这是影响执行编排的重要实操细节——并发调用不仅是风格问题而是会真实导致空输出的事故源。模板未安装时的处理未安装的模板分为两类情况SDK 自带模板如console、classlib等无需安装直接可用需要 workload 或模板包的模板如maui、winui3、aspire-starter、func、orleans通常需要dotnet workload install id和/或dotnet new install package。如果短名称没有出现在dotnet new list中应先用dotnet new list/dotnet new search定位正确的模板及其提供包再决定是否推荐。这一规则与template-discovery技能中的意图映射表相互印证该表覆盖了webapi/webapp/mvc/blazor/blazorwasm/grpc/worker/console/xunit/nunit/mstest等常用模板但明确指出maui、winui3、aspire、func、orleans等通常不在默认 SDK 安装中。Step 2构建并排对比表对比表需要覆盖四个维度参数Parameters——名称、类型、默认值、选项 choices特性支持Feature support——auth、AOT、Docker、controllers、interactivity可用框架Available frameworks——如 net8.0、net9.0、net10.0分类Classifications——模板宣传的类别Web、API、Blazor 等。技能明确要求每个请求的决策维度一行并在单元格中引用观察到的选项名当某行专门问模板生成什么、暴露什么时不得用泛泛的框架知识填充。标准对比表示例技能给出了如下示例形状AspectwebapiwebappAuth--authNone, Individual, SingleOrg, WindowsNone, Individual, SingleOrg, ...AOT--aot标志若dotnet new webapi --help列出--aot则为 present若dotnet new webapp --help列出--aot则为 presentControllers--use-controllersYesn/aInteractivityn/an/aFrameworksnet8.0 / net9.0 / net10.0net8.0 / net9.0 / net10.0ClassificationsWeb, WebAPIWeb, Razor Pages注意示例中的严谨写法AOT 一行的取值不是猜测而是若--help列出则为 present的条件判断Controllers 一行的n/a表示该模板不暴露此选项。这正是证据契约的体现——每个单元格都必须能回溯到某次--help输出。对比生成的依赖Generated Dependencies--help和--dry-run不会揭示包引用package references。当用户在不允许创建项目的前提下询问生成的依赖时技能要求检查已安装模板包内的源.csproj文件。同时明确禁止两件事——不得仅仅为了检查而创建临时项目也不得猜测当前的包 ID 或测试平台默认值。这一条在评测场景中格外重要tests 目录下的 eval.yaml 中Select a test project template for an enterprise suite 用例要求对比xunit、nunit、mstest三个模板的生成依赖、默认测试平台集成和框架选项且明确dont create projects。这正是依赖源.csproj检查路径的典型应用。Step 3给出决定性推荐对比必须以一条果断的Recommendation行收尾——绝不能让用户只拿到一张表。推荐格式为Recommendation:template— 用一句话把选择与用户陈述的场景绑定。若满足condition则选另一个。然后链接到template-instantiation技能去真正创建项目。技能强调一份没有点名赢家或没有明确取决于 X的对比是不完整的——正是这种犹豫不决会让该技能与一条普通回答毫无差别。给推荐配上可执行的下一步当推荐起点可执行时附上一条安全的--dry-run命令让推荐落地为行动dotnet new webapi --name MyApi --framework net10.0 --dry-run这与template-instantiation技能的 Step 3 一致该技能同样用--dry-run向用户展示将创建的文件确认后再真正创建。两者的衔接路径为template-comparison负责选哪个template-instantiation负责怎么建。常见模板对的决策捷径技能为四组高频对比对提供了仅用于推荐环节的默认选择注意捷径不能替代--help证据填写对比表前仍需逐个检查对比对默认选择理由webapivswebappJSON/REST 后端选webapi服务端渲染的 HTML/Razor Pages 选webappwebapi 自带 controllers/minimal APIs OpenAPI无 UIblazorvsblazorwasm需要离线/无服务器时选blazorwasm需要灵活的服务器 客户端交互时选blazorWeb App独立 WASM 完全客户端运行可离线工作workervsconsole长生命周期/队列/后台处理选workerGeneric Host 提供 DI、日志、配置、优雅停机、IHostedService生命周期mvcvswebapp页面型应用选webappRazor Pages规模化后需要 controller/view 分离选mvcRazor Pages 对 CRUD 型页面更轻量覆盖约束Overrides以下约束优先于上表捷径当用户明确预期大型应用或共享 controller 逻辑时选mvc——即使初期页面以 CRUD 为主当富交互表单是核心、但又要求首次响应就到达有用 HTML 时选带 Server 交互性的blazor而非webapp。需要解释首屏渲染由服务端完成交互组件使用 Blazor 表单/组件模型而非 Razor Pages 的PageModel需要离线支持时选blazorwasm并解释 PWA/service-worker 要求、首次加载后缓存的行为、以及执行不需要常驻在线服务器的事实需要持久化队列处理器时选worker并把决策绑定到 Generic Host 生命周期、依赖注入、配置、日志、优雅停机以及真实持久化队列而非内存循环上。这些捷径的评判逻辑与评测脚本的 rubric 高度一致eval.yaml 中 Choose between blazor and blazorwasm 用例要求解释 hosting/interactivity trade-offs (server-rendered vs WebAssembly) 并把离线需求连接到具体推荐Decide which template fits a background processing scenario 用例则要求用 hosted service lifecycle 解释 worker 模板为何适合长生命周期队列处理。验证清单技能自带的 Validation 清单也是评测 rubric 的直接来源每个请求的模板都通过dotnet new template --help检查过对比覆盖了参数、特性支持、框架和分类四个维度与用户场景相关的差异被显式点出给出了推荐或明确的权衡不支持或不存在的选项被标注而非猜测最终推荐是单条决定性的Recommendation:行对照 eval.yaml 中的 7 个评测用例可以清晰看到这条清单如何被机械地验证Compare webapi vs webapp side by side 用output-matches正则要求输出同时出现webapi、webapp、auth、aot、docker、controllers、recommend关键词且 rubric 明确要求并排对比表而非两张独立列表、覆盖参数、特性支持auth/AOT/Docker/controllers和框架Choose MVC or Razor Pages for an admin portal 用\|.*\|正则强制要求输出包含 Markdown 表格行从测试层面把必须产出表格固化为硬性标准每个用例都带有expect_tools: [skill]约束即评测时要求 Agent 实际调用 skill 工具而非凭记忆作答。常见陷阱陷阱解决方案凭记忆对比未安装的模板安装并逐个检查每个模板让对比反映真实参数与选项假设特性对等Assuming feature parity参数名和特性支持因模板而异——每个模板都用--help确认对比根本不同类型的模板只对比解决重叠问题的模板目标场景不同时要明确指出这三条陷阱从反面印证了证据契约的强制力。template-discovery技能中有一句同样的话值得记住Report a flag only when the current templates--helpoutput contains it只有当当前模板的--help输出中出现该标志时才报告它——worker模板的 Windows 服务支持、某个模板是否有--aot标志都必须以实际输出为准绝不能从其他 SDK 或模板借用标志。与仓库其他技能的协作闭环template-comparison并非孤立技能它与同插件的其他技能形成完整选型→创建闭环意图解析用户说我想要一个带认证的 Web API时template-discovery的意图映射表SKILL.md 中的 Intent → template short name 与 Keyword → parameter 两张表把它解析为webapi--auth Individual对比选型当候选不止一个如webapivswebapp、blazorvswebapp时template-comparison用本文的流程产出对比表与推荐智能默认值创建时若--aot与--framework等跨参数存在隐含关系template-smart-defaultsSKILL.md只填补未设置的参数、绝不覆盖用户显式值项目创建最终由template-instantiationSKILL.md执行创建并负责 CPMDirectory.Packages.props适配、--no-restore时序控制与dotnet build验证。在 template-engine.agent.md 的技能清单Skills Inventory中这六个技能被统一登记而 agent 的分诊表Triage and Routing正是依据用户意图在它们之间做第一层路由。对于本文的对比主题路由规则很简单任何 Compare templates X vs Y 或 which template should I use 的请求都会落到template-comparison。小结template-comparison的价值在于把模板选型从凭印象的问答升级为可验证的工程流程先以--help逐个取证证据契约再按用户的决策维度组织并排表格最后以一条Recommendation:行给出果断结论并衔接创建步骤。其核心实操要点可归纳为三条证据优先一切参数、特性、框架声明都必须来自当前安装模板的--help输出缺失的选项标Not exposed绝不猜测顺序执行模板引擎的全局互斥锁决定了dotnet new系列命令必须串行调用失败重试一次后仍要基于已有知识给出答案果断收尾对比表只是手段决定性的推荐或明确的权衡才是交付物并附上可执行的--dry-run命令与template-instantiation的下一步入口。当你下次在两个相似模板之间犹豫时不妨把这份方法论交给 Agent让每个单元格都源于一次真实的--help输出让最终选择绑定到你的具体场景——这样的选型既经得起评测脚本的 regex 校验也经得起实际项目的考验。【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考