用途
winui-wpf-migration 是一个面向 WPF 应用的迁移技能,目标是把现有 WPF 代码迁移到 WinUI 3。资料以迁移流程的形式组织,覆盖源码审计、项目创建、命名空间替换、控件替换、线程调度替换、成像 API 替换、MVVM 框架替换、资源替换以及迁移后的验证。
主要能力
- 源码审计:提供一个 PowerShell 命令,递归检索非 obj 目录下的 *.cs 文件,查找 System.Windows. 的用法,并列出所使用的 WPF 控件、自定义 MVVM 框架、成像 API、线程模式与 Win32 互操作。
- 项目创建与命名空间对齐:使用 dotnet new winui-mvvm -n <AppName> 创建项目,随后在 .csproj 中设置 <RootNamespace> 与 WPF 命名空间一致,并更新 App.xaml、MainWindow.xaml 及其 code-behind 中的 x:Class,要求先构建验证再迁移代码。
- 命名空间替换对照:System.Windows → Microsoft.UI.Xaml、System.Windows.Controls → Microsoft.UI.Xaml.Controls、System.Windows.Media → Microsoft.UI.Xaml.Media、System.Windows.Input → Microsoft.UI.Xaml.Input、System.Windows.Data → Microsoft.UI.Xaml.Data、System.Windows.Threading.Dispatcher → Microsoft.UI.Dispatching.DispatcherQueue,PresentationCore / PresentationFramework 需整体移除。
- 控件替换对照:DataGrid → 带 Grid 列头的 ListView、WrapPanel → ItemsRepeater + UniformGridLayout、TabControl → TabView、StatusBar → 底部 Grid 行加 TextBlock、Menu / MenuItem → MenuBar / MenuBarItem / MenuFlyoutItem、ToolBar → CommandBar、自定义 Expander → 内置 Expander。
- 线程替换:Application.Current.Dispatcher.Invoke 改为 dispatcherQueue.TryEnqueue,通过 DispatcherQueue.GetForCurrentThread() 获取;WinUI 3 中不存在 Application.Current.Dispatcher。
- 成像替换:PresentationCore.dll 与 System.Windows.Media.Imaging 会导致 WinUI XAML 编译器崩溃,资料称这是架构性不兼容、无变通方案;需移除所有 System.Windows.Media.Imaging 引用,改用 Windows.Graphics.Imaging(WinRT)或 Microsoft.UI.Xaml.Media.Imaging.BitmapImage;不要添加 <UseWPF>true</UseWPF>;成像代码较重时应提前迁移。
- MVVM 框架替换:删除自定义 ObservableObject/RelayCommand/DelegateCommand,改用 CommunityToolkit.Mvvm;INotifyPropertyChanged 基类改为带 [ObservableProperty] 分部属性的 ObservableObject;自定义 RelayCommand 改为 [RelayCommand] 特性;{Binding} 改为 {x:Bind Mode=OneWay};DynamicResource 改为 {ThemeResource}。
- 资源替换:.resx → .resw(复制并重命名到 Strings\en-us\)、{x:Static} → x:Uid、Properties.Resources.Key → ResourceLoader.GetString("Key")。
使用方式
按资料给出的八个步骤顺序执行:审计 → 创建项目并对齐命名空间 → 替换命名空间 → 替换控件 → 替换线程 → 替换成像 → 替换 MVVM → 替换资源。关键规则包括:不得引用 PresentationCore、PresentationFramework 或 System.Windows.Controls 程序集;不得添加 <UseWPF>true</UseWPF> 或 <WindowsPackageType>None</WindowsPackageType>;不得删除 Package.appxmanifest;不得覆盖 App.xaml / App.xaml.cs,而应把 WPF 代码合并进 WinUI 3 模板;启动应用时始终使用 winapp run,不要直接运行 .exe;把迁移拆成文件级任务,不要一次性整体重写。
迁移后验证
资料提供验证内容:再次检索 System.Windows. 应无结果;用 Test-Path "Package.appxmanifest" 确认打包文件保留(应为 True);然后构建并运行 .\BuildAndRun.ps1。
适用场景
适用于需要把基于 WPF 的桌面应用代码迁移到 WinUI 3 的开发场景,尤其是使用了 MVVM 框架、资源本地化与成像 API 的项目。
限制
资料未提供该技能的具体安装方式、运行环境版本要求、支持的 WPF 版本范围或迁移成功率等信息,这些事实暂未提供。