將 Windows Forms 應用程式升級為 .NET，並進行 GitHub Copilot 現代化

本文將介紹如何使用 GitHub Copilot 現代化代理程式，將 Windows Forms 桌面應用程式升級為 .NET。代理會在你的編輯器中執行，分析專案，並推動三階段工作流程：評估、規劃與執行。

範例使用 Matching Game 範例，這是一個由主專案和類別函式庫組成的小型 .NET Framework Windows Forms 應用程式。

先決條件

Windows 作業系統。
Visual Studio 2026。
下載並擷取本文所使用的示範應用程式。
你目標版本的 .NET SDK。本文針對 .NET 10。
一個用於解決方案的 Git 倉庫。代理程式會提交進度，因此專案必須在原始碼控制之下。
已為 Visual Studio 啟用 GitHub Copilot 現代化功能。如需詳細資訊，請參閱安裝 GitHub Copilot Modernization。

Tip

開始之前，請務必先備份您的程式碼，例如存放在版本控制系統中，或保留一份副本。

開啟解決方案

Matching Game 專案的目標是 .NET Framework 4.5。當你打開解決方案時，Visual Studio 會提示你將專案重新定位到支援的 .NET Framework 版本。

在 Visual Studio 開啟 MatchingGame 解決方案。
Visual Studio 會顯示「目標框架未安裝」對話框。
選擇將目標更新為 .NET Framework 4.8（推薦），然後選擇繼續。
打開 Git 變更 視窗並提交重新定向變更。

Visual Basic 重要說明

GitHub Copilot現代化代理程式並未完全支援Visual Basic .NET專案。代理程式包含專門設計的護欄，確保 C# 專案能可靠升級，而這些護欄會干擾 VB 專案的分析與執行。如果你的解決方案包含 VB 專案，請改用以下選項之一：

GitHub Copilot（標準代理程式）：使用一般的 Copilot 代理程式（不使用現代化代理程式）以互動方式引導升級。
升級助理：一個專門支援 VB 的遷移工具。

Tip

如果你的解決方案同時包含 C# 和 VB 專案，你仍然可以使用現代化代理來處理 C# 專案。使用上述替代方案之一，分別升級 VB 專案。

如果你使用標準的 Copilot Agent 或手動升級，請遵循以下步驟：

如果專案針對不支援的 .NET Framework 版本，請先將其重新定位為 .NET Framework 4.8。 Visual Studio 在你開啟解決方案時會提示你這麼做，或者你可以在專案屬性中更改。
將任何過時的 NuGet 套件更新到最新的相容版本。
使用 Visual Studio 範本或 dotnet new winforms -lang vb。建立一個新的 VB Windows Forms 專案。該範本產生一個類似 SDK 的專案檔案與設定，這些設定已與 .NET Framework 有所不同。
把你的 .vb 原始檔案從舊專案資料夾複製到新的專案資料夾。
複製專案依賴的任何非程式碼檔案，如 app.config檔案 .settings 、圖片、圖示及其他嵌入資源。
打開舊的專案檔案（或 packages.config），記錄每個 NuGet 套件的引用。使用 NuGet 封裝管理員或 dotnet add package <name>，將這些相同的套件新增至新專案。
如果專案在解決方案中引用了其他專案，請在新專案中重新加入那些參考。
嘗試建立解決方案。先不要急著修正錯誤——建置輸出會給 Copilot 一份具體的問題清單。
先將目前的狀態提交到版本控制，這樣在 Copilot 進行變更前，你就有一個乾淨的基準點。
打開 GitHub Copilot Chat，請它解決剩餘的問題。例如：

此Visual Basic Windows Forms專案已從 .NET Framework 4.8 遷移至 .NET 10。專案檔案和原始碼檔案都已經到位，但解決方案無法編譯。檢視建置錯誤並修正 API 不相容性、缺少引用以及任何設定遷移問題。
檢視 Copilot 提出的變更，然後重建並測試專案。

啟動升級

Matching Game 解決方案包含 MatchingGame 應用程式與 MatchingGame.Logic 類別函式庫。代理程式會自行計算專案圖，所以從解決方案層級開始升級。

在 方案總管 中，右鍵點擊解決方案並選擇現代化。

GitHub Copilot Chat 視窗會開啟，並開始與現代化代理程式對話。
選擇具有強大推理能力與編碼能力的模型。
告訴經紀人你想怎麼做。例如：

把所有東西都升級到 .NET 10。

代理程式會回報程式碼庫的當前狀態及其計畫：
- 目標框架：表示代理將專案升級至 .NET 10。
- 流程模式：預設為自動。對於複雜的應用程式，請客服人員切換到引導模式。
- 來源控制：表示代理建立新的工作分支。
代理程式會將其工作結果寫入您儲存庫中的 .github/upgrades/scenarios/dotnet-version-upgrade/。如果該資料夾已經存在於先前嘗試中，客服會詢問是否繼續或重新開始。
告知代理程式start開始升級程序。

回顧評估

在評估階段，代理會檢視專案結構、相依性及程式碼模式，以找出需要改變的地方。它會將結果寫入 assessment.md.github/upgrades/scenarios/dotnet-version-upgrade/。

當 Copilot 完成評估後，檢視對話結果。通常會從類似以下內容開始：

Assessment Complete

I've analyzed the solution and created a full assessment — see .github/upgrades/scenarios/dotnet-version-upgrade/assessment.md.

Solution summary:
• Target: net48 → net10.0
• Projects: 2
• MatchingGame.Logic (Class Library)
• MatchingGame (Windows Forms)
• Issues: 883 (673 mandatory, 210 potential)
• Affected Technologies: Windows Forms (666), GDI+ / System.Drawing (208), Legacy Configuration System (2)

Key concerns:
• Both projects are legacy-format .csproj files — need conversion to SDK-style
• MatchingGame.csproj has API incompatibilities (binary + source) and an incompatible NuGet package
• WinForms remains supported on .NET 10 (Windows-only TFM)
• No reported security vulnerabilities

評估明細

Copilot 會在 Visual Studio 編輯器中開啟該.github/upgrades/scenarios/dotnet-version-upgrade/assessment.md檔案。往下捲動至該 MatchingGame\MatchingGame.csproj 區塊，可以看到議題表：

科技問題百分比遷徙路徑

舊有配置系統 2 0.2% 舊有的基於 XML 的配置系統（app.config/web.config），已被 .NET Core 中更靈活的配置模型取代。舊系統是僵化且基於 XML 的。遷移至 Microsoft.Extensions.Configuration，搭配 JSON/環境變數；如有需要，可使用 System.Configuration.ConfigurationManager NuGet 套件作為過渡橋接方案。

GDI+ / System.Drawing 208 23.7% System.Drawing API 可用於 2D 圖形、影像與列印，可透過 NuGet 套件 System.Drawing.Common 取得。注意：由於 Windows 依賴，不建議用於伺服器場景;新程式碼可考慮使用跨平台替代方案如 SkiaSharp 或 ImageSharp。

Windows Forms 621 76.0% Windows Forms API 用於建立傳統 Forms 介面的 Windows 桌面應用程式，且可在 Windows 上以 .NET 格式取得。啟用 Windows Forms 支援：選項 1（建議）：將目標設為 net10.0-windows；選項 2：新增 <UseWindowsForms>true</UseWindowsForms>；選項 3（舊版）：使用 Microsoft.NET.Sdk.WindowsDesktop SDK。

科技	問題	百分比	遷徙路徑
舊有配置系統	2	0.2%	舊有的基於 XML 的配置系統（app.config/web.config），已被 .NET Core 中更靈活的配置模型取代。舊系統是僵化且基於 XML 的。遷移至 Microsoft.Extensions.Configuration，搭配 JSON/環境變數；如有需要，可使用 System.Configuration.ConfigurationManager NuGet 套件作為過渡橋接方案。
GDI+ / System.Drawing	208	23.7%	System.Drawing API 可用於 2D 圖形、影像與列印，可透過 NuGet 套件 System.Drawing.Common 取得。注意：由於 Windows 依賴，不建議用於伺服器場景;新程式碼可考慮使用跨平台替代方案如 SkiaSharp 或 ImageSharp。
Windows Forms	621	76.0%	Windows Forms API 用於建立傳統 Forms 介面的 Windows 桌面應用程式，且可在 Windows 上以 .NET 格式取得。啟用 Windows Forms 支援：選項 1（建議）：將目標設為 net10.0-windows；選項 2：新增 `<UseWindowsForms>true</UseWindowsForms>`；選項 3（舊版）：使用 Microsoft.NET.Sdk.WindowsDesktop SDK。

這些問題大多不是真正的問題。請參考 GDI+ 列的「遷移路徑」欄位，列出 208 個問題。評估會標記這些 API，因為它們在 .NET Framework 中有，但在 .NET 中卻沒有。專欄說明了修復方法：新增 System.Drawing.Common NuGet 套件以還原 API。

Windows Forms 列中列出 621 API 問題的原因相同。 Windows Forms API 在 .NET 中預設無法使用，但只要將目標設為 Windows 專屬框架（例如 net10.0-windows），並在專案檔中設定 <UseWindowsForms>true</UseWindowsForms>，即可恢復使用。 選項三則建議了一個錯誤的選項。舊版 .NET 需要 Windows Forms 專案明確以 Microsoft.NET.Sdk.WindowsDesktop SDK 為目標，但現在只要設定 <UseWindowsForms>true</UseWindowsForms>，就會自動參考該 SDK。

Tip

想了解更多選項，請向 Copilot 詢問更多資訊與背景。

檢視升級選項

評估後，代理程式會提出升級策略決定，並將其儲存至 upgrade-options.md 中的 .github/upgrades/scenarios/dotnet-version-upgrade/。對於配對遊戲樣本，代理人會選擇以下選項：

層面	決策	Reason
升級策略	從底而上。	代理會先升級 MatchingGame.Logic ，因為 MatchingGame 依賴它，然後再驗證每個層級，然後才繼續。
專案方法	就位。	兩個專案會一起遷移，因為沒有其他 .NET Framework 專案會消耗它們。
不支援套件	線上解決。	評估結果顯示僅有少數不相容的套件，因此代理程式會在執行過程中一邊尋找替代套件。
不支援的 API 處理	直接修正。	大多數 Windows Forms 和 GDI+ API 對 .NET 的變更都是機械式的，不需要另外的規劃流程。
Windows 原生 API	Windows 相容性套件。	這個應用程式大量使用 Windows Forms 和 GDI+，且本質上僅限 Windows。
可為 Null 的參考類型	維持停用狀態。	代理將啟用 nullable 視為遷移後的獨立作業。

代理人也會指出需要你注意的風險。對於 Matching Game 範例，代理程式會標記套件MetroFramework，因為它們只支援 .NET 框架。很可能的結果是移除MetroFramework並退回標準的 Windows Forms 控制項，這會改變應用程式的視覺風格。

檢視建議選項，並告訴經紀人你想改變什麼。例如，告訴代理啟用可空的參考類型，或先暫停討論 MetroFramework 替換。完成後，回覆 confirm 以鎖定選擇，然後進入規劃階段。

檢視計畫

在規劃階段，代理人會將評估結果及您確認的選項轉化為詳細的規格。它會將結果寫入 plan.md 並建立 scenario-instructions.md 一個檔案，儲存偏好設定、決策及升級的自訂指示。

Important

若流程模式為自動，代理人員會立即執行計畫，無需時間審查。

計畫涵蓋跨專案的升級順序、每個專案的目標框架名稱（net10.0-windows針對 Windows Forms 專案）、套件更新路徑，以及評估發現的破壞性變更的風險緩解措施。

檢視並調整計畫：

開啟 plan.md 於 .github/upgrades/scenarios/dotnet-version-upgrade/。
檢視升級策略與相依性更新。
根據需要，修改計畫以調整步驟或補充背景。
告訴代理程式移至執行階段。

注意事項

計畫取決於專案間的相互依賴關係。如果你修改計畫，導致升級路徑無法完成，升級就不會成功。例如，如果 MatchingGame 依賴 MatchingGame.Logic ，而你從計畫中移除 MatchingGame.Logic ，升級 MatchingGame 可能會失敗。

執行升級

在執行階段，代理將計畫拆解為具有驗證標準的序列性、具體任務。代理會將任務清單寫入 .github/upgrades/scenarios/dotnet-version-upgrade/tasks.md 並追蹤該檔案的整體進度。對於每個任務，代理會在 .github/upgrades/scenarios/dotnet-version-upgrade/tasks/ 下建立一個資料夾，其中包含一個描述該任務的 Markdown 檔案，以及一個回報該任務進度的 Markdown 檔案。

以 Matching Game 範例為例，任務清單通常包括先升級 MatchingGame.Logic ，接著 是 MatchingGame，還原套件、建置解決方案，以及提交變更。

要進行升級：

告訴客服開始升級。
透過查看 tasks.md 來追蹤進度，並留意代理更新任務狀態。打開下面的 tasks/ 每個任務資料夾，裡面有任務描述和詳細進度報告。
如果客服遇到無法解決的問題，就提供所需的協助。例如，代理可能會要求你在兩個替代 API 中做選擇，或確認是否保留已棄用的套件。
根據你的回應，代理人會根據剩餘任務調整策略並繼續執行。

代理會依照你在初始化前設定的 Git 策略提交變更：每個任務、每個任務群組，或在最後階段提交。

Visual Basic 專案筆記

.NET Framework 上的 Visual Basic Windows Forms 專案通常會使用 System.Configuration 設定檔和 My 副檔名，例如 My.Computer 和 My.User。這些My副檔名在 .NET 中被移除。代理程式會在評估期間標記這些模式，並在執行期間提出修正方案，但你可能需要在引導式執行期間確認個別變更。

如果代理程式遷移了專案但沒有編譯，請確認專案檔案是針對 Windows 並參考 Windows Forms。該 <PropertyGroup> 元素應該看起來像以下片段：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0-windows</TargetFramework>
    <UseWindowsForms>true</UseWindowsForms>
    <OutputType>WinExe</OutputType>
    <MyType>WindowsForms</MyType>

    <!-- Other settings removed for brevity. -->
  </PropertyGroup>
</Project>

確認升級

升級完成後，客服會在聊天回覆中建議下一步。使用「產生變更報告。」提示代理程式產生一份全面的變更報告。

檢視最終任務狀態 tasks.md ，確認每個步驟都已完成。

為了驗證升級：

建立解決方案並修正任何編譯錯誤。
啟動應用程式確認表單載入並正常運作。

Windows Forms 的預設字型在 .NET Framework 和 .NET 之間有變動，所以請檢查表單和自訂控制項是否有排版差異。
執行解決方案中的單元測試並修正失敗。
確認更新後的 NuGet 套件是否與你的應用程式相容。
請徹底測試應用程式，確認升級是否成功。

Tip

如果專案無法執行且無法附加除錯器，試著重啟 Visual Studio。將專案檔案從 .NET Framework 遷移到 .NET 可能會讓 Windows Forms 設計器感到困惑，除非重啟。

Windows Forms 配對遊戲範例現已升級至 .NET 10。

升級後的經驗

如果您已將應用程式從 .NET Framework 移植到 .NET，請參閱從 .NET Framework 升級到 .NET 後進行現代化，了解如何採用較新的模式，例如 appsettings.json組態、相依性插入或雲端服務。採用這些模式與升級到 .NET 是分開的，且不是完成升級的必要條件。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-06-26