套用自訂的 .NET 升級指令

自訂升級指示是 Markdown 檔案，用於引導 GitHub Copilot Upgrade 在升級期間套用特定的轉換作業。 建立這些檔案以自動化重複性變更，例如替換一個函式庫或套用特定的 API 升級。

本文說明如何建立並結構化自訂升級指令檔，單獨測試，並將其整合進升級工作流程的評估階段。

先決條件

在建立自訂指令前，先在你的開發環境中設定 GitHub Copilot 升級。 關於安裝步驟，請參見「安裝 GitHub Copilot 升級」。

瞭解自訂升級指示

GitHub Copilot 升級功能會在升級的評估與規劃階段視需要以 Markdown 檔案形式擷取自訂升級指示。 客製化升級說明與copilot-instructions.md的不同之處在於：

  • 目標是自動化程式碼和相依性變更。
  • 僅在與當前升級評估或計畫相關時檢索。
  • 複製到每個儲存庫時，可跨解決方案重複使用。

使用以下方式建構您的指令檔案：

  • 描述該動作的簡短標題。 例如，「將 Newtonsoft.Json 取代為 System.Text.Json」。
  • 簡潔的問題陳述或先決條件部分。
  • 明確的步驟邏輯（「如果找到 X，就執行 Y」）。 避免使用模糊的語言。
  • （推薦）從實際本機編輯擷取的一或多個差異範例，以引導轉換。

除了自訂升級說明外，你還可以透過標準的技能與說明系統擴展 GitHub Copilot 升級。 技能為代理提供能力，指令檔（如 copilot-instructions.md）則提供全域指引。

建立自訂升級指示

請依照下列步驟產生和精簡新的指令檔案。 這些章節著重於將 替換 Newtonsoft.Json 為 System.Text.Json 作為範例。

啟動升級

請依照以下步驟開始升級：

  1. 啟動代理人時，請使用以下其中一種方法：

    • Visual Studio：右鍵點擊 方案總管 中的解決方案或專案，選擇 Modernize。 或者，打開 GitHub Copilot Chat 視窗並輸入 @Modernize.
    • Visual Studio Code：打開 GitHub Copilot Chat面板並輸入 @upgrade。
    • GitHub Copilot CLI：輸入 @upgrade，接著輸入您的升級或遷移請求。
    • GitHub Copilot 應用程式：在代理選擇器中，選擇 Upgrade。

  2. 告訴客服人員要升級或遷移什麼。

建立指令檔案

  1. 在聊天中，輸入： I want to generate a custom upgrade instruction。

  2. 當被要求時，提供像是 I want to replace Newtonsoft with System.Text.Json 這樣的情境，讓Copilot建立檔案。

  3. 當 Copilot 建立新的檔案時，例如 replace_newtonsoft_with_system_text_json.md，檢閱內容並在聊天中完善它。 例如，請Copilot「釐清偵測標準」或「新增先決條件」。

    小提示

    如果檔案尚未包含在方案中，請將其加入以便在方案中顯示。

  4. 用真實的差異範例來強化教學。

    1. 在一個專案中手動進行所需的程式碼變更。 例如，“刪除套件 Newtonsoft.Json ，使用指令更新，並將代碼替換 JsonConvert 為 JsonSerializer”。
    2. 在聊天中，開啟指令檔案，輸入： Check my git changes and add diffs as examples to my instruction file。
    3. 確認 Copilot 使用 git diff 並在 Markdown 檔案中附加了有圍欄的 diff 區塊或結構化範例。

編寫秘訣

請遵循以下指引，撰寫清晰且有效的客製化升級指示，讓 Copilot 能可靠解讀：

  • 使用清晰的條件語句： If code references X, then do Y.
  • 每個檔案保留一個轉換;當多個檔案必須依序執行時，請使用必要條件。
  • 至少提供一個具體範例，例如差分或前後的片段，以提升轉換準確度。
  • 避免使用像「改進」或「修正」這類含糊動詞;使用明確的動作，如「替換」、「移除」和「更新」。

測試自訂升級指示 （一次性執行）

在升級時執行指令前，先單獨驗證指令。 獨立測試有助於你精煉偵測並驗證程式碼變更。

啟動升級

請依照以下步驟開始升級：

  1. 啟動代理人時，請使用以下其中一種方法：

    • Visual Studio：右鍵點擊 方案總管 中的解決方案或專案，選擇 Modernize。 或者，打開 GitHub Copilot Chat 視窗並輸入 @Modernize.
    • Visual Studio Code：打開 GitHub Copilot Chat面板並輸入 @upgrade。
    • GitHub Copilot CLI：輸入 @upgrade，接著輸入您的升級或遷移請求。
    • GitHub Copilot 應用程式：在代理選擇器中，選擇 Upgrade。

  2. 告訴客服人員要升級或遷移什麼。

測試升級指令

  1. 在聊天中，用與檔名相似的措辭呼叫指令。 例如： replace Newtonsoft with System.Text.Json 。

  2. 請在聊天視窗確認 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 沒有顯示找到指示，請用檔案名稱中的關鍵字重新嘗試，例如相同的動詞和名詞組合。

  3. 檢視建議的變更（解決方案差異、待提交或預覽修改），確認自訂升級指令是否如預期運作。

驗證提示

如果測試執行沒有達到預期結果，請使用以下故障排除技巧來精煉你的指令檔：

  • 如果 Copilot 只更新套件版本而非替換套件，請確保指令明確說明要移除或替換舊套件。
  • 請使用一致的命名方式，以確保自然語言的啟動匹配能夠準確運作。 例如，將檔案名稱開頭以 replace_ 開始，並在開啟聊天請求時以「替換...」作為起始語。
  • 測試時，將缺失的程式碼模式作為範例以提升覆蓋率。

在升級期間套用自訂指示

利用這些步驟，將現有的客製化升級指示納入升級評估階段。

啟動升級

要開始升級，請依照以下步驟操作：

  1. 啟動代理人時，請使用以下其中一種方法：

    • Visual Studio：右鍵點擊 方案總管 中的解決方案或專案，選擇 Modernize。 或者，打開 GitHub Copilot Chat 視窗並輸入 @Modernize.
    • Visual Studio Code：打開 GitHub Copilot Chat面板並輸入 @upgrade。
    • GitHub Copilot CLI：輸入 @upgrade，接著輸入您的升級或遷移請求。
    • GitHub Copilot 應用程式：在代理選擇器中，選擇 Upgrade。

  2. 告訴客服人員要升級或遷移什麼。

自訂升級

在評估階段請遵循以下步驟：

  1. 監控聊天室，看看 Copilot 是否會在評估過程中自動取得你的自訂指令檔案。 找是否有訊息顯示它開啟了 Markdown 指令檔。

    如果 Copilot 沒有自動套用自訂指令，請明確要求。 用與檔案名稱相似的措辭。 例如： use the custom instructions to replace Newtonsoft with System.Text.Json during the assessment 。

  2. 等 Copilot 確認它已經取得 Markdown 檔案。 如果你沒看到指令檔的參考，請用檔案的關鍵字動詞（replace、update、remove）和套件名稱重新陳述請求。

  3. 檢視assessment.md資料夾中的.github/upgrades檔案。 確認評估包含你的客製化指示所識別的問題與變更。

    例如，當更換 Newtonsoft 時，評估會指出：

    • 使用 Newtonsoft.Json 套件的專案。
    • 程式碼模式用於重構針對System.Text.Json。
    • 需要移除或替換依賴性。

  4. 如有需要，請編輯 assessment.md 檔案以補充背景或調整已識別的問題再繼續。

  5. 當評估結果反映出你的客製化指示後，告訴 Copilot 繼續進入規劃階段。

  6. 請檢查 Copilot 產生的 plan.md 檔案。 此檔案包含針對評估問題的策略。

  7. 指示 Copilot 繼續，以進入執行階段。 監視 tasks.md 檔案，以觀察 Copilot 套用轉換的過程。

改進激活的方法

你如何命名並呼叫自訂升級指令，會影響 Copilot 是否會自動取得這些指令。 請遵循以下指引以提升啟動可靠性：

  • 與檔案的動詞相符。 如果檔名使用 replace，請使用該表述（非 upgrade 或 fix）。
  • 每個檔案保留一個轉換，方便辨識和重複使用。 透過列出每個檔案中的先決條件來排序多個檔案。
  • 在評估階段就申請客製化指示以獲得最佳效果，而非等待規劃或執行。
  • 避免像 「改進評量」 這類模糊的要求。明確說明：「評估時應用replace_newtonsoft_with_system_text_json指示。」

驗證套用的變更

升級完成後：

  1. 請檢視 tasks.md 檔案 .github/upgrades ，查看與自訂指令相關的任務狀態。
  2. 檢查執行階段所建立的 Git 提交是否有與自訂指令相關的變更。
  3. 執行測試以確保功能行為保持正確。
  4. 可選：擷取成功變更的差異範例並加入指令檔，以強化未來自動化。

清理資源

移除或整合任何臨時指令檔，以避免未來升級時轉換重疊。

相關內容

  • 上次更新時間：