前言¶
ASP.NET Core 同時存在 Blazor、Razor Pages、MVC、Minimal API、控制器 Web API 等多種應用模型，版本迭代也會帶來 WebApplicationBuilder 與舊版 Startup 等差異。在 Agent 裏改 Program.cs、加認證或做升級時，容易混用過時 API，或在不合適的場景裏換應用模型。下面介紹 OpenAI Curated 目錄下的 aspnet-core Skill：它用分主題的 reference 文檔約束工作流，讓助手按 Microsoft 當前文檔風格選棧、搭管道、實現功能。
這是什麼¶
aspnet-core 是 OpenAI 在 skills/.curated/aspnet-core 中維護的 Agent Skill。官方 description 寫明：用於構建、審查、重構或架構 ASP.NET Core Web 應用，並遵循當前 .NET Web 開發的官方指引。
適用任務包括 Blazor Web Apps、Razor Pages、MVC、Minimal API、基於控制器的 Web API、SignalR、gRPC、中間件、依賴注入、配置、認證與授權、測試、性能、部署，以及 ASP.NET Core 版本升級等。Skill 要求只加載與當前任務匹配的最小 reference 集合，而不是默認加載全部資料。
核心功能¶
工作流（Workflow）¶
官方在 SKILL.md 中固定了閱讀與執行順序：
- 確認目標框架、SDK 與當前應用模型。
- 新建應用或大規模重構時，先打開
references/stack-selection.md。 - 再打開
references/program-and-pipeline.md，處理Program.cs、DI、配置、中間件、路由、日誌與靜態資源。 - 按應用類型只打開一個主 reference：
-references/ui-blazor.md
-references/ui-razor-pages.md
-references/ui-mvc.md
-references/apis-minimal-and-controllers.md - 按需追加橫切主題 reference（數據與狀態、安全、實時/gRPC/後臺任務、測試與運維等）。
- 向舊方案引入新平臺 API 或跨大版本遷移前，先讀
references/versioning-and-upgrades.md。 - 任務未在 focused reference 中覆蓋時，用
references/source-map.md對照 Microsoft Learn 文檔樹。
默認假設（Default Operating Assumptions）¶
- 除非倉庫或用戶指定舊版本，優先使用最新穩定版 ASP.NET Core 與 .NET。
- 截至 2026 年 3 月，新項目生產環境優先 .NET 10 / ASP.NET Core 10；ASP.NET Core 11 視爲預覽，除非用戶明確要求預覽特性。
- 優先
WebApplicationBuilder與WebApplication；除非代碼庫已使用或任務爲遷移，避免舊式Startup與WebHost。 - 優先內置 DI、Options/配置、日誌、ProblemDetails、OpenAPI、健康檢查、限流、輸出緩存、Identity，再考慮第三方基礎設施。
- 保持功能切片內聚，便於從頁面、組件、端點、控制器追溯到服務、數據訪問與測試。
- 尊重現有應用模型；無明確理由時，不要把 Razor Pages 改成 MVC，或把控制器改成 Minimal API。
Reference 覆蓋範圍¶
Skill 內 reference 索引包括：棧選型、Program.cs 與管道、Blazor / Razor Pages / MVC UI、Minimal API 與控制器 API、EF Core 與狀態、安全與 Identity、SignalR / gRPC / Hosted Services、集成測試與部署、版本與升級，以及面向 Microsoft 文檔的 source-map。
執行說明（Execution Notes）¶
- 生成新代碼時，從正確的
dotnet new模板起步，保持生成結構與官方模板可辨認。 - 編輯既有解決方案時，先遵循項目既有約定，再用 reference 避免框架誤用或過時模式。
- 任務涉及「最新」特性時，應在 Microsoft Learn 或 ASP.NET Core 文檔倉庫覈實，而非僅憑記憶。
安裝與啓用¶
officialskills.sh 列出的安裝方式爲：
npx skills add https://github.com/openai/skills --skill aspnet-core
也可將 Skill 目錄鏈接交給支持 Agent Skills 的編碼助手安裝：
https://github.com/openai/skills/tree/main/skills/.curated/aspnet-core
資料中未區分 Cursor、Codex CLI、Claude Code 的安裝差異；按各產品對 npx skills add 或 SKILL 目錄掛載的說明操作即可。
典型用法¶
以下場景來自官方資料中的 When to use it 與 Workflow，可作爲觸發 Skill 的任務描述示例（需結合你倉庫中的實際框架與版本）：
- 腳手架 Minimal API：要求 OpenAPI 文檔與 ProblemDetails 錯誤響應，並走
apis-minimal-and-controllers.md與program-and-pipeline.md。 - 遷移宿主模型：將基於
Startup的舊應用遷移到WebApplicationBuilder，先確認目標框架，再讀versioning-and-upgrades.md與program-and-pipeline.md。 - Razor Pages 安全：爲站點添加 Cookie 認證與基於角色的授權，打開
security-and-identity.md與ui-razor-pages.md。 - MVC 中的 SignalR：在現有 MVC 應用中接入 SignalR Hub 做實時通知，主 reference 爲
ui-mvc.md，並按需打開realtime-grpc-and-background-work.md。 - 控制器集成測試：使用
WebApplicationFactory爲控制器端點編寫集成測試，參考testing-performance-and-operations.md。
生成或修改代碼時，助手應按 Workflow 順序加載 reference，而不是一次性載入全部文件。
適用場景與注意¶
適合誰：日常用 C# / ASP.NET Core 做 Web 或 API，並希望在 Agent 對話裏得到與 Microsoft 當前指引一致的結構、管道與安全做法的 .NET 開發者。該 Skill 位於 OpenAI Curated 列表，與官方 Skills 倉庫同源，對補齊 Agent 在 C# Web 棧上的參考覆蓋有直接意義。
限制與注意：
- Skill 是 reference 與工作流約束，不能替代你本地指定的
TargetFramework與 SDK；版本假設以SKILL.md爲準，舊項目需顯式說明目標版本。 - 「最新」特性必須以 Microsoft Learn 覈實；資料明確要求不要依賴未驗證的記憶。
- 不要在沒有業務理由時切換應用模型；Skill 默認尊重倉庫已有選型。
- 第三方包與雲廠商部署細節以項目爲準；Skill 傾向先用框架內置能力。
結尾¶
aspnet-core 把 ASP.NET Core 多模型、多版本下的選型、管道與橫切能力拆成可按任務加載的 reference，並用固定 Workflow 減少過時 API 與錯誤重構。若你主要在 Agent 裏維護 Blazor、MVC、Minimal API 等 .NET Web 項目，可安裝後按任務描述觸發上述場景。
官方地址：https://github.com/openai/skills/tree/main/skills/.curated/aspnet-core
