自定义升级说明是 Markdown 文件，用于指导 GitHub Copilot 的现代化改造，以便在升级期间应用特定转换。 创建这些文件以自动执行重复更改，例如将一个库替换为另一个库或应用特定的 API 升级。
本文介绍如何创建和构建自定义升级指令文件、隔离测试它并将其集成到升级工作流的评估阶段。
先决条件
在创建自定义说明之前，请在开发环境中配置 GitHub Copilot 的现代化功能。 有关安装步骤，请参阅 Install GitHub Copilot modernization。
了解自定义升级说明
GitHub Copilot 在升级的评估和规划阶段会按需以 Markdown 文件格式检索自定义升级说明。 自定义升级说明不同于 copilot-instructions.md 因为它们是：
- 目标是自动化代码和依赖项的变更。
- 仅当与当前升级评估或计划相关时才检索。
- 复制到每个存储库时，可跨解决方案重复使用。
使用以下方法构建说明文件：
- 描述行动的简短标题。 例如，“将 Newtonsoft.Json 替换为 System.Text.Json”。
- 简洁的问题语句或先决条件部分。
- 显式步骤逻辑（“如果找到 X，请执行 Y” ）。 避免模糊的语言。
- （推荐）从实际本地编辑中捕获的一个或多个差异示例，用于指导转换。
除了定制升级说明，还可以利用标准技能和说明系统推进GitHub Copilot的现代化。 技能为代理添加能力，说明文件（如 copilot-instructions.md）提供全局指导。
创建自定义升级说明
按照以下步骤生成和优化新的指令文件。 这些部分重点是将Newtonsoft.Json替换为System.Text.Json，作为一个示例。
在 解决方案资源管理器 窗口中，右键单击 solution>Modernize。
-或-
打开Copilot聊天面板并键入
@Modernize以启动与代理的对话。注释
这些步骤适用于Visual Studio。 在Visual Studio Code和其他环境中，直接从Copilot聊天面板调用
modernize-dotnet代理。 在Visual Studio中，代理命名为Modernize。在聊天中，键入：
I want to generate a custom upgrade instruction.在询问时，请您提供一个情景，例如
I want to replace Newtonsoft with System.Text.Json，以便由Copilot创建文件。当Copilot创建新文件（如
replace_newtonsoft_with_system_text_json.md），查看内容并在聊天中对其进行优化。 例如，要求Copilot“阐明检测条件”或“添加先决条件节”。“小窍门
将文件添加到解决方案中，以便查看（如果尚未包含）。
使用真正的差异示例加强指令。
- 在一个项目中手动更改所需的代码。 例如，“删除
Newtonsoft.Json包，使用指令更新，并将代码替换为JsonConvertJsonSerializer.” - 在聊天中，打开指令文件时，键入：
Check my git changes and add diffs as examples to my instruction file - 确认 Copilot 使用了 git diff 并将一个围栏式 diff 块或结构化示例附加到了 Markdown 文件中。
- 在一个项目中手动更改所需的代码。 例如，“删除
创作提示
按照以下准则编写清晰有效的自定义升级说明，Copilot可以可靠地解释：
- 使用明确的条件措辞：
If code references X, then do Y. - 为每个文件保留一个转换;当多个文件必须按顺序运行时，请使用先决条件。
- 提供至少一个具体示例，例如差异或前后代码段，以提高转换准确性。
- 避免使用像“改进”或“修复”这样不明确的动词；应使用明确的操作，例如“替换”、“删除”和“更新”。
测试自定义升级指令（一次性运行）
在升级期间运行指令之前，请隔离验证它。 独立测试有助于优化检测并验证代码更改。
在 解决方案资源管理器 窗口中，右键单击 solution>Modernize。
注释
这些步骤适用于Visual Studio。 在Visual Studio Code和其他环境中，直接从Copilot聊天面板调用
modernize-dotnet代理。在聊天中，使用类似于文件名的措辞调用指令。 例如，
replace Newtonsoft with System.Text.Json。在聊天窗口中确认Copilot检索了指令文件：
> Getting instructions for 'replace Newtonsoft with System.Text.Json'. Perfect! I've retrieved the scenario instructions for upgrading from Newtonsoft.Json to System.Text.Json. Now I'll begin the analysis following the scenario-specific instructions.如果Copilot未指示它找到指令，请使用文件名中的关键字重试，例如相同的谓词和名词组合。
查看建议的更改（解决方案差异、待提交的更改或预览的修改），以确认自定义升级指令的行为符合预期。
验证提示
如果测试运行未生成预期结果，请使用以下故障排除提示来优化说明文件：
- 如果Copilot仅更新包版本，而不是替换包，请确保明确说明删除或替换旧包。
- 请保持一致的命名，以便自然语言激活功能能够匹配。 例如，以
replace_开始文件名，并以“替换...”开始聊天请求。 - 在测试期间，添加任何缺失的代码模式作为示例以提高覆盖率。
在升级期间应用自定义说明
使用以下步骤将现有自定义升级指令合并到升级的评估阶段。
在 解决方案资源管理器 窗口中，右键单击 solution>Modernize。
注释
这些步骤适用于Visual Studio。 在Visual Studio Code和其他环境中，直接从Copilot聊天面板调用
modernize-dotnet代理。在聊天中，选择
Upgrade to a newer version of .NET。 在它开始评估之前，请回答Copilot的问题。监视聊天，以查看在评估期间Copilot是否自动检索自定义指令文件。 查找一条消息，该消息表明它已打开 Markdown 指令文件。
如果 Copilot 不会自动应用自定义指令，请明确请求它们。 使用类似于文件名的措辞。 例如，
use the custom instructions to replace Newtonsoft with System.Text.Json during the assessment。等待Copilot确认它检索到 Markdown 文件。 如果未看到对指令文件的引用，请使用文件的键谓词（替换、更新、删除）和包名称重新编写请求。
查看
assessment.md文件夹中生成的.github/upgrades文件。 确认评估包括自定义指令识别的问题和更改。例如，替换 Newtonsoft 时，评估结果显示：
- 使用
Newtonsoft.Json包的项目。 - 需要为
System.Text.Json进行重构的代码模式。 - 要删除或替换的依赖项。
- 使用
如果需要，请编辑
assessment.md文件以添加上下文，或在继续之前调整识别的问题。告知Copilot，当评估反映出自定义指令后，继续进入规划阶段。
查看Copilot生成的
plan.md文件。 此文件包含用于解决评估中问题的策略。通过指示 Copilot 继续，进入执行阶段。 在 Copilot 应用转换时监视
tasks.md文件。
更好的激活建议
如何命名和调用自定义升级说明会影响 Copilot 是否会自动检索它们。 遵循以下准则提高激活可靠性：
- 匹配文件的谓词。 如果文件名使用
replace，请使用该措辞（不是upgrade或fix）。 - 为每个文件保留一个转换，以便清晰和重复使用。 通过列出每个文件中的先决条件对多个文件进行排序。
- 在评估阶段请求自定义说明以获取最佳结果，而不是在计划或执行之前等待。
- 避免出现模棱两可的请求，例如“改进评估”。 明确：“在评估期间应用‘replace_newtonsoft_with_system_text_json’说明。”
验证已实施的更改
升级完成后：
- 在
tasks.md中查看.github/upgrades文件，以了解与自定义指令相关的任务状态。 - 检查在执行阶段创建的 Git 提交，以识别与自定义指令相关的更改。
- 运行测试以确保功能行为保持正确。
- 可选：从成功的更改中捕获差异示例，并将其添加到指令文件中，以增强未来的自动化。
清理资源
删除或合并任何临时指令文件，以避免将来升级中出现重叠转换。
