Migrer une application UWP vers WinUI 3

UWP n’est plus en cours de développement actif. WinUI 3 et le SDK d'application Windows sont ses successeurs, et les outils IA peuvent automatiser la majeure partie de la migration. Le principal défi est que les modèles IA ont été formés sur des années d’échantillons UWP. Par conséquent, sans conseils, ils reproduisent les modèles que vous essayez de quitter. Cette page fournit à votre agent le contexte dont il a besoin pour bien faire les choses.

Installer le plug-in de l’agent WinUI

La winui-uwp-migration compétence gère automatiquement les substitutions courantes :

gh copilot plugin install winui@awesome-copilot

Pour plus d’informations, consultez le plug-in de l’agent WinUI .

Table de substitution d’API

Espaces de noms

UWP WinUI 3
Windows.UI.Xaml.* Microsoft.UI.Xaml.*
Windows.UI.Xaml.Controls.* Microsoft.UI.Xaml.Controls.*
Windows.UI.Xaml.Media.* Microsoft.UI.Xaml.Media.*
Windows.UI.Composition Microsoft.UI.Composition

Thread

UWP WinUI 3
CoreDispatcher DispatcherQueue
Dispatcher.RunAsync(...) DispatcherQueue.TryEnqueue(...)
CoreApplication.MainView.CoreWindow.Dispatcher this.DispatcherQueue (à partir d’un Window ou Page)

Windowing

UWP WinUI 3
ApplicationView AppWindow
ApplicationView.GetForCurrentView() AppWindow.GetFromWindowId(...)
ApplicationViewTitleBar AppWindowTitleBar
CoreWindow Microsoft.UI.Xaml.Window
SystemNavigationManager Bouton Retour via AppWindowTitleBar

Boîtes de dialogue et sélecteurs

UWP WinUI 3
MessageDialog ContentDialog (défini XamlRoot)
FileOpenPicker FileOpenPicker + InitializeWithWindow
FileSavePicker FileSavePicker + InitializeWithWindow
FolderPicker FolderPicker + InitializeWithWindow

Important

Les sélecteurs nécessitent InitializeWithWindow avant l’appel PickSingleFileAsync (ou similaire) :

var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);

ContentDialog nécessite XamlRoot (pas InitializeWithWindow) :

var dialog = new ContentDialog { XamlRoot = this.Content.XamlRoot, ... };
await dialog.ShowAsync();

Notifications

UWP WinUI 3
Windows.UI.Notifications.ToastNotificationManager Microsoft.Windows.AppNotifications.AppNotificationManager
Windows.UI.Notifications.BadgeUpdateManager Microsoft.Windows.BadgeNotifications.BadgeNotificationManager
Windows.UI.Notifications.TileUpdateManager Les vignettes sont déconseillées : utiliser des notifications ou des widgets
UWP WinUI 3
Frame.Navigate(typeof(MyPage)) Frame.Navigate(typeof(MyPage)) — inchangé
SystemNavigationManager.BackRequested Gérer via NavigationView ou AppWindow
Windows.UI.Core.Preview.SystemNavigationManagerPreview événement AppWindow.Closing

Cycle de vie de l’application

UWP WinUI 3
Application.Current.Suspending Microsoft.Windows.AppLifecycle (nécessite des modifications architecturales - voir remarque)
Application.Current.Resuming AppInstance.GetCurrent().Activated (voir remarque)
BackgroundTaskBuilder Tâches en arrière-plan du SDK d'application Windows

Note

La migration du cycle de vie des applications WinUI 3 n’est pas un échange simple de nom d’API. Le SDK d'application Windows utilise un modèle d’activation et de suspension différent. Traitez le code de cycle de vie comme nécessitant une réécriture dédiée plutôt que la substitution automatisée. Consultez la documentation de cycle de vie SDK d'application Windows pour le modèle complet.

Paramètres et stockage

UWP WinUI 3
ApplicationData.Current.LocalSettings Inchangé
ApplicationData.Current.LocalFolder Inchangé
Windows.Storage.KnownFolders Inchangé

API qui ne changent pas

Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color et la plupart des API WinRT en dehors de l’espace de noms XAML sont inchangées.

Invite de démarrage

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

Apply these substitutions:
- Windows.UI.Xaml.* → Microsoft.UI.Xaml.*
- CoreDispatcher / Dispatcher.RunAsync → DispatcherQueue.TryEnqueue
- ApplicationView → AppWindow + AppWindowTitleBar
- CoreWindow → Microsoft.UI.Xaml.Window
- MessageDialog → ContentDialog (set XamlRoot, not InitializeWithWindow)
- FileOpenPicker / FileSavePicker / FolderPicker → add InitializeWithWindow
- Windows.UI.Notifications → Microsoft.Windows.AppNotifications
- SystemNavigationManager.BackRequested → NavigationView back handling

Do not use any Windows.UI.Xaml.* namespaces in new code.
Do not use CoreDispatcher — use DispatcherQueue.
Flag any APIs without a direct WinUI 3 equivalent rather than guessing.

modifications apportées au fichier Project

Remplacez le framework cible UWP :

<!-- Before (UWP) -->
<TargetPlatformVersion>10.0.19041.0</TargetPlatformVersion>
<TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>

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

Ajoutez le package SDK d'application Windows :

dotnet add package Microsoft.WindowsAppSDK

Contenu connexe

  • Last updated on