本文介绍使用 GitHub Copilot 进行 .NET 现代化改造时可能遇到的常见问题，并按类别分类。 每个条目都遵循问题、原因和解决方案格式，以便快速查找和解决问题。
工作流问题
这些问题与方案发现、恢复工作和任务状态有关。
代理说“找不到方案”
Cause：代理无法将工作区识别为.NET项目。
Solution:
- 确保工作区根目录中包含
.sln、.csproj或.vbproj文件。 - 询问代理： “你使用的是哪种解决方案或项目文件？
- 如果解决方案或项目文件位于子目录中，请以工作区根目录的形式打开该目录，或将代理显式指向该文件。
代理无法恢复以前的工作
原因： 代理 .github/upgrades/ 存储其所有状态的文件夹丢失或损坏。
Solution:
-
.github/upgrades/检查存储库根目录中是否存在该文件夹。 - 如果意外删除了文件夹，请重新启动方案。 代理如果没有其状态文件，则无法恢复。
- 如果文件夹存在，但文件似乎已损坏，请让代理 “重新评估和重新计划” 以重新生成它们。
小窍门
将 .github/upgrades/ 文件夹提交到您的分支，以确保在不同会话和机器之间保留该文件夹。
任务停滞在进行中
原因：上一个会话在代理进行任务中途时结束的。
Solution:
- 在大多数情况下，代理会自动检测过时的任务。 告知代理 “继续” 或 “重启当前任务”。
- 如果停滞状态仍然存在，请告知代理 “将当前任务标记为挂起并重新启动” 或 “重新评估并继续执行上一个已完成的步骤”。
- 检查任务的相应
progress-details.md文件，以了解上一个会话已停止的位置。
代理不断建议错误的方案
原因： 代理的分析识别出了未预料到的项目特点，并推测出了不同于您预期的情形。
Solution:
明确所需内容。 而不是 “升级我的项目”， 例如：
- “我想升级到 .NET 10.”
- “我想从 Newtonsoft.Json 迁移到 System.Text.Json。
- “将项目转换为 SDK 样式格式。”
此外，添加情景偏好至scenario-instructions.md以防止将来的不匹配。
生成和编译问题
这些问题与生成失败、NuGet 还原问题和代码生成错误有关。
代理更改后构建失败
原因： 升级可以引入 中断性 API 更改、缺少的包或不兼容的代码模式。
Solution:
- 告知代理失败情况。 代理会自动分析错误。
- 如果代理无法解决问题，请还原最后一次提交（
git revert HEAD），并要求代理尝试其他方法。 - 对于复杂的故障，请检查
execution-log.md以了解代理所做的更改以及顺序。
NuGet 还原失败
原因： 与目标框架的包不兼容，或者使用专用 NuGet 源的身份验证失败。
Solution:
- 对于专用源： 在开始升级之前向源进行身份验证。
- 对于不兼容的包： 告知代理哪个包有问题。 代理可以搜索兼容版本或建议备用包。
-
对于源连接问题： 验证是否可以手动运行
dotnet restore。 首先修复任何馈送问题，然后让代理重试。
代理生成不编译的代码
原因： AI 生成的代码可能包含错误，尤其是在边缘情况或不常见的 API 模式中。
Solution:
- 代理会自动检测编译错误。 如果代理处于困境，请手动提供指导或修复代码，并告知代理继续。
- 如果代理在多次尝试后难以处理特定修复，请手动编辑代码并告诉代理： “我修复了MyClass.cs中的编译错误，请标记此任务完成。
- 如果其他位置出现相同的问题，代理会从手动修复中学习并应用类似的模式。
Git 问题
注释
代理工具也适用于非 Git 目录。 如果工作区不是 Git 存储库，代理将跳过 Git 操作（分支、提交），并将更改直接应用于文件。 如果没有 Git，请在开始之前手动备份项目，以便根据需要还原。
代理无法创建分支
原因： 工作树中有未提交的更改、分支命名冲突，或 Git 没有在工作区中初始化。
Solution:
- 在启动方案之前提交或保存挂起的更改。
- 验证 Git 是否已初始化：在工作区根目录中运行
git status。 - 如果已存在具有代理预期名称的分支，请删除现有分支或要求代理使用不同的分支名称。
撤消所有代理更改
原因： 升级未按计划进行，你希望从头开始。
Solution:
- 切换回原始分支：
git checkout main（或任何基本分支）。 - 代理的工作分支包含与主分支隔离的所有更改。
- 若要完全删除代理的分支，请执行以下操作：
git branch -D <agent-branch-name> - 若要保留一些更改，请拣选特定的提交：
git cherry-pick <commit-hash>。
小窍门
代理软件对每个任务进行精细提交，以便有选择地保留成功的更改。
性能问题
这些问题与升级速度和评估持续时间有关。
代理速度缓慢或需要很长时间
原因： 具有许多项目、复杂依赖项关系图或许多中断性变更的大型解决方案自然需要更长的时间。
Solution:
对于非常大的解决方案（50 多个项目），请考虑批量升级。 将相关项目分组并将它们一起升级。
评估需要很长时间
原因： 评估将分析每个项目的依赖项、NuGet 包、目标框架和适用的中断性变更。 对于大型解决方案，评估自然需要更长的时间。
Solution:
- 大型解决方案的评估时间较长。 无需采取任何行动。
- 在 Output 面板中监视进度（从 Visual Studio 的下拉列表中选择 AppModernizationExtension）。
- 每个场景仅评估一次。 后续阶段使用缓存的结果。
自定义问题
这些问题与自定义技能和方案说明文件相关。
未被识别的自定义技能
原因： 技能文件位于错误的位置或缺少或无效的元数据，或者技能格式不正确。
Solution:
- 验证技能文件是否位于支持的位置之一：
-
.github/skills/（库级，整个团队） -
.github/upgrades/skills/（方案级别） -
%UserProfile%/.copilot/skills/（用户级、个人版）
-
- 检查技能元数据是否至少包括
name和description字段。 -
discovery字段（如果已设置）必须为以下项之一：lazy、preload或scenario。 - 验证技能是否
description与预期应用的任务类型匹配。 代理使用描述匹配来选择技能。
对 scenario-instructions.md 的更改不会生效
原因： 代理可能无法在会话期间重新读取文件，或者您的编辑在文件中的位置不正确。
Solution:
- 要求代理 “重新加载说明” 或启动新的聊天会话以强制重新读取。
- 确保编辑位于文件的正确部分中：
- 用户首选项： 对于常规首选项和约束。
- 关键决策： 记录升级期间做出的重要决策。
- 自定义说明： 用于特定行为覆盖。
- 验证文件是否已保存，并在预期路径中：
.github/upgrades/{scenarioId}/scenario-instructions.md
获取帮助
当某些东西未按预期工作时：
- 询问代理： 问 “上一个任务有什么问题？” 代理通常可以解释所发生的事情并建议后续步骤。
-
查看执行日志：在
.github/upgrades/{scenarioId}/中打开execution-log.md。 日志显示代理所执行的操作的时间记录，包括代理遇到的任何错误。 - 提交问题：如果发现了 bug 或者代理在某个方面一直出现问题，请在 @modernize-dotnet GitHub 存储库提交相关问题。
