Migrer une application WPF vers WinUI 3

Les applications WPF s’exécutent sur .NET, mais s’appuient sur la pile XAML de Windows Presentation Foundation. WinUI 3 est le remplacement moderne. Le principal défi pour la migration d’IA est que WPF utilise des espaces de noms System.Windows.* tandis que WinUI 3 utilise Microsoft.UI.Xaml.*, et de nombreux contrôles et API de fenêtrage ont besoin de substitutions ciblées plutôt que de simples recherches et remplacement.

Installer la compétence de migration WPF

gh copilot plugin install winui@awesome-copilot

Table de substitution d’API

Espaces de noms

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

Contrôles

WPF WinUI 3 Remarques
Window Microsoft.UI.Xaml.Window Surface d’API différente
Grid, StackPanel, Canvas Inchangé Mêmes noms
TextBox, Button, CheckBox Inchangé Mêmes noms, style WinUI
ListBox / ListView ListView Utiliser ItemsView pour le nouveau code
DataGrid DataGrid (CommunityToolkit) Ajouter CommunityToolkit.WinUI.Controls.DataGrid
TabControl TabView API différente
Menu / MenuItem MenuBar / MenuBarItem
ToolBar CommandBar
RichTextBox RichEditBox
WebBrowser WebView2 Autre API, asynchrone

Thread

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

Gestion des fenêtres et PPP

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

Liaison de données

WPF WinUI 3
INotifyPropertyChanged Inchangé
ObservableCollection<T> Inchangé
{Binding} {x:Bind} préféré (au moment de la compilation)
DependencyProperty Inchangé
IValueConverter Inchangé

Ressources et styles

WPF WinUI 3
ResourceDictionary Inchangé
StaticResource Inchangé
DynamicResource {ThemeResource} pour les couleurs système
SystemColors.WindowBrush {ThemeResource SystemFillColorSolidNeutralBrush}

Invite de démarrage

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.

modifications apportées au fichier 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

API qui ne migrent pas directement

Indiquez à l’agent de marquer ces éléments plutôt que de deviner :

  • couche WPF Adorner — aucun équivalent dans WinUI 3
  • WPF FlowDocument / DocumentViewer — utilisez RichEditBox pour le contenu modifiable ; aucune visionneuse équivalente
  • WPF Viewport3D — utiliser Win2D ou DirectX Interop
  • Hébergement Airspace / HWND — utiliser SwapChainPanel ou des modèles d’interop Win32

Contenu connexe

  • Last updated on