Migrowanie aplikacji WPF do interfejsu WinUI 3

Aplikacje WPF działają w środowisku .NET, ale używają stosu XAML platformy Windows Presentation Foundation. WinUI 3 jest nowoczesnym zamiennikiem. Głównym wyzwaniem przy migracji wspomaganej przez AI jest to, że WPF używa przestrzeni nazw System.Windows.*, podczas gdy WinUI 3 używa Microsoft.UI.Xaml.*, a wiele kontrolek i interfejsów API obsługi okien wymaga ukierunkowanych zamian, a nie prostego wyszukiwania i zastępowania.

Instalowanie umiejętności migracji WPF

gh copilot plugin install winui@awesome-copilot

Tabela podstawiania interfejsu API

Przestrzenie nazw

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

Sterowanie

WPF WinUI 3 Notatki
Window Microsoft.UI.Xaml.Window Różne powierzchnie interfejsu API
Grid, StackPanel, Canvas Niezmienione Te same nazwy
TextBox, Button, CheckBox Niezmienione Te same nazwy, styl WinUI
ListBox / ListView ListView Użyj ItemsView dla nowego kodu
DataGrid DataGrid (CommunityToolkit) Dodaj CommunityToolkit.WinUI.Controls.DataGrid
TabControl TabView Inny interfejs API
Menu / MenuItem MenuBar / MenuBarItem
ToolBar CommandBar
RichTextBox RichEditBox
WebBrowser WebView2 Inny interfejs API, asynchroniczny

Wątkowanie

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

Obsługa okien i DPI

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

Powiązanie danych

WPF WinUI 3
INotifyPropertyChanged Niezmienione
ObservableCollection<T> Niezmienione
{Binding} {x:Bind} preferowane (czas kompilacji)
DependencyProperty Niezmienione
IValueConverter Niezmienione

Zasoby i style

WPF WinUI 3
ResourceDictionary Niezmienione
StaticResource Niezmienione
DynamicResource {ThemeResource} dla kolorów systemowych
SystemColors.WindowBrush {ThemeResource SystemFillColorSolidNeutralBrush}

Monit startowy

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.

Zmiany w plikach projektu

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

Interfejsy API, których nie można migrować bezpośrednio

Poinformuj agenta, aby oznaczał takie przypadki, zamiast zgadywać:

  • warstwa WPF Adorner — brak odpowiednika w warstwie WinUI 3
  • WPF FlowDocument / DocumentViewer — użyj RichEditBox do edytowalnej zawartości; brak odpowiednika przeglądarki
  • WPF Viewport3D — użyj międzyoperajności Win2D lub DirectX
  • Air-space / hostowanie HWND — użyć SwapChainPanel lub wzorców interoperacyjności Win32

Treści powiązane

  • Last updated on