⚡

WinUI3迁移助手 winui3-migration-helper

WinUI3迁移助手是一个专业的桌面应用程序现代化工具，专门帮助开发者将传统的WPF应用程序平滑迁移到现代的WinUI 3和Windows App SDK平台。该工具提供全面的代码分析、自动转换、兼容性评估和迁移指导，支持从WPF到WinUI 3的完整迁移流程。关键词：WPF迁移，WinUI 3，Windows App SDK，桌面应用现代化，代码转换，兼容性分析，XAML转换，.NET桌面开发，微软技术栈，应用程序升级。

前端开发 0 次安装 0 次浏览 更新于 2/25/2026

name: winui3-migration-helper description: 协助从WPF迁移到WinUI 3 / Windows App SDK，提供代码转换和兼容性指导 allowed-tools: Read, Write, Edit, Bash, Glob, Grep tags: [winui, wpf, migration, windows-app-sdk, modernization]

winui3-migration-helper

协助从WPF迁移到WinUI 3 / Windows App SDK。此技能分析WPF应用程序，并提供迁移路径、代码转换和兼容性指导，以实现向WinUI 3的现代化升级。

能力

  • 分析WPF代码库的迁移兼容性
  • 识别API差异和所需更改
  • 生成WinUI 3项目结构
  • 转换XAML语法差异
  • 将代码隐藏迁移到现代模式
  • 处理命名空间和类型映射
  • 配置Windows App SDK依赖项
  • 生成带优先级的迁移任务列表

输入模式

{
  "type": "object",
  "properties": {
    "projectPath": {
      "type": "string",
      "description": "WPF项目的路径"
    },
    "migrationStrategy": {
      "enum": ["full", "incremental", "analysis-only"],
      "default": "analysis-only"
    },
    "targetSdk": {
      "type": "string",
      "default": "1.5",
      "description": "目标Windows App SDK版本"
    },
    "preserveWpfComponents": {
      "type": "array",
      "items": { "type": "string" },
      "description": "通过XAML Islands保留的WPF组件"
    },
    "generateReport": {
      "type": "boolean",
      "default": true
    }
  },
  "required": ["projectPath"]
}

输出模式

{
  "type": "object",
  "properties": {
    "success": { "type": "boolean" },
    "compatibility": {
      "type": "object",
      "properties": {
        "score": { "type": "number" },
        "blockers": { "type": "array" },
        "warnings": { "type": "array" }
      }
    },
    "migrationTasks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "category": { "type": "string" },
          "task": { "type": "string" },
          "effort": { "enum": ["low", "medium", "high"] },
          "automated": { "type": "boolean" }
        }
      }
    },
    "codeTransformations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": { "type": "string" },
          "original": { "type": "string" },
          "transformed": { "type": "string" }
        }
      }
    }
  },
  "required": ["success"]
}

关键差异

命名空间变更

WPF WinUI 3
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

XAML命名空间

<!-- WPF -->
<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

<!-- WinUI 3 -->
<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:MyApp">

窗口创建

// WPF
public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
    }
}

// WinUI 3
public sealed partial class MainWindow : Window
{
    public MainWindow()
    {
        this.InitializeComponent();

        // WinUI 3: 无自动窗口大小调整
        this.SetWindowSize(800, 600);
    }

    private void SetWindowSize(int width, int height)
    {
        var hWnd = WinRT.Interop.WindowNative.GetWindowHandle(this);
        var windowId = Microsoft.UI.Win32Interop.GetWindowIdFromWindow(hWnd);
        var appWindow = Microsoft.UI.Windowing.AppWindow.GetFromWindowId(windowId);
        appWindow.Resize(new Windows.Graphics.SizeInt32(width, height));
    }
}

常见控件差异

<!-- WPF: DataGrid -->
<DataGrid ItemsSource="{Binding Items}"
          AutoGenerateColumns="False">
    <DataGrid.Columns>
        <DataGridTextColumn Header="Name" Binding="{Binding Name}"/>
    </DataGrid.Columns>
</DataGrid>

<!-- WinUI 3: 社区工具包DataGrid -->
<toolkit:DataGrid ItemsSource="{x:Bind ViewModel.Items}"
                  AutoGenerateColumns="False">
    <toolkit:DataGrid.Columns>
        <toolkit:DataGridTextColumn Header="Name" Binding="{Binding Name}"/>
    </toolkit:DataGrid.Columns>
</toolkit:DataGrid>

绑定语法

<!-- WPF: 经典绑定 -->
<TextBlock Text="{Binding Name}"/>
<Button Command="{Binding SaveCommand}"/>

<!-- WinUI 3: x:Bind (编译绑定，推荐) -->
<TextBlock Text="{x:Bind ViewModel.Name, Mode=OneWay}"/>
<Button Command="{x:Bind ViewModel.SaveCommand}"/>

<!-- WinUI 3: 经典绑定仍然可用 -->
<TextBlock Text="{Binding Name}"/>

资源字典

<!-- WPF -->
<ResourceDictionary>
    <SolidColorBrush x:Key="AccentBrush" Color="#0078D4"/>
    <Style TargetType="Button">
        <Setter Property="Background" Value="{StaticResource AccentBrush}"/>
    </Style>
</ResourceDictionary>

<!-- WinUI 3 -->
<ResourceDictionary>
    <SolidColorBrush x:Key="AccentBrush" Color="#0078D4"/>
    <Style TargetType="Button">
        <Setter Property="Background" Value="{StaticResource AccentBrush}"/>
    </Style>
</ResourceDictionary>
<!-- 注意：大部分兼容，但部分默认样式不同 -->

项目配置

WPF .csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows</TargetFramework>
    <UseWPF>true</UseWPF>
  </PropertyGroup>
</Project>

WinUI 3 .csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <UseWinUI>true</UseWinUI>
    <WindowsPackageType>None</WindowsPackageType>
    <Platforms>x64;x86;arm64</Platforms>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.5.240227000"/>
    <PackageReference Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.22621.756"/>
  </ItemGroup>
</Project>

迁移障碍

WinUI 3中不可用

功能 替代方案
NavigationWindow 使用Frame的自定义导航
DataGrid (内置) 社区工具包DataGrid
RichTextBox RichEditBox
WebBrowser WebView2
WindowsFormsHost 不可用 (反向使用XAML Islands)
系统托盘图标 直接使用Win32 API

需要更改

WPF功能 WinUI 3方法
Application.Current.Dispatcher DispatcherQueue
RoutedUICommand ICommand实现
样式中的触发器 VisualStateManager
效果 (模糊等) Composition API
DynamicResource StaticResource (大部分)

代码转换

调度器

// WPF
Application.Current.Dispatcher.Invoke(() => {
    // UI代码
});

// WinUI 3
DispatcherQueue.GetForCurrentThread().TryEnqueue(() => {
    // UI代码
});

触发器到VisualStateManager

<!-- WPF: 样式触发器 -->
<Style TargetType="Button">
    <Style.Triggers>
        <Trigger Property="IsMouseOver" Value="True">
            <Setter Property="Background" Value="LightBlue"/>
        </Trigger>
    </Style.Triggers>
</Style>

<!-- WinUI 3: VisualStateManager -->
<Style TargetType="Button">
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="Button">
                <Border x:Name="RootBorder" Background="{TemplateBinding Background}">
                    <VisualStateManager.VisualStateGroups>
                        <VisualStateGroup x:Name="CommonStates">
                            <VisualState x:Name="PointerOver">
                                <Storyboard>
                                    <ColorAnimation Storyboard.TargetName="RootBorder"
                                                    Storyboard.TargetProperty="(Border.Background).(SolidColorBrush.Color)"
                                                    To="LightBlue"/>
                                </Storyboard>
                            </VisualState>
                        </VisualStateGroup>
                    </VisualStateManager.VisualStateGroups>
                    <ContentPresenter/>
                </Border>
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</Style>

最佳实践

  1. 从分析开始: 迁移前了解范围
  2. 增量迁移: 逐个功能迁移
  3. 使用x:Bind: 比经典绑定性能更好
  4. 采用WinUI样式: 不要对抗默认设置
  5. 在Windows 10最低版本上测试: 验证兼容性
  6. 考虑XAML Islands: 用于渐进式迁移

相关技能

  • wpf-mvvm-scaffold - MVVM模式 (两者都适用)
  • msix-package-generator - WinUI 3打包
  • desktop-migration 流程 - 完整迁移工作流

相关代理

  • wpf-dotnet-expert - WPF专业知识
  • desktop-migration-strategist - 迁移规划