一个 2015 年上线的设备管理程序,.NET Framework 4.8 加 WinForms,客户还在用,每年还要加两三个功能。界面里嵌着一个 WebBrowser 控件显示报表,最近客户升级了 Windows,页面开始渲染错乱,按钮位置全偏。团队想顺手升到 .NET 8,结果第一步就卡住:有个第三方硬件库只有 .NET Framework 版本,厂商说新版本要重新买授权。硬着头皮升上去之后,注册表读不到、COM 组件报「类未注册」、配置文件里一半的值是空的。
这类项目的困境不是「技术旧」,是「动一处牵全身」。它没有测试、没有文档,知道原委的人可能已经离职,但它承载着真实业务,停一天就是损失。迁移的目标不是把它变成教科书里的新项目,而是让它能在新运行时上继续交付,同时把最痛的地方一点点拆开。
这篇按「先判断该不该迁、再怎么迁、迁完怎么验、出问题怎么退」讲。重点是第三方依赖、配置与注册表、WebBrowser、高 DPI 这些工具不会替你做的决定。版本按 .NET Framework 4.8 升 .NET 8 讲。本机只用 dotnet-install.ps1 验证到 SDK 8.0.427,跑了 dotnet --version、新建 .NET 8 工程和发布;4.8 老工程迁移、升级工具的实际选项没有跑,本机也没有 4.8 工程,这部分仍未验证。
现场:能跑、够用、再重构
先把「升级」和「重写」分开。升级是保留界面和业务,把运行时、项目格式、依赖换掉;重写是连交互和信息结构一起重做。老项目最常见的错误,是把这两件事捆在一起:一边换运行时,一边换 UI 框架,一边重构分层,最后哪个问题都定位不到。
.NET Framework 4.8 跟着 Windows 走,短期不会消失,很多工业现场也还在用。所以「必须升级」不是默认答案。真正值得升级的信号通常是:关键第三方库只出新版本、安全扫描不允许旧运行时、新系统上出现无法绕过的兼容问题、团队已经没人愿意维护旧工具链。反过来,如果程序十年没改、只在一台内网机器上跑、升级会影响生产,留在 4.8 并做好隔离和备份,是更负责的选择。
决定要迁之后,可以先把项目转成 SDK 风格、目标框架仍留 net48,构建通过后再单独换目标框架。每次只动一个变量,出问题能立刻定位。
迁移不是重写:两种做法的代价
就地迁移
保留 WinForms 界面和事件处理,把项目文件、目标框架、依赖换到新版本。改动集中在工程和兼容层,用户几乎看不出区别,回归测试的范围相对可控。
代价是历史包袱原样保留:上帝类、复制粘贴的代码、写死在界面里的业务规则都还在。它解决的是「还能不能跑」,不是「好不好维护」。
重写界面
借迁移的机会换成 WPF、WebView2 或新的交互结构,把逻辑从控件里抽出来。长期收益大,能顺带解决高 DPI、老旧控件和界面扩展性问题。
代价是工期和风险完全不是一个量级。需求文档缺失时,重写等于边猜边做;业务方还会拿旧界面的每个像素来比对。多数老项目没有这个预算。
现实里的做法通常是「先就地迁移,再局部重写」。先把运行时换掉,让程序在新机器上稳定跑一个版本;然后把最痛的一两个界面(比如那个 IE 渲染的报表页)单独换成新方案。每步都能独立发布、独立回滚,才不会出现「升了三个月,一次都没上线」的局面。
场景走查:从 4.8 到 .NET 8
需求:把 LegacyApp 这个 WinForms 项目迁到 .NET 8,先保证能编译、能启动、能完成「登录、查询、导出」三条主流程,再谈其他。开始前先建分支、打标签、备份数据库和安装包,确保随时能回到升级前的状态。
第一步安装升级工具。它能把旧项目转成 SDK 风格、改目标框架、给出一部分 API 替换建议:
dotnet tool install -g upgrade-assistant
upgrade-assistant upgrade .\LegacyApp.csproj
预期是交互式地列出可执行的步骤,询问目标框架,最后改写项目文件并生成备份。跑完不要直接提交,先看它改了什么:项目文件是否变成 SDK 风格、TargetFramework 是否落在 net8.0-windows、packages.config 有没有转成 PackageReference。工具给出的「需要人工处理」清单,才是真正的工作量。
SDK 风格的 WinForms 项目文件大致是这样,关键是 -windows 后缀和 UseWindowsForms:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net8.0-windows</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>
<Nullable>enable</Nullable>
</PropertyGroup>
</Project>
然后编译:
dotnet build -c Release
预期不会一次通过。常见错误有三类:引用了已移除的 API、第三方程序集仍指向 .NET Framework、残留的 packages.config 或重复的程序集属性。逐个处理,每修一类提交一次。
能编译之后运行:
dotnet run -c Release
预期是主窗口能打开,但「能打开」不等于「迁移完成」。接下来按登录、查询、导出三条主流程走一遍,重点观察配置文件是否读到、数据库连接是否正常、COM 控件是否加载、导出的文件格式有没有变化。这个阶段发现的问题,大多不是编译错误,而是运行时行为差异。
配置、注册表、COM、WCF 与第三方库
配置是第一大坑。旧的 App.config 在 .NET 8 里不是自动生效的:ConfigurationManager 还能用,但要额外引用 System.Configuration.ConfigurationManager 包,而且 Settings.settings 那套用户级设置的语义并不完整。更常见的做法是迁到 appsettings.json 加 Microsoft.Extensions.Configuration:
var config = new ConfigurationBuilder()
.SetBasePath(AppContext.BaseDirectory)
.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
.Build();
var connectionString = config.GetConnectionString("Main");
迁移时要注意三件事:连接字符串里的敏感信息不要原样搬进明文 JSON;旧配置的键名和默认值要逐条对照,缺一个默认值就可能让程序在客户现场走另一条分支;配置文件要随安装包发布,且放在只读的安装目录,用户可改的部分另存到 %LocalAppData%。不要假设「文件存在」或「键一定存在」,老项目的配置文件经常被现场手工改过。
注册表要分清用途。读 HKCU 下的用户设置通常没有权限问题;写 HKLM 需要管理员,应该由安装器完成,而不是程序每次启动都写。.NET 8 仍然支持 Microsoft.Win32.Registry,但 32 位和 64 位进程看到的注册表视图不同,老项目如果原来编译成 x86,迁到 AnyCPU 后默认跑 64 位,可能读不到原来写在 WOW6432Node 下的键。要么显式指定 RegistryView,要么在安装器里两边都写,别靠猜。
COM 互操作能继续用,但条件更苛刻。进程位数必须和 COM 组件匹配,32 位组件在 64 位进程里会报「类未注册」,错误码通常是 0x80040154。可以给项目设 PlatformTarget 为 x86,或者改成注册免注册 COM(通过清单文件声明),后者更适合不想动客户机器的场景。Office 这类自动化要看对方版本和 PIA 的可用性,能晚绑定就晚绑定,少依赖具体版本的类型库。
WCF 要分客户端和服务端。作为客户端调用外部服务,.NET 8 可以通过对应的包支持,旧代理类通常要重新生成;如果项目自己宿主 WCF 服务端,新运行时没有原来的实现,只能用 CoreWCF 重写,或者把服务端留在 .NET Framework。这条要在评估第一天确认,别拖到后期。
第三方二进制依赖是最硬的墙。纯托管、只用了公共 API 的 .NET Framework 程序集,有时能在 .NET 8 上直接加载,但这是运气,不是保证;一旦碰到已移除的 API,运行时才报错。带原生 dll 的库还要看位数和系统依赖。处理顺序是:先查厂商有没有新版本,再查有没有社区替代,最后才考虑自己包一层兼容层。厂商明确不升级、授权又换不了时,这个模块就应该留在旧进程里,通过进程间通信和新程序配合,而不是硬塞进新运行时。
WebBrowser 到 WebView2,点到为止
WebBrowser 控件在 .NET 8 的 WinForms 里仍然存在,所以能编译、能显示,但它底层还是 IE 的渲染引擎。IE 桌面应用早已停止支持,现代页面用的 CSS、脚本特性它大多不支持,表现就是布局错乱、脚本报错、登录页打不开。客户升级 Windows 之后问题变多,不是你的代码改了,是宿主环境变了。
替代方案是 WebView2,底层是 Edge 的 Chromium 内核。WinForms 用 Microsoft.Web.WebView2.WinForms,WPF 用 Microsoft.Web.WebView2.Wpf,初始化是异步的,API 和旧控件完全不同,不能把类型名换掉就完事。还有一个部署前提:目标机器要有 WebView2 Runtime,通常由安装器负责安装或检测,漏了就是「程序能开、网页区域空白」。
迁移时先确认页面归谁维护。如果是内部页面,能改就顺手把 IE-only 的写法去掉;如果是第三方系统,先在一台装好 WebView2 的机器上试跑,确认登录、打印、文件下载、弹窗这些边缘功能都正常。WebBrowser 时代常用的 ActiveX 控件、IE 专有接口,在 WebView2 里没有对应物,这部分要单独评估。具体怎么在 WinForms/WPF 里嵌 WebView2、怎么做双向通信,留给混合方案的文章展开,这里只需要记住:它不是换个控件,是换了一整套浏览器宿主。
高 DPI、字体与回归测试
迁移后界面「变丑」通常有两个原因。第一是默认字体变了:.NET Framework 的 WinForms 默认用 Microsoft Sans Serif 8.25 磅,.NET 6 之后默认换成 Segoe UI 9 磅,同样的坐标和自动缩放设置,控件就会变大、文字被截断、按钮超出窗口。可以在启动时用 Application.SetDefaultFont 固定回原来的字体,或者接受新字体并逐个界面调整布局。
第二是高 DPI 感知模式。旧项目可能在 app.manifest 里声明了系统级 DPI 感知,新模板默认的行为不一定相同;在 125%、150% 缩放下,AutoScaleMode 是 Font 还是 Dpi、窗体的 AutoScaleDimensions 是否匹配,都会影响布局。表现是控件重叠、留白过大、字体模糊。不要靠拖控件逐个修,先把缩放模式和默认字体统一,再看剩余问题。
回归测试要按「用户会怎么用」列清单,而不是按代码覆盖率。至少覆盖:启动与登录、每个主界面的增删改查、导入导出与打印、数据库升级、配置保存、文件对话框、COM 与外设、网络异常、多显示器与不同缩放、非管理员账户、安装与卸载、覆盖升级。每一条都在旧版和新版上各跑一遍,记录差异。没有自动化测试的老项目,这份手工清单就是唯一的安全网。
双版本并行是降低风险的关键。给新版换一个产品名或安装标识,让它可以和旧版装在同一台机器上,数据用同一份副本而不是同一个文件;先让内部人员和一两个愿意配合的客户试用,收集问题,再逐步扩大范围。数据库结构如果在迁移中变了,要保证旧版仍能读,或者至少在回滚时能用备份恢复。不要做「升级时顺手把数据格式改成不可逆」这种事。
迁移顺序建议固定成:建分支并备份、转 SDK 风格但仍指向 net48、构建通过、换目标框架、修编译错误、跑主流程、处理配置与系统集成、换界面组件、调 DPI 与字体、更新安装包、双版本试点、全量发布。每一步都有提交和验证点,出问题就退回上一个能跑的状态。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 升级工具跑完能编译,一启动就崩 | 第三方程序集或原生 dll 仍按 .NET Framework 编译,运行时缺少 API 或位数不匹配 | 看异常堆栈里第一个 FileLoad 或 MissingMethod,逐个确认依赖的目标框架和位数 |
| 界面字体变大、按钮被截断 | .NET 默认字体从 Microsoft Sans Serif 8.25 变为 Segoe UI 9 | 查启动时的 SetDefaultFont 和窗体的 AutoScaleMode |
| 高缩放比例下控件重叠、文字模糊 | DPI 感知模式或 AutoScaleDimensions 与旧版不一致 | 对比新旧 app.manifest 的 DPI 声明,确认是按系统还是按显示器感知 |
| 配置读出来全是空值 | App.config 没有随新项目复制,或没有引用 ConfigurationManager 包 | 看输出目录里有没有配置文件,项目是否改成 PackageReference,键名是否与旧版一致 |
| WebBrowser 里页面错乱、脚本报错 | 控件仍用 IE 内核,现代页面特性不支持 | 确认是否已换 WebView2,目标机器是否装了 WebView2 Runtime |
| 调用 COM 报「类未注册」 | COM 组件没装,或 32 位组件被 64 位进程加载 | 查注册表里的 CLSID,确认组件位数和进程位数是否一致 |
| WCF 服务端启动失败 | .NET 8 不提供原来的 WCF 服务端托管 | 确认项目是 WCF 客户端还是服务端;服务端考虑 CoreWCF 或留在 4.8 |
| 升级后写注册表失败 | 程序试图写 HKLM,但没有管理员权限,或读错 32/64 位视图 | 看写入位置和进程位数,把机器级写入挪到安装器,读取时显式指定 RegistryView |
边界与代价
第一,有些项目不该迁。只在固定几台内网机器上运行、硬件和驱动绑定很深的工业软件,升级带来的收益可能完全抵不过现场风险。留在 .NET Framework 4.8、锁定系统版本、做好备份和隔离,是合理选择。迁移不是技术先进性的证明,是一次有成本的风险交换。
第二,升级工具只解决工程文件。目标框架、项目格式、部分 API 可以自动改,但设计器生成的代码、资源文件、第三方二进制、COM、WCF 服务端、安装器脚本,仍然要人逐项处理。把它当成「一键升级」是工期估算失真的起点。
第三,第三方依赖可能一票否决。厂商不提供新版本、授权不能转移、原生库只支持 32 位,这些都不是代码能绕过的。遇到这种模块,要么留在旧进程里通过进程间通信协作,要么接受整个项目不迁。越早做依赖清单,越不会在最后一周发现死路。
第四,界面差异会变成验收争议。字体、间距、DPI、控件的默认行为都可能和旧版不同,业务方会说「和原来不一样」。提前约定哪些差异可接受、哪些必须还原,比事后逐个解释省力。
第五,双版本并行有维护成本。两套产物、两套安装器、两份问题单,数据格式还要兼容。试点期不能太长,否则团队会被两套环境拖住。要提前定好退出条件:哪些问题必须修完才能全量,旧版支持到哪一天。
第六,迁移后的代码仍然是老代码。就地迁移不会自动带来可测试性、分层和文档,只是把运行环境续上了;要不要重构,按业务和维护成本单独决定,不要再捆进同一次发布。
小结与练习
老项目迁移的核心不是工具,是顺序和边界:先确认该不该迁,再把工程和运行时换掉,最后才谈界面和架构;每一步都保留回滚点,每一类依赖都提前确认。能把「能跑」和「重构」分开的团队,迁移成功率会高很多。
当天可以自己验证的练习:
- 给一个旧项目列依赖清单:NuGet 包、COM 组件、原生 dll、WCF 服务、第三方控件,逐项标注是否有 .NET 8 版本,找出可能一票否决的那一项。
- 复制一份项目,只把工程转成 SDK 风格、目标框架仍留
net48,确认能编译、能启动,再提交。体会「一次只动一个变量」。 - 把一个
App.config里的连接字符串迁到appsettings.json,用IConfiguration读出来,再故意删掉键,观察程序是否给出可理解的错误。 - 在 125% 和 150% 缩放下各截一张主界面图,和旧版对比,标出字体、间距、控件尺寸的差异,再决定是改默认字体还是改布局。
- 把新旧两版装在同一台机器上,用同一份数据库副本跑一遍登录、查询、导出,记录差异并设计一条回滚步骤。
这篇是本组「C# 桌面」的收尾。从选型、WinForms、WPF、MVVM、数据与线程,到打包交付和老项目迁移,一条线走下来,真正决定桌面程序能不能长期活着的,往往不是某个框架多先进,而是依赖是否可控、发布是否可重复、数据是否安全、升级是否可回滚。新项目按这些约束设计,老项目按这些约束续命,路会好走很多。