按照以下准则在升级.NET项目时从GitHub Copilot现代化中获得最佳结果。
在您开始之前
在开始升级之前准备项目，以获得最佳结果。
验证您的解决方案是否能成功构建并通过测试
代理通过运行生成和测试来验证其所做的更改。 如果在开始之前解决方案已中断，代理无法区分预先存在的故障及其引入的问题。
记录任何已知的测试失败 scenario-instructions.md ，以便代理知道忽略它们。
提交或暂存未提交的工作
从干净的工作目录开始，以避免将未提交的更改与代理的修改混合在一起。 使用干净的基线可以更轻松地查看或还原更改。
git stash
git status
备份非 Git 存储库
该代理还适用于不在源代码管理下的文件夹。 如果您的项目不在 Git 存储库中，代理将跳过分支和提交的操作。 如果是，请在开始之前备份项目文件夹，以便根据需要还原它。
在开始升级之前，请考虑初始化本地 Git 存储库，即使不推送到云提供商也是如此。 通过本地 Git 存储库，可以：
- 使用
git revert回滚单个更改。 - 在提交历史记录中逐步跟踪升级进度。
- 控制要保留或放弃的更改。
- 使原始代码在主分支上安全，而代理在单独的分支上工作。
cd your-project-folder
git init
git add .
git commit -m "Baseline before upgrade"
查看测试覆盖范围
代理依赖于测试来验证其更改是否不会破坏行为。 具有良好测试覆盖率的项目获得更高的置信度升级。
小窍门
您不需要百分之百的覆盖率。 专注于升级最有可能更改的代码，例如 API 边界、序列化、数据库访问和身份验证。
从小型开始
如果这是你第一次使用代理，请选择一个小型的低风险项目作为试点。 类库或实用工具项目是理想的。 从小事做起，可以在处理主应用程序之前了解工作流程、建立信心并发现任何仓库特定的问题。
在升级期间
在代理执行升级时，请遵循这些准则。
使用引导模式进行第一次升级
代理支持引导模式和自动模式。 在引导模式下，代理会在关键决策点暂停，等待您的审核和批准。 从引导模式开始，了解代理的作用以及原因。 熟悉工作流后切换到自动模式。
仔细审核评估
评估是在代理开始进行更改之前捕获问题的最佳机会。 查找:
- 代理可能错过或误识的项目。
- 你知道的依赖项有问题。
- 代理人应该了解您解决方案中的任何异常之处。
如果发现某些问题，请在聊天中告知客服人员，或将信息添加至scenario-instructions.md。 直接编辑 assessment.md 以在代理继续规划之前添加上下文、更正错误的项目或标记问题。
规划阶段需要时间
代理根据其评估生成计划。 在继续之前查看计划：
- 顺序对您的代码库是否有意义？
- 是否有代理可能不知道的依赖项？
- 是否应以不同的方式排除或处理任何项目？
要求代理对任务重新排序、跳过项目或更改其方法。 你比代理更了解代码库，因此请使用该知识。
plan.md直接编辑文件以调整任务顺序、添加任务或删除任务。
注意
直接编辑 plan.md 时请小心。 如果这些更改创建了相互矛盾的指令，代理可能无法完全解释。 例如，在保留依赖于依赖项的项目的同时删除依赖项项目。
立即提供反馈
代理从会话中的更正学习。 如果代理做出一个你不同意的选择：
- 立即告诉它： “不要使用该模式，请改用 X。
- 向
scenario-instructions.md添加持久指南，以便代理能够在任务和会话之间保持记忆。
执行过程中保持投入
执行不是移交。 在告诉代理开始之前，请查看 tasks.md：
- 任务顺序对代码库是否有意义？
- 是否有要跳过或重复的任务？
- 是否缺少任何任务？
要求代理调整任务列表，或在执行开始前直接编辑 tasks.md 。 一旦执行开始，如果智能体在任务中途做出了错误的调用，请立即告知它 — 它会将你的纠正应用于后续操作。
你知道你的代码库比代理更好，因此请在每个阶段使用该知识。
常见错误
请注意这些常见问题，因为它们可能会减慢或使升级复杂化。
具有 50 多个项目的大型解决方案
代理按项目工作，因此大型解决方案需要时间。 耐心并监视进度。 在提交完整解决方案之前，请考虑从一个具有代表性的项目端到端开始。 单项目试点能及早揭示系统性问题。
专用 NuGet 源
对于专用 NuGet 源，请在开始升级之前进行身份验证（例如，通过组织的凭据提供程序或源配置）。 如果没有身份验证，包还原失败会阻止进度。
自定义 MSBuild 目标和导入
复杂的生成自定义（如自定义 .targets 文件、条件导入或非标准生成逻辑）可能会混淆评估并导致意外生成失败。 如果解决方案包含这些自定义项，请在聊天或scenario-instructions.md中提及，以便代理能够处理这些自定义项。
会话超时
长时间运行的升级可能会跨越多个会话。 代理在工作流文件（位于 .github/upgrades/ 下）中跟踪其进度，因此它可以从上次中断的地方继续。 启动新会话时，请提及你所在的位置：“继续.NET 10 升级。我在 Data.Access 项目中间。“
有效协作
交互的质量直接影响结果的质量。
特定于范围
你提供的细节越具体，代理的表现就越好。
| 替代 | 试用 |
|---|---|
| “升级所有内容” | “将 Data.Access 项目升级到 .NET 10” |
| “修复构建” | “修复与已删除 API 相关的CustomerService.cs中的生成错误” |
| “升级数据库内容” | “将 Entity Framework 6 升级到存储库项目中的 EF Core” |
共享约束
提前告知代理真实约束：
- “我们无法破坏公共 API 的向后兼容性。
- “我们在两周内有一个发布截止时间，因此优先考虑 Web 项目。
- “应从此升级中排除旧版报告模块。
解释体系结构
代理会分析代码结构，但它不知道团队的精神模型。 帮助代理了解：
- “Project A 是我们的共享库。 B、C 和 D 都依赖于它。
- “WebApi 项目是我们面向公众的 API;Internal.Api 仅适用于内部服务。
- “模型项目是从 OpenAPI 规范自动生成的。不要直接修改它。
询问原因
代理可以解释其推理。 如果决策看起来不正确，请问：
- “你为什么选择自下而上的顺序？
- “为什么将此包升级到版本 X 而不是 Y？
- “你为什么将此任务分解为子任务？
了解推理有助于提供更好的反馈。
提前保存首选项
如果您对编码样式、模式或方法有很强的偏好，请在第一次会话中将其添加到scenario-instructions.md中。 此文件在会话之间保留，并且始终位于代理的上下文中，使其成为影响行为的最可靠方法。
从问题中恢复
当升级未按预期进行时使用这些策略。
任务后生成失败
告诉代理：“生成在最后一个任务后失败。” 代理分析错误并尝试修复错误。 如果代理无法解决问题：
- 提供手动修复，并告知代理你执行了什么操作。 代理从修复中学习。
- 还原提交（
git revert或重置为上一个提交），让代理尝试不同的方法。 - 跳过有问题的任务，稍后再处理。
选择了错误的策略
如果代理的总体方法不适用于代码库，请重启规划阶段：
- “让我们重做计划。 我想先升级 Web 项目，而不是自下而上。
- 调整策略以一次性升级所有共享库。
代理陷入循环中
如果代理在没有进度的情况下重复相同的修复，请说 “停止” 并描述所观察到的内容，或手动停止会话。 代理可以重置其方法并尝试其他方法。
撤消所有更改
如果使用 Git 分支进行升级，请切换回原始分支来撤消所有内容：
git checkout your-original-branch
git branch -D upgrade-branch
原始代码未更改。 如果在不使用源代码管理的情况下工作，请从开始之前创建的备份还原。
安全性和隐私
代码片段 ：GitHub Copilot 根据 GitHub的Copilot隐私政策 处理这些代码片段，不会将其保留超出当前会话。-
工作流文件（
scenario-instructions.md自定义任务、首选项）会保留在位于存储库中的.github/upgrades/。 GitHub不会将这些文件传输到外部服务。 -
文件夹
.github/upgrades/是存储库的一部分。 提交文件夹，因为它包含升级进度和状态。 代理需要文件夹才能跨会话恢复工作。 升级完成后，可以将其删除。 - 遥测：通过 IDE 的遥测设置禁用。
性能提示
- 关闭不必要的文件和选项卡：代理分析活动工作区，打开的文件更少意味着噪音更少。
- 分阶段升级非常大的解决方案：而不是一次性升级所有项目，请对其进行批处理。 例如，首先升级所有库，然后升级所有 Web 项目，然后测试。
- 使用生成缓存：代理在验证期间运行许多增量生成。 热构建缓存可显著加快验证速度。 避免在任务执行期间清理生成输出。
