Migrar uma aplicação WPF para o WinUI 3

As aplicações WPF funcionam em .NET, mas utilizam a stack XAML da Windows Presentation Foundation. O WinUI 3 é o substituto moderno. O principal desafio para a migração de IA é que WPF usa namespaces System.Windows.* enquanto o WinUI 3 usa Microsoft.UI.Xaml.*, e muitas APIs de controlo e janelas precisam de substituições direcionadas em vez de simples pesquisa e substituição.

Instalar a habilidade de migração WPF

gh copilot plugin install winui@awesome-copilot

Tabela de substituição de API

Namespaces

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.*

Controlos

WPF WinUI 3 Observações
Window Microsoft.UI.Xaml.Window Diferentes superfícies de API
Grid, StackPanel, Canvas Inalterado Mesmos nomes
TextBox, Button, CheckBox Inalterado Mesmos nomes, estilo WinUI
ListBox / ListView ListView Utilize ItemsView para código novo
DataGrid DataGrid (Kit de Ferramentas da Comunidade) Adicionar CommunityToolkit.WinUI.Controls.DataGrid
TabControl TabView API diferente
Menu / MenuItem MenuBar / MenuBarItem
ToolBar CommandBar
RichTextBox RichEditBox
WebBrowser WebView2 API diferente, assíncrona

Encadeamento

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

Sistema de janelas e DPI

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

Vinculação de dados

WPF WinUI 3
INotifyPropertyChanged Inalterado
ObservableCollection<T> Inalterado
{Binding} {x:Bind} Preferencial (tempo de compilação)
DependencyProperty Inalterado
IValueConverter Inalterado

Recursos e estilos

WPF WinUI 3
ResourceDictionary Inalterado
StaticResource Inalterado
DynamicResource {ThemeResource} para as cores do sistema
SystemColors.WindowBrush {ThemeResource SystemFillColorSolidNeutralBrush}

Prompt inicial

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.

Alterações no ficheiro Project

<!-- 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

APIs que não migram diretamente

Diga ao agente para sinalizar estes casos em vez de tentar adivinhar:

  • camada WPF Adorner — não há equivalente no WinUI 3
  • WPF FlowDocument / DocumentViewer — use RichEditBox para conteúdo editável; não há equivalente de visualizador
  • WPF Viewport3D — utilize a interoperabilidade com Win2D ou DirectX
  • Alojamento de espaço aéreo / HWND — usar SwapChainPanel ou padrões de interoperabilidade Win32

Conteúdo relacionado

  • Last updated on