neo-dotnet-tag-helper

.NET Tag Helper 专家技能

触发条件

• 用户请求使用 C# 创建、生成或设计自定义 Razor Tag Helper。
• 用户希望将复杂的 HTML/UI 逻辑封装为可复用的自定义标签，而不使用 Partial Views 或 CSHTML。
• 目标框架为 .NET 6.0（LTS）及更高版本。

工作流（生成器模式）

严格按照以下步骤创建健壮、高性能的 C# Tag Helper。

步骤 1：理解并收集需求（反向提问）

编写任何代码之前，如果用户尚未提供以下信息，请先询问并澄清：

1. 目标 HTML 标签：自定义标签在 HTML 中的名称是什么？（例如，<my-button>、<user-card>）
2. 属性：此标签应接受哪些参数/属性？（例如，theme、is-active、user-id）
3. 依赖项（DI）：此标签是否需要查询数据库或调用服务？（需要依赖注入）
4. 上下文：是否需要访问 ViewContext（例如，生成 URL 或检查模型状态）？

步骤 2：推理并设计（规划）

根据用户的回答：

• 类命名：确保类名以 TagHelper 结尾（例如，MyButtonTagHelper）。
• 目标元素：应用 [HtmlTargetElement("my-button")]。
• 属性：将 HTML kebab-case 属性映射到 C# PascalCase 属性。必要时应用 [HtmlAttributeName("is-active")]。
• 方法选择：
  • 如果没有 IO/异步操作，则重写 Process。
  • 如果使用 DI 调用数据库/API，则重写 ProcessAsync。

步骤 3：执行（生成代码）

生成完整的 C# 类。严格遵守以下规则：

1. 继承自 Microsoft.AspNetCore.Razor.TagHelpers.TagHelper。
2. 不要生成 .cshtml 文件。所有 HTML 都必须在 C# 类中使用 TagBuilder 构建。
3. 如果需要 ViewContext，请使用 [ViewContext] 和 [HtmlAttributeNotBound]。
4. 使用 output.TagName、output.Attributes.SetAttribute 和 output.Content.SetHtmlContent 正确管理内容。
5. 确保线程安全（除非实例字段注入的是 scoped/transient 服务，否则不要在实例字段中存储请求专属状态）。

步骤 4：验证（质量检查）

在提交代码之前，根据以下标准检查生成的代码：

• 所有属性是否都具有强类型？
• 是否使用了 TagBuilder 而不是字符串拼接来构建 HTML 元素？
• 如果要等待任务，是否正确使用了 ProcessAsync？

交付内容

将 C# 代码放在 Markdown 代码块中。简要说明如何在 _ViewImports.cshtml 中注册（例如，@addTagHelper *, YourAssemblyName）。

文档

官方参考资料

• ASP.NET Core 中的 Tag Helpers
• 编写 Tag Helpers

内部参考资料

• Tag Helper 编码风格与高级模式
• Tag Helper 编码约定
• Tag Helper 反模式