Migración de una aplicación de WPF a WinUI 3

Las aplicaciones WPF se ejecutan en .NET, pero usan el entorno XAML de Windows Presentation Foundation. WinUI 3 es el reemplazo moderno. El principal desafío de la migración de IA es que WPF usa los espacios de nombres System.Windows.*, mientras que WinUI 3 usa Microsoft.UI.Xaml.*, y muchos controles y API de ventanas requieren sustituciones específicas en lugar de una simple búsqueda y reemplazo.

Instalar la habilidad de migración de WPF

gh copilot plugin install winui@awesome-copilot

Tabla de sustitución de API

Espacios de nombres

WPF WinUI 3
System.Windows.* Microsoft.UI.Xaml.*
System.Windows.Controls.* Microsoft.UI.Xaml.Controls.*
System.Windows.Media.* Microsoft.UI.Xaml.Media.*
System.Windows.Data.* Microsoft.UI.Xaml.Data.*
System.Windows.Input.* Microsoft.UI.Input.*

Controles

WPF WinUI 3 Notas
Window Microsoft.UI.Xaml.Window Superficie de API diferente
Grid, , StackPanel, Canvas Sin cambios Mismos nombres
TextBox, , Button, CheckBox Sin cambios Mismos nombres, estilo winUI
ListBox / ListView ListView Uso ItemsView para código nuevo
DataGrid DataGrid (CommunityToolkit) Agregue CommunityToolkit.WinUI.Controls.DataGrid.
TabControl TabView API diferente
Menu / MenuItem MenuBar / MenuBarItem
ToolBar CommandBar
RichTextBox RichEditBox
WebBrowser WebView2 API diferente, asíncrona

Threading

WPF WinUI 3
Dispatcher.Invoke(...) DispatcherQueue.TryEnqueue(...)
Dispatcher.BeginInvoke(...) DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Low, ...)
Application.Current.Dispatcher this.DispatcherQueue

Gestión de ventanas y DPI

WPF WinUI 3
Window.WindowState AppWindow.Presenter (utilice OverlappedPresenter)
SystemParameters.WorkArea DisplayArea.GetFromWindowId(...)
PresentationSource.FromVisual() WinRT.Interop.WindowNative.GetWindowHandle(window)

Vinculación de datos

WPF WinUI 3
INotifyPropertyChanged Sin cambios
ObservableCollection<T> Sin cambios
{Binding} {x:Bind} preferido (tiempo de compilación)
DependencyProperty Sin cambios
IValueConverter Sin cambios

Recursos y estilos

WPF WinUI 3
ResourceDictionary Sin cambios
StaticResource Sin cambios
DynamicResource {ThemeResource} para los colores del sistema
SystemColors.WindowBrush {ThemeResource SystemFillColorSolidNeutralBrush}

Mensaje de inicio

I'm migrating a WPF app to WinUI 3 using the Windows App SDK.

Apply these substitutions:
- System.Windows.* → Microsoft.UI.Xaml.*
- Dispatcher.Invoke / BeginInvoke → DispatcherQueue.TryEnqueue
- Window.WindowState → AppWindow with OverlappedPresenter
- PresentationSource → WinRT.Interop.WindowNative.GetWindowHandle
- DynamicResource for system colors → ThemeResource
- {Binding} → {x:Bind} where possible (compile-time binding)
- ListBox → ListView or ItemsView
- TabControl → TabView
- WebBrowser → WebView2
- DataGrid → CommunityToolkit.WinUI.Controls.DataGrid

Do not use any System.Windows.* namespaces in new code.
Do not use Dispatcher.Invoke — use DispatcherQueue.TryEnqueue.
Flag APIs without a direct WinUI 3 equivalent rather than guessing.

Cambios en el archivo del proyecto

<!-- Before (WPF) -->
<TargetFramework>net10.0-windows</TargetFramework>
<UseWPF>true</UseWPF>

<!-- After (WinUI 3) -->
<TargetFramework>net10.0-windows10.0.19041.0</TargetFramework>
<WindowsSdkPackageVersion>10.0.19041.31</WindowsSdkPackageVersion>

dotnet add package Microsoft.WindowsAppSDK

Las API que no se pueden migrar directamente

Indique al agente que señale estos casos en lugar de hacer suposiciones:

  • WPF Adorner capa, sin equivalente en WinUI 3
  • WPF FlowDocument / DocumentViewer: use RichEditBox para contenido editable; no hay ningún equivalente de visor
  • WPF Viewport3D — usa la interoperabilidad de Win2D o DirectX
  • Hospedaje de espacio aéreo o HWND: usar SwapChainPanel o patrones de interoperabilidad win32

Contenido relacionado

  • Last updated on