简介一份面向.NET开发者的迁移实战文档详细讲解如何借助微软官方.NET升级助手将.NET Framework项目平稳升级到.NET 6。内容覆盖环境准备、.NET Portability Analyzer兼容性分析、升级助手安装与更新、项目升级指令及后续调整并针对WPF项目给出net6.0-windows目标框架建议可帮助开发者在迁移前预判风险、迁移中按步骤操作、迁移后快速处理依赖与配置变化。资源仅含1个doc文档体积691KB便携易用适合有.NET Framework维护经验并计划迁移至.NET 6的开发者参考。已有388人学习下载文档内容结构清晰包含命令示例与变更项说明是一份可快速上手的升级参考。1. .NET 升级助手不是一键迁移.NET Framework 到 .NET 6 的真实成本第一次用 .NET 升级助手升级一个 .NET Framework 4.7.2 的 WPF 工程时我以为跑完一条命令就能直接编译结果工具停在交互菜单上每一步都等我确认。这个“助手”没有想象中那么智能但比手动迁移可靠得多。它把微软官方迁移手册里的步骤变成了可执行的任务列表还顺手帮你备份、改 csproj、迁移 packages.config。.NET Framework 4.0 的服务支持早已结束但大量 C# 存量工程还压在老框架上靠人肉改工程文件既慢又容易漏掉 API 兼容性细节。这类工具适合两种人一种是守着老框架、想用 .NET 6 的 LTS 能力又不敢重写的团队另一种是接手存量项目、需要在一个迭代内给出可运行结果的开发者。下面把从环境准备到升级收尾的完整流程拆开讲包括工具不会告诉你的坑。2. 环境准备与版本核对VS2022、.NET 6 SDK 与命令行验证2.1 为什么 VS2022 与 .NET 6 SDK 要同时在场升级助手本身是一个 .NET 全局工具运行它需要 .NET SDK升级完成后用 VS2022 打开项目则需要对应的 Windows 桌面工作负载来编译和调试 WPF/WinForms。只装 .NET Runtime 不够dotnet tool 会直接拒绝运行。VS2022 17.0 及以上版本在安装时会默认勾选 .NET 6 运行时但如果安装时没有选择“.NET 桌面开发”工作负载即使 SDK 装好了新建项目页里也看不到 WPF 模板打开旧工程则会提示“无法加载项目”。我一般在开发机上先装 VS2022 Community单独下载 .NET 6 SDK 装到 CI 机器。对于需要固定版本的构建服务器用 dotnet-install 脚本指定 SDK 版本比直接依赖 VS 自带的 SDK 更可控——VS 的小版本更新会悄悄替换 SDKCI 上一旦出现“本地能编、服务器不能编”基本都是这个原因。2.2 命令行验证 SDK 与运行时环境准备阶段最容易忽略的是“装完了但没验证”。打开 PowerShell 或 CMD依次执行下面三条命令dotnet --info dotnet --list-sdks dotnet --list-runtimes第一条输出整体环境信息包括 SDK 版本、运行时版本和操作系统标识第二条只看机器上装了哪些 SDK第三条看运行时。对于 WPF 项目dotnet --list-runtimes里应当出现Microsoft.WindowsDesktop.App 6.x这就是桌面应用运行时的条目。如果只有 ASP.NET Core Runtime 而没有 WindowsDesktop.App升级后能编译但一运行就报“找不到运行时”。命令行现象含义处理--list-sdks为空SDK 未安装安装 VS2022 桌面工作负载或单独安装 .NET 6 SDK只有 7.0/8.0没有 6.x版本不匹配补装 6.0.x SDK升级助手按目标框架解析依赖有 SDK 但--list-runtimes无 WindowsDesktop.App桌面运行时缺失单独安装 Windows Desktop Runtime 6.x--info显示 architecture 与系统不一致SDK 位数不对卸载后安装对应 x86/x64 版本2.3 新建项目验证模板SDK 装好之后打开 VS2022新建项目搜索 WPF确认模板列表里有“.NET 6.0”选项。这里有个常见的视觉误区模板列表明明显示了“WPF 应用程序 (.NET Framework)”和“.NET 6.0”两个入口如果只看到前者说明 VS 安装时没勾选 .NET 桌面开发。回到 VS Installer 修改勾选“.NET 桌面开发”工作负载再重启一次 VS。3. 用 .NET Portability Analyzer 先做依赖体检3.1 它到底在分析什么升级前先做依赖体检是避免“升级五分钟排错两星期”的关键。.NET Portability Analyzer 不执行你的程序而是对程序集做静态扫描把每个 API 调用与目标框架的 API 面比对计算出一个“可移植性百分比”。这个数值本身参考意义有限真正有价值的是第二个 Sheet 里列出的“不支持的 API 清单”。常见的误用是只看百分比90% 就以为可以放心升级70% 就以为要重写。实际上 Portability Analyzer 对某些 API 的判定偏保守比如System.Web下的很多类型会被标红但项目里可能只是用了一个不相关的常量反过来某些 API 在报告里显示“支持”实际运行时行为却完全不同。所以这个工具的价值是列清单不是给结论。3.2 安装与配置在 VS2022 中打开“扩展”菜单选择“管理扩展”搜索“Portability Analyzer”下载安装后重启 VS。这个扩展从 VS 2015 时代就有了安装路径一直没变。原文档里提到该工具仅支持 .NET 5 以下版本这是指工具的目标平台列表里没有直接列出 .NET 6。实际操作中我一般把目标平台选成 .NET 5 作为评估基准因为 .NET 6 是 .NET 5 的直接后继API 面高度一致分析结果足以暴露绝大多数兼容性问题。配置步骤在解决方案上右键选择“Portability Analyzer Settings”勾选要评估的目标平台通常选.NET 5和.NET Core 3.1确定后在解决方案右键菜单里选择“Analyze Assembly Portability”等待分析完成结果窗口会自动弹出3.3 结果怎么读分析结果打开后是表格形式大致长这样Target Platform: (.NET 5) Assembly BCUs Supported Not Supported % Supported MyApp.exe 1243 1120 123 90.8% MyLib.dll 2345 2198 147 93.7%第一页是每个程序集的可移植性汇总第二页才是关键它按 API 列出“在目标平台上不受支持”的具体成员包括命名空间、类型、成员名和所在程序集。看到第二页时重点关注三类自己业务代码直接调用的、通过反射调用的、通过 NuGet 包间接调用的。反射调用尤其隐蔽静态分析能扫到字符串里的类型名但扫不到动态拼接的。拿到清单后先不要急着改代码。把不支持的 API 按“替换成本”排序有官方替代方案的优先处理只在极少数代码路径里出现的可以加条件编译被大量业务代码依赖的要评估是改代码还是放弃升级。3.4 高发不兼容点从 .NET Framework 迁移到 .NET 6最常被标记的 API 集中在几个区域AppDomain的CreateDomain和ExecuteAssembly、CAS 相关的SecurityPermission、System.Runtime.Remoting全套、以及System.Drawing的某些 GDI 封装。这些 API 在 .NET 6 里不是删掉就是行为变了。如果你的分析报告里出现这些且数量超过 50 处升级前要专门排一个重构任务不要指望升级助手处理——升级助手只在少数场景下做 API 层面的自动替换大多数情况只负责改项目文件和包引用。4. 升级助手安装与 analyze 模式先让工具自己讲一遍计划4.1 dotnet tool 安装与更新升级助手以 .NET 全局工具的形式分发安装命令是dotnet tool install -g upgrade-assistant dotnet tool update -g upgrade-assistant第一条命令里的dotnet前缀不能省原文档里写成tool install -g upgrade-assistant会让命令行直接报“找不到命令”。-g表示全局安装工具会被放到用户目录下的.dotnet/tools路径任何目录下都能直接调用。第二条命令用于更新微软每过一段时间会修正升级助手对某些包版本的识别逻辑升级前先更新一次是值得的。选型上官方把升级助手做成命令行工具而不是 VS 扩展是有意为之命令行工具可以进 CI 脚本在流水线里对多个项目批量执行VS 扩展只能服务于开发机。对于二三十个项目的解决方案手动在 VS 里点一遍不现实命令行方式可以把升级过程固化成脚本。4.2 analyze 模式与 TFM 推断analyze 模式不会修改任何文件只输出一份“升级计划”。命令如下upgrade-assistant analyze .\MyApp.sln upgrade-assistant analyze .\MyApp.csproj --target-framework net6.0-windows第一条针对整个解决方案逐个分析项目第二条只分析指定项目并通过--target-framework参数显式指定目标框架。不加参数时工具会根据项目类型推断 TFMWPF 或 WinForms 项目会给出net6.0-windows普通类库和控制台程序可能给出net6.0。这个推断是工具最有价值的一个环节它不只是看项目文件还会扫描代码里引用了哪些 Windows 专属 API。如果你已经确定目标框架直接加参数更稳妥。工具输出的前面几行是它自己的内部日志夹杂大量 MSBuild 诊断信息不要逐行看。重点找两处一是Target framework那行确认是net6.0-windows而不是net6.0二是Warnings和Errors区域如果有红色输出先处理再进入 upgrade 阶段。4.3 分析输出中的关键信号输出片段含义要做什么Target framework: net6.0-windows工具建议使用带 Windows 后缀的 TFM保持默认不要改成纯net6.0Package ... is not compatible某个 NuGet 包没有 .NET 6 兼容版本在 upgrade 阶段检查是否有替代版本API ... is not supported项目中存在不兼容 API 调用对照 Portability Analyzer 报告处理No issues found分析通过可以直接进入 upgrade 阶段注意analyze 模式输出的“No issues found”不代表升级后一定能编译通过它只说明静态分析没发现问题。XAML 绑定、动态加载的程序集、启动时反射探测的类型都不在静态分析范围内。所以分析结果干净仍然要按第 5、6 章的流程走完整套验证。5. upgrade 命令实操packages.config 迁移与交互式步骤选择5.1 执行升级并理解交互菜单分析通过后执行真正的升级命令upgrade-assistant upgrade .\MyApp.csproj工具会先创建备份默认放在项目同级目录下的.upgrade-assistant/backup里然后开始执行步骤列表。每完成一步控制台会显示一个菜单让你选择下一步动作菜单选项作用1. Apply next step应用当前这一步的变更2. Skip next step跳过当前步直接看下一步3. Skip remaining steps跳过剩余所有步骤提前退出4. Select different step跳转到指定编号的步骤5. Exit退出升级助手直接按 Enter 等同于选择第一项。第一次跑建议全部按 Enter让工具完成默认流程。中间如果某一步报错工具不会直接终止而是回到菜单让你决定跳过还是重试。这一步的设计容易让人误以为升级失败了实际只是停下来等你判断。5.2 csproj 的关键变化升级完成后打开 csproj 会看到一个缩减很多的 SDK 风格文件。WPF 项目升级后的典型形态如下Project SdkMicrosoft.NET.Sdk PropertyGroup OutputTypeWinExe/OutputType TargetFrameworknet6.0-windows/TargetFramework UseWPFtrue/UseWPF UseWindowsFormsfalse/UseWindowsForms Platformsall/Platforms /PropertyGroup /ProjectOutputType保持WinExe表示这是一个窗口程序UseWPF为true启用 WPF 的 XAML 编译支持UseWindowsForms为false如果你的项目同时依赖 WinForms 控件这里会被设为truePlatforms从原来的x86/x64分离改为all由运行时决定到底跑在哪种位数上。原来写在 packages.config 里的程序集引用不会出现在 csproj 里——SDK 风格项目默认通过框架引用拿到System.Net.Http等 DLL不需要逐个写Reference。5.3 packages.config 到 PackageReference 的迁移原文档里的项目依赖 Caliburn.Micro 3.2升级助手自动把它升到了 4.0。这个动作背后是 packages.config 到 PackageReference 的迁移旧格式里每个包的版本号写在 packages.config 里间接依赖靠 NuGet 在还原时自动补全PackageReference 则把版本号直接写进 csproj间接依赖的版本由依赖项自己声明。对比项packages.configPackageReference版本记录位置packages.config 独立文件csproj 的PackageReference节点间接依赖还原时自动写入 packages.config由包自身声明的依赖范围决定依赖覆盖手动改 packages.config直接在 csproj 中指定版本与 SDK 风格项目兼容不兼容原生支持升级助手识别到 Caliburn.Micro 3.2 没有 net6.0-windows 目标时会查找同名的兼容版本并自动更新。如果你的项目里有一个包始终找不到兼容版本工具会把它留在“未处理”列表里这时需要自己去 NuGet 官网确认替代包或者用条件编译注释掉相关代码。5.4 中途失败的处理升级助手把每个步骤的状态记录在.upgrade-assistant目录下中途失败后重新执行 upgrade 命令会从上次完成的位置继续而不是从头再来。常见的失败有两个来源一是 NuGet 包的依赖链解析超时特别是旧包源里有大量已删除版本时重试时加上--ignore-failed-sources可以缓解二是项目文件编码问题老工程如果用的是 GB2312 编码工具读取资源文件可能乱码。遇到第二种情况先把 csproj 和 XAML 文件用 VS 另存为 UTF-8再重新跑 upgrade。6. 升级收尾AssemblyInfo.cs 清理与 net6.0-windows 运行验证6.1 AssemblyInfo.cs 与 SDK 风格项目的冲突升级后最常见的编译错误是CS0579: Duplicate System.Reflection.AssemblyVersionAttribute attribute。原因在于 SDK 风格项目会在编译时自动生成AssemblyInfo.cs里面包含AssemblyVersion、AssemblyTitle、AssemblyProduct等特性而老项目里的 AssemblyInfo.cs 还保留着同样的内容两份叠加就冲突了。AssemblyInfo.cs 中的项SDK 风格是否自动生成建议AssemblyTitle是删除AssemblyProduct是删除AssemblyVersion是由 csproj 的Version控制删除在 csproj 中配置VersionComVisible否保留Guid否保留原文档提到“程序集版本在 .NET 6 中应该在项目属性里设置”指的就是 csproj 的Version属性。清除重复项后可以用 C# 反射验证版本号是否按预期输出using System.Reflection; var asm Assembly.GetExecutingAssembly(); var ver asm.GetName().Version; Console.WriteLine(ver);这段代码读取当前程序集版本。清理前输出的是 AssemblyInfo.cs 里的硬编码值清理后输出的是 csproj 中Version属性映射过来的版本。如果 csproj 没写Version默认输出1.0.0.0。6.2 编译运行与性能感知dotnet build .\MyApp.csproj -c Release dotnet run --project .\MyApp.csprojbuild只做编译run会先 build 再启动程序。首次 build 比后续慢因为要还原依赖并生成 WPF 的临时 XAML 编译产物。启动后重点看两件事启动耗时和内存占用。从 .NET Framework 迁到 .NET 6绝大多数 WPF 项目的启动速度有明显提升但如果你在App.xaml.cs的构造函数里做了大量同步初始化提升幅度会被吃掉这时优先处理启动路径上的耗时逻辑。6.3 开启 API 分析器做最后审核升级完成、能跑起来事情还没结束。我每迁完一个项目都会在 csproj 里加上下面两个属性触发一次全量 API 审核PropertyGroup AnalysisLevellatest/AnalysisLevel EnableNETAnalyzerstrue/EnableNETAnalyzers /PropertyGroupAnalysisLevel告诉编译器使用最新一套分析规则集EnableNETAnalyzers显式启用内置分析器。加了之后重新编译会看到一批此前被忽略的警告——比如在异步代码里同步阻塞、用HttpClient时没有释放、事件订阅没有退订。这些不是升级引入的问题是被旧框架放过的问题。把警告逐条看过能改的顺手改掉不能改的加#pragma warning disable并写明原因。升级不只在换运行时把分析器打开才算真正接入了 .NET 6 的开发范式。本次示例工程整理在网盘pan.baidu.com/s/1pCdAdAJ-XVG8onsZ9OCYdQ提取码 0000升级完成后可以直接对照 csproj 和 AssemblyInfo.cs 的差异卡住的时候拿出来比一比。本文还有配套的精品资源点击获取