dotnet/skills写标准ASP.NET Core API：dotnet-aspnetcore插件使用指南

dotnet/skills写标准ASP.NET Core API：dotnet-aspnetcore插件使用指南

【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills

想让 AI 编程助手写出标准的 ASP.NET Core API，而不是东拼西凑的代码片段？skills仓库中的dotnet-aspnetcore 插件正是为此而生——它是 .NET 团队官方维护的 AI 技能包，内置 Web API 规范、OpenAPI 文档、文件上传、可观测性等实战技能，让 Copilot、Claude Code 等编程助手按工业级标准为你生成 API 代码。

📦 插件一览：4 个技能各管一摊

dotnet-aspnetcore 插件（plugins/dotnet-aspnetcore/plugin.json）专注于 ASP.NET Core 的 Web 开发场景，包含 4 个技能（Skill）：

每个技能都有明确的"何时使用 / 何时不用"边界。例如dotnet-webapi会主动声明：EF Core 查询优化请交给optimizing-ef-core-queries技能，Blazor 前端改动不在其职责范围内——避免 AI "越界瞎写"。

🚀 快速上手：三步安装 dotnet-aspnetcore 插件

第 1 步：添加插件市场

在 Copilot CLI 或 Claude Code 中执行：

/plugin marketplace add dotnet/skills

第 2 步：安装插件

/plugin install dotnet-aspnetcore@dotnet-agent-skills

第 3 步：重启并查看技能

重启后输入/skills即可看到已加载的 ASP.NET Core 技能。

💡VS Code 用户：在设置中开启"chat.plugins.enabled": true并添加市场源即可浏览安装；完整安装说明见 README.md。

安装完成后无需额外配置——只要你提出"帮我建一个产品管理的 API"这类需求，助手就会自动调用对应技能。

⭐ 核心技能精讲：dotnet-webapi 如何写出标准 API

这是插件中含金量最高的技能。它把"写标准 ASP.NET Core API"拆成了8 步标准工作流，AI 会逐步执行并自我校验：

1️⃣ 先判断 API 风格，再动笔

扫描你的项目：已有 Controller 就继续用 Controller，已有 Minimal API 就继续用 Minimal API，新项目默认 Minimal API，且绝不在同一项目里混用两种风格。

2️⃣ 用 sealed record 定义请求/响应 DTO

• 一律使用不可变的sealed record，禁止用可变类，也绝不把数据库实体直接暴露给 API；
• 命名有严格约定：CreateProductRequest、ProductResponse、ProductListResponse；
• 每个 DTO 都要写<summary>XML 注释——它们会自动流入生成的 OpenAPI 文档；
• 日期时间字段统一用DateTimeOffset而非DateTime，序列化时自带时区偏移，避免客户端踩时区坑。

3️⃣ 端点实现遵循 HTTP 语义

技能内置了一张状态码对照表：POST创建成功必须返回201 Created + Location 头，DELETE成功返回204 No Content，每个端点签名都要接收CancellationToken并透传到所有异步调用。Minimal API 优先使用TypedResults，让 OpenAPI 生成器拿到更丰富的类型元数据。

4️⃣ 接入内置 OpenAPI（不装 Swashbuckle）

针对 .NET 9+ 项目，技能明确要求使用框架内置的AddOpenApi()+MapOpenApi()，禁止给新项目引入Swashbuckle.*系列包（已知兼容性问题）。每个端点还要链上.WithName()、.WithSummary()、.WithDescription()、.Produces<T>()，生成真正"能看懂"的接口文档。

5️⃣ 全局错误处理 + 6️⃣ 服务层 + 7️⃣.http文件

• 使用 RFC 7807Problem Details统一错误响应，异常处理器统一放在Middleware/目录；
• 端点不直接碰数据存储，而是通过接口 + 服务类解耦，方便单元测试；
• 自动为你生成.http请求测试文件，覆盖每个新端点，兼当"活文档"和手动测试脚本。

8️⃣ 构建验证收尾

最后一步是运行构建确认零错误零警告，启动应用验证/openapi/v1.json可访问，再逐条跑.http文件确认状态码正确。

🚫 内置"常见坑"清单，AI 替你避雷

技能文件里维护了一张高频踩坑表（见 SKILL.md 的 Common Pitfalls 部分），典型如：

🔍 其他三个技能：覆盖 API 开发的"周边"

文件上传（minimal-api-file-upload）：这是新手最容易翻车的场景。技能内置了大量"CRITICAL"级别提醒——请求体大小有Kestrel 与 FormOptions 两层限制，只调一层上传照样失败；.NET 8+ 的防伪造验证会自动校验表单上传，纯 API 上传端点必须显式.DisableAntiforgery()；文件名绝不能信任（防路径穿越），还要校验文件"魔数"而非只看扩展名；超大文件则用MultipartReader流式落盘。

可观测性（configuring-opentelemetry-dotnet）：精确告诉你该装哪几个 OpenTelemetry 包（例如只装OpenTelemetry主包是不够的，需要OpenTelemetry.Extensions.Hosting），并给出 Program.cs 的完整接线模板，支持 OTLP 导出、健康检查端点过滤等。

Blazor 迁移（convert-blazor-server-to-webapp）：把AddServerSideBlazor/_Host.cshtml老式架构迁移到 .NET 8+ 的AddRazorComponents/App.razor模型，且每完成一个逻辑步骤就建议提交一次，保证迁移过程可审查、可回滚。

📊 质量有据可查：技能不是"玄学提示词"

你可能好奇：这些技能真能让 AI 写得更好吗？仓库自带一套技能评估体系——每个技能都有对应的评测用例（如 tests/dotnet-aspnetcore/dotnet-webapi/eval.yaml），用"带技能 vs 不带技能"的成对对比来量化效果，判断标准是均值偏好提升且在 95% 置信区间内为正才算"可信改进"。下图就是评估结果在代码评审中的展示形态：

以dotnet-webapi的评测为例，评分规则非常具体：是否用了 Minimal API、POST 是否返回 201 + Location、DTO 是否为 sealed record、时间是否用DateTimeOffset、是否接入内置 OpenAPI 且未引入 Swashbuckle……这些正是上文标准工作流里要求的每一条。

🧭 新手上手建议

1. 一句话起步：装好插件后，直接告诉助手"帮我创建一个产品管理的 ASP.NET Core API（.NET 10），包含增删查端点和 OpenAPI 文档"，技能会自动激活；
2. 看它的自检清单：dotnet-webapi技能自带 19 项验证清单，AI 完成后可主动要求它"按 Validation 清单自查一遍"；
3. 按需组合：需要上传接口就补充"加一个图片上传端点"触发文件上传技能；上线前可再提"接入 OpenTelemetry 追踪"，一次补齐可观测性；
4. 深入了解：更多插件与标准说明见 README.md，AI 代理工作流背景知识可参考 docs/agentic-workflows.md。

✅ 小结

dotnet-aspnetcore 插件把 .NET 团队对"标准 ASP.NET Core API"的定义——HTTP 语义、不可变 DTO、内置 OpenAPI、统一错误处理、文件上传安全、可观测性——打包成了 AI 可直接执行的技能。对新手来说，它相当于随叫随到的资深 .NET 架构师；对团队来说，它让不同人、不同模型写出的 API 代码风格和质量保持一致。三步安装，开箱即用，建议所有 .NET Web 开发者都装上试试。

【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills