Windows Forms 框架遷移記錄

  • 81
  • 0
  • 2026-11-12

事情發生在一年半以前,受託將一個 Windows Forms 的系統框架從 .NET Framework 4.8 遷移到 .NET 8。這裡記錄當時的一些程序與做法。  

也許有人會問:「為什麼不直接用 AI 升級就好?」,老實說我也很想像現在用 Loop Engineering 讓 AI 代理直接搞定一切,但現實不允許,這大概有以下的原因:

  1. 當時 AI 還沒像現在這麼火紅,還沒發展出像現在如此瘋狂的 agents+skills 的作法。
  2. 作業環境並不在我自己的電腦上,而且企業這一端有嚴格的資訊安全規定,不可能整個專案拋進 AI 作業,頂多有些簡短的問題可以用自己的電腦一問一答。
  3. 專案的設定檔案 (csproj) 經過長久的摧殘以後,充滿著各式各樣混亂的內容。
  4. 這個系統牽涉到每日的交易額有點可怕,加上牽涉的專案有幾十個,萬一有個失誤我擔待不起。
釐清相依

由於這個系統包含了相當數量的專案以及外部函式庫相依,所以一開始的苦工是先找出各個專案的相依關係,以便建立未來遷移程序的更新順序,執行遷移步驟時由相依性最低的開始,這樣可以降低流程上的麻煩與風險。

project file 轉換為 SDK-Style

接著要修改 .csproj,在 .NET Core 時代 C# project file 使用一種新的形式 SDK-Style,因此需要轉換成這個格式,這邊我借助了一個工具 .NET Upgrade Assistant (微軟現在建議用 GitHub Copilot upgrade)。謹慎起見是由相依性最低的專案開始改寫,這個階段維持 .NET Framework 4.8,目標設定在只解決格式問題,這個階段除了遇到寫的很奇妙的建置前\建置後事件以外通常很順利。

加入 .NET 8

麻煩會從現在開始,畢竟  .NET Framework 4.8 和 .NET 8 雖然很像但是差異也是不少,因為有未知的風險,採取穩步攻堅的戰術,相同地從相依性最低的專案開始 (事實上也不可能從相依性最高的專案開始改),並且要讓  .NET Framework 4.8 和 .NET 8 並存一段時間 (我在改系統的時候,其他人也同時在這些專案上的其他分支作業),再加上版控的保護,至少還能有一個框架在系統轉換期間是確認可行的。

原來只有  .NET Framework 4.8 時,.csproj 的內容主要是這樣:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>    
    <OutputType>WinExe</OutputType>    
    <!-- 關鍵點:單數的 TargetFramework,值為 net48 -->
    <TargetFramework>net48</TargetFramework>  
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup>
</Project>

同時並用兩個框架,TargetFramework 標籤名會改成 TargetFrameworks:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>    
    <!-- 關鍵點:複數的 TargetFrameworks,並用分號隔開。net8.0 必須加上 -windows -->
    <TargetFrameworks>net48;net8.0-windows</TargetFrameworks>
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup> 
</Project>
不同目標框架的函式庫引用

這事情有時候會發生,所以需要在 .csproj 中加入條件,像在 .NET Framework 4.8 這些套件需外掛,而 8.0 卻內建的情況:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>    
    <!-- 關鍵點:複數的 TargetFrameworks,並用分號隔開。net8.0 必須加上 -windows -->
    <TargetFrameworks>net48;net8.0-windows</TargetFrameworks>
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup> 
  <ItemGroup Condition="'$(TargetFramework)' == 'net48'">
    <PackageReference Include="System.Text.Json" Version="8.0.5" />
    <PackageReference Include="System.Memory" Version="4.5.5" />
    <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" Version="8.0.0" />
  </ItemGroup>
</Project>

或是 .NET Framework 4.8 使用內建組件,但 .NET 8 要引用外部套件:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>    
    <!-- 關鍵點:複數的 TargetFrameworks,並用分號隔開。net8.0 必須加上 -windows -->
    <TargetFrameworks>net48;net8.0-windows</TargetFrameworks>
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup> 
  <ItemGroup Condition="'$(TargetFramework)' == 'net48'">
    <Reference Include="System.Configuration" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'net8.0-windows'">
    <PackageReference Include="System.Configuration.ConfigurationManager" Version="8.0.1" />
  </ItemGroup>
</Project>

引用兩個不同的套件很大機率引起額外的麻煩,例如命名空間不同、或是使用的類別跟方法名稱完全兩回事的狀況,例如麻煩很多的 Entity Framework:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>    
    <!-- 關鍵點:複數的 TargetFrameworks,並用分號隔開。net8.0 必須加上 -windows -->
    <TargetFrameworks>net48;net8.0-windows</TargetFrameworks>
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup> 
  <ItemGroup Condition="'$(TargetFramework)' == 'net48'">
    <PackageReference Include="EntityFramework" Version="6.4.4" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'net8.0-windows'">
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.11" />
  </ItemGroup>
</Project>

在程式碼的部分可能就會多出不少條件式編譯的寫法:

#if NET48
using System.Data.Entity;
#else
using Microsoft.EntityFrameworkCore;
#endif
DLL Import 的問題

過去 .NET Framework 時代 CLR 對 Win32 API 有很多歷史包袱與容錯處理,但 .NET Core  之後重新實作了 Native Library Loading 機制,Microsoft 移除了許多歷史相容邏輯,舉個例子來說,在過去很多機會看到這樣的程式碼:

[DllImport("kernel32")]
public static extern void CopyMemory(...);

這有點誤打誤撞的意味,因為在 kernel32 中其實並沒有名為 CopyMemory 的函式,但在過去會因為相容性機制最後會指向 RtlMoveMemory,但這段程式碼在 .NET 8 則會出現 EntryPointNotFoundException,因此必須指明  EntryPoint:

[DllImport("kernel32", EntryPoint = "RtlMoveMemory")]
public static extern void CopyMemory(...);
CA1416 警告

這是一個平台相容性警告,在 .NET Framework 時代,所有的玩意都只支援 Windows,但 .NET Core 時代是跨平台的,因此 Windows Forms 或 WPF 專案很容易發出這樣的警告。這個解決也不難,使用條件式編譯在 .NET 8 加上個 Assembly Attribute   [assembly: System.Runtime.Versioning.SupportedOSPlatform("windows")] 就可以有效解決,當然也有其他方式。

資料庫連線字串

專案由 .NET Framework 遷移至 .NET 時,若同時將 SQL Server 驅動程式由 System.Data.SqlClient 改為 Microsoft.Data.SqlClient,請依實際使用的 Microsoft.Data.SqlClient 版本確認連線字串設定。若該版本不支援或不建議使用 Network Library=DBMSSOCN,可移除這個參數,並在 Data Source 的伺服器位址前加上 tcp:,以明確指定透過 TCP/IP 連線。


例如:

"Data Source=192.168.1.100,1433;Network Library=DBMSSOCN;Initial Catalog=MyDb;Integrated Security=true;"

要換成

"Data Source=tcp:192.168.1.100,1433;Initial Catalog=MyDb;Integrated Security=true;"
String.GetHashCode()

在 .NET Core 2.1 以後的 String.GetHashCode() 具有隨機性,簡單說來就是在不同的 Process 中,String.GetHashCode() 可能會得到不同的結果,如果整個系統有兩個 Process 通訊又牽涉到字串的雜湊碼出現問題的機率很大,這要特別注意。

AppDomain.CurrentDomain.DefineDynamicAssembly

這應該比較不容易遇到,但剛好程式碼中有動態產生組件的部分,而 AppDomain.CurrentDomain.DefineDynamicAssembly 在 .NET 8 是不存在的,要改用 AssemblyBuilder.DefineDynamicAssembly。

Windows Forms 版面配置問題

.NET 8 的 Windows Forms 有兩個和版面佈局相關的設定改變:

  1. DPI 感知模式 : .NET Framework 4.8 預設為 Unware,但 .NET 8 是 SystemAware
  2. 字型:兩個框架的預設字型也不一樣,這個有點麻煩的是 .NET 4.8 在不同作業系統可能會不同字型

大致上是這樣解決問題的:

#if NET48
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);
#else
            Application.SetHighDpiMode(HighDpiMode.DpiUnaware);
            Application.EnableVisualStyles();
            Application.SetCompatibleTextRenderingDefault(false);
            Application.SetDefaultFont(new Font("PMingLiU", 9F));
#endif

            Application.Run(new Form1());
        }

字型的部分,如果是在繁體中文的 Windows 下,預設是 ["PMingLiU", 9F],所以強制把 .NET 8 的預設字型改成一樣就可以了。特別說明很有可能還是會有一些對不齊的狀況就需要個別視窗表單調整了。