.NET 项目框架升级实战指南基于 awesome-copilot 的 dotnet-upgrade 指令体系【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本篇技术指南以开源仓库 awesome-copilot 中 .NET Framework Upgrade Specialist 指令 为核心系统讲解如何将一个多项目 .NET 解决方案安全、增量地升级到更高的框架版本例如 .NET 6 → .NET 8/10。读者将掌握项目类型识别、依赖图谱分析、逐项目升级、NuGet 兼容性处理、破坏性变更修复以及 CI/CD 管线同步更新的完整方法论并可直接配合仓库中的 .NET Upgrade Agent 与 dotnet-upgrade Skill 落地执行。一、升级前的准备工作1.1 识别项目类型升级的第一步不是改代码而是摸清解决方案里每个项目的类型。检查每一个*.csproj中的TargetFramework值按以下规则归类目标框架值项目类型说明netcoreapp*如netcoreapp3.1.NET Core / .NET现代后续版本直接写作net6.0、net8.0等netstandard*如netstandard2.0.NET Standard用于跨框架共享的类库net4*如net472、net48.NET Framework传统 Windows 框架运行于 Windows 与 IIS在 dotnet-upgrade Agent 的 Quick Start 中还提供了自动发现命令可以直接在终端执行以批量获取每个项目的当前目标框架# 检查本机已安装的全局 SDK dotnet --list-sdks # 列出解决方案下所有项目 dotnet sln list # 批量检测所有 csproj 的 TargetFramework find . -name *.csproj -exec grep -H TargetFramework {} \; # 汇总去重快速了解解决方案使用的框架版本分布 grep -r TargetFramework **/*.csproj | sed s/.*TargetFramework//;s/\/TargetFramework// | sort | uniq # 验证运行时环境 dotnet --info | grep Version注意该 Agent 也给出了版本检测的边界——通过dotnet --list-sdks看到的是本机安装的 SDK而项目实际目标框架以*.csproj中的TargetFramework为准两者可能不一致需要分开核对。1.2 选定目标版本根据项目类型选择升级目标遵循LTS长期支持优先原则.NET Core / .NET现代升级到最新的 LTS 版本例如net10.0。Agent 的 Quick Start 建议通常选择比当前版本领先 2 年左右的新稳定版如net6.0 → net8.0、net7.0 → net9.0并按 LTS 优先。.NET Standard优先迁移到 .NET 8如果必须保留则以netstandard2.1为目标。.NET Framework至少升级到4.8该系列的最后版本如条件允许则迁移到 .NET 8。从 dotnet-upgrade.agent.md 的 Classification Rules 可以看到与本指令一致的分类口径netcoreapp、net5.0、net6.0归为 Modern .NETnetstandard*建议迁移到当前 .NET 版本net4*建议通过中间步骤迁移到 .NET 8。1.3 审阅发布说明与破坏性变更在动手之前需要查阅目标版本的 Whats New 与升级指南重点收集两类信息新增功能对代码现代化带来的机会以及破坏性变更breaking changes对现有代码的冲击。原文档强调要顺序执行、不要一次性升级所有项目。二、升级策略从低依赖到高依赖整个升级过程遵循顺序推进原则核心策略如下逐个升级项目绝不一次性修改全部项目。从独立的类库项目开始依赖最少风险最低。逐步过渡到依赖较高的项目如 API、Azure Functions 等宿主应用。每个项目都必须构建通过、测试通过后才能进入下一个项目。只有所有项目的构建都成功后才更新 CI/CD 文件。dotnet-upgrade Agent 给出了更细化的升级顺序建议独立类库依赖最少的库最先升级共享组件与公共工具Shared components and common utilitiesAPI、Web 或 Function 项目测试项目、集成点和管线配置最后处理这种底层先行的顺序能最大限度缩小每次变更的影响面类库升级后上层项目仍然可以用旧引用编译反过来则不行。三、确定升级顺序依赖图谱分析要确定谁先谁后必须先看清项目之间的引用关系。原文档给出了三种方式Visual Studio在解决方案资源管理器中查看项目的Dependencies节点。dotnet CLI查看单个项目的直接项目引用dotnet list ProjectName.csproj reference依赖图生成器生成整个解决方案的还原依赖图 JSONdotnet msbuild SolutionName.sln /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPathgraph.json然后检查graph.json即可看到项目间的依赖顺序。从 dotnet-upgrade SKILL 的提示词库还可以看到两个进阶角度依赖兼容性审查按依赖图深度评估升级复杂度和传递依赖审查升级后检查传递依赖与潜在版本冲突并制定冲突解决策略。这与先看直接引用、再评估整体图深度的实践一致。四、逐项目分析csproj 与 NuGet 包4.1 打开并检查 csproj典型的目标框架与包引用写法如下Project SdkMicrosoft.NET.Sdk PropertyGroup TargetFrameworknet6.0/TargetFramework /PropertyGroup ItemGroup PackageReference IncludeNewtonsoft.Json Version13.0.1 / PackageReference IncludeMoq Version4.16.1 / /ItemGroup /Project需要检查的两个关键点TargetFramework修改为目标版本例如net10.0。PackageReference逐一确认每个 NuGet 包是否支持新框架。4.2 检查并更新 NuGet 包先列出所有过期的包dotnet list package --outdated然后逐个更新dotnet add package PackageName --version LatestVersionAgent 中的逐项目升级流程则建议按dotnet restore→dotnet list package --outdated→dotnet add package的顺序执行先恢复依赖再检查更新避免遗漏。4.3 迁移 legacy 的 packages.config如果项目仍使用传统的packages.config非 SDK 风格项目需要先迁移到PackageReferencedotnet migrate ProjectPathdotnet-upgrade SKILL 将其归纳为Legacy Package Detection提示词场景先定位使用packages.config的项目再统一迁移避免新旧两种包管理方式混用。五、代码调整与破坏性变更处理分析完 NuGet 包后必须审查代码中是否有需要适配新框架的 API 变更。原文档给出了三类高频示例这里完整展开并补充说明。5.1 System.Text.Json 替换 Newtonsoft.Json// 旧写法Newtonsoft.Json var obj JsonConvert.DeserializeObjectMyClass(jsonString); // 新写法System.Text.Json.NET Core 3.0 内置 var obj JsonSerializer.DeserializeMyClass(jsonString);System.Text.Json是 .NET 内置的高性能 JSON 库序列化 API 与 Newtonsoft 有差异如默认严格属性名匹配、大小写策略通过PropertyNamingPolicy配置替换时需同步检查反序列化选项例如var options new JsonSerializerOptions { PropertyNameCaseInsensitive true, PropertyNamingPolicy JsonNamingPolicy.CamelCase }; var obj JsonSerializer.DeserializeMyClass(jsonString, options);5.2 IHostBuilder 替换 WebHostBuilder// 旧写法 IWebHostBuilder builder new WebHostBuilder(); // 新写法.NET 通用主机支持后台服务、配置与日志统一管理 IHostBuilder builder Host.CreateDefaultBuilder(args);通用主机的迁移往往伴随Startup.cs→Program.cs的配置结构调整详见下文 5.4。5.3 Azure SDK 更新// 旧写法Azure 存储 SDK v11命名空间 Microsoft.Azure.* CloudBlobClient client storageAccount.CreateCloudBlobClient(); // 新写法Azure.Storage.Blobs命名空间 Azure.* BlobServiceClient client new BlobServiceClient(connectionString);从 Agent 的 Breaking Changes Modernization 一节可以看出这是一类系统性问题将过时的 SDK如Microsoft.Azure.*替换为新的Azure.*包是 .NET 升级中最常见的第三方依赖迁移动作之一。5.4 常见破坏性变更清单原文档总结的常见问题包括弃用 API→ 替换为官方支持的新 API。包不兼容→ 查找更新的 NuGet 版本或迁移到微软官方支持的库例如上文的 Azure SDK。配置差异→ .NET 8 中典型的Startup.cs→Program.cs重构改用顶级语句 Top-level statements 与最小化托管模型。dotnet-upgrade SKILL 从提示词工程角度补充了几个值得关注的现代化方向异步模式转换将合适的同步调用转为 async提升性能与可扩展性、共享依赖策略评估共享依赖的升级策略寻找微软官方命名空间下的替代品、以及API 弃用检测使用 .NET Upgrade Assistant 与 API Analyzer 自动扫描。六、逐项目升级流程对每个项目按以下流程执行更新.csproj中的TargetFramework。将 NuGet 包更新为与目标框架兼容的版本。升级并还原最新 DLL 后审查代码中需要调整的部分。重新构建项目dotnet build ProjectName.csproj如果有单元测试运行测试dotnet testAgent 建议更精确地只运行对应测试项目dotnet test ProjectName.Tests.csproj修复所有构建或运行时问题后再进入下一个项目。注意第 5 步中 Agent 的写法明确了测试项目通常命名为ProjectName.Tests.csproj的惯例但实际项目命名可能不同应以仓库中的真实测试项目为准。七、端到端验证所有项目升级完成后进行整体验证重新构建整个解决方案。运行全部自动化测试单元测试与集成测试。部署到较低环境UAT/Dev进行验证。重点确认API 启动时无运行时错误日志与监控集成正常工作外部依赖数据库、消息队列、缓存连接符合预期。dotnet-upgrade SKILL 的 Service Integration Verification 提示词进一步细化验证日志、遥测与服务连通性并核对向后兼容性与运行时行为——这正是端到端验证的完整内涵。八、工具与自动化Upgrade Assistant 与 CI/CD 管线8.1 .NET Upgrade Assistant可选dotnet tool install -g upgrade-assistant upgrade-assistant upgrade SolutionName.slnUpgrade Assistant 会自动分析项目并给出升级建议包括目标框架选择、API 迁移提示等。原文档将其定位为可选工具但建议参考它的建议来处理破坏性变更。Agent 中则更明确地将其用于初始建议与自动扫描并配合分析器检测过时 API。8.2 同步升级 CI/CD 构建管线升级 .NET 项目时构建管线也必须引用正确的 SDK、NuGet 版本与任务否则本地构建通过、CI 却会失败。原文档给出了完整的管线更新步骤a. 定位管线 YAML 文件常见位置包括.azuredevops/.pipelines/Deployment/仓库根目录的*.ymlb. 扫描 .NET SDK 安装任务查找类似UseDotNet2的任务- task: UseDotNet2 inputs: version: current-sdk-version或带有displayName: Use .NET Core sdk current-sdk-version的任务。c. 更新 SDK 版本以匹配新框架- task: UseDotNet2 displayName: Use .NET SDK new-version inputs: version: new-version includePreviewVersions: true # 可选仅在升级到预览版时启用d. 按需更新 NuGet 工具版本- task: NuGetToolInstaller0 displayName: Use NuGet new-version inputs: versionSpec: new-version checkLatest: truee. 更新后验证管线将变更提交到功能分支触发一次 CI 构建确认YAML 语法有效SDK 安装成功项目在新框架下能够还原、构建并通过测试。dotnet-upgrade Agent 在此基础上给出了动态版本的进阶写法让管线版本号与目标版本自动对齐Azure DevOps使用变量注入 SDK 版本- task: UseDotNet2 inputs: packageType: sdk version: $(TargetDotNetVersion).xGitHub Actions- uses: actions/setup-dotnetv4 with: dotnet-version: ${{ env.TargetDotNetVersion }}.xAgent 还建议更进一步用 GitHub Actions 或 Azure Pipelines 自动化升级检测定时运行dotnet --list-sdks检查新 .NET 版本发布并由 Agent 自动为过时框架创建 PR。九、提交与 PR 规范9.1 提交计划始终在指定分支上工作若上下文未指定分支则新建分支upgradeNetFramework。每次成功升级一个项目后提交一次。若某个项目升级失败回滚到上一个提交再增量修复。Agent 的分支命名规范更细致使用功能分支upgrade/project-to-targetVersion保持提交频繁且原子化如果合并后 CI 失败则回退 PR 并隔离故障模块。9.2 PR 指南每个仓库使用单个 PR标题格式Upgrade to .NET [VERSION]内容包含更新的目标框架NuGet 升级摘要测试结果汇总见下节检查清单。若替换了 API给 PR打上breaking-change标签。9.3 升级检查清单附于 PR 中原文档要求将以下表格作为升级进度跟踪工具并附在 PR 中Project NameTarget FrameworkDependencies UpdatedBuilds SuccessfullyTests PassingDeployment VerifiedNotesProject A☐ net10.0☐☐☐☐Project B☐ net10.0☐☐☐☐Project C☐ net10.0☐☐☐☐✅ 每完成一个项目的一步就在对应列打勾。十、多仓库执行可选对于拥有多个仓库的组织原文档给出了规模化执行路径将本instructions.md存放在一个中央升级模板仓库中。向 SWE Agent / Cursor 提供指令Upgrade all repositories to latest supported .NET versions following instructions.mdAgent 应检测每个仓库的项目类型应用合适的升级路径为每个仓库创建 PR。dotnet-upgrade SKILL 补充了企业级诉求跨仓库验证自动化输出、建立标准化验证工作流以及用汇总仪表盘或 Markdown 清单跟踪多项目升级进度。十一、最佳实践与注意事项原文档末尾给出的关键经验优先迁移到现代 .NET如果当前在 .NET Framework 或 .NET Standard 上应评估迁移到 .NET 8/10 以获得长期支持。尽早自动化测试CI/CD 应在测试失败时阻止合并merge。增量升级大型解决方案可能需要一次只升级一个项目。可直接复用的 Agent 提示词原文档提供了一个开箱即用的示例提示词Upgrade this repository to the latest supported .NET version following the steps indotnet-upgrade-instructions.md. Detect project type (.NET Core, Standard, or Framework) and apply the correct migration path. Ensure all tests pass and CI/CD workflows are updated.十二、在 awesome-copilot 仓库中的配套资产本指令并非孤立文件它在仓库中被组织为完整的能力矩阵可直接组合使用指令本体instructions/dotnet-upgrade.instructions.md —— 本文所依据的完整升级方法论准备、策略、执行、验证、交付。Agent 定义agents/dotnet-upgrade.agent.md —— 名为.NET Upgrade的专用 Agent声明了codebase、runCommands、runTests、web/fetch、microsoft.docs.mcp等工具提供 Chat Modemode: dotnet-upgrade、版本自动检测命令与即用提示词库。Skill 提示词库skills/dotnet-upgrade/SKILL.md —— 按项目发现与评估、升级策略与排序、框架定位与代码调整、NuGet 管理、CI/CD 更新、破坏性变更分析、版本控制、文档与沟通、工具与自动化、最终验证交付十个主题组织的即用提示词。插件打包plugins/csharp-dotnet-development/plugin.json 将dotnet-upgradeSkill 纳入csharp-dotnet-development插件版本 1.2.0其 README 展示了安装方式与斜杠命令copilot plugin install csharp-dotnet-developmentawesome-copilot装好后可通过/csharp-dotnet-development:dotnet-upgrade直接调用。指令索引docs/README.instructions.md 将本文件收录为 .NET Framework Upgrade Specialist并说明了安装方式点击 VS Code / VS Code Insiders 安装按钮或将*.instructions.md放入工作区.github/instructions/目录指令即自动作用于 Copilot 行为。按 docs/README.instructions.md 的说明将该文件复制到项目工作区的.github/copilot-instructions.md或.github/instructions/dotnet-upgrade.instructions.md后Copilot 便会在 .NET 升级类任务中自动遵循上述完整流程实现检测项目类型 → 制定升级序列 → 逐项目升级 → 修复破坏性变更 → 同步 CI/CD → 附清单交付 PR的闭环。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考