Eseguire la migrazione di un'app UWP a WinUI 3

La piattaforma UWP non è più in fase di sviluppo attivo. WinUI 3 e il SDK per app di Windows sono i suoi successori e gli strumenti di intelligenza artificiale possono automatizzare la maggior parte della migrazione. La sfida principale è che i modelli di intelligenza artificiale sono stati sottoposti a training su anni di esempi UWP, quindi senza indicazioni riproducono i modelli da cui si sta tentando di allontanarsi. Questa pagina fornisce all'agente il contesto necessario per farlo correttamente.

Installare il plug-in dell'agente WinUI

La winui-uwp-migration competenza gestisce automaticamente le sostituzioni comuni:

gh copilot plugin install winui@awesome-copilot

Per informazioni dettagliate, vedere il plug-in dell'agente WinUI .

Tabella di sostituzione API

Namespaces

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

Gestione dei thread

UWP WinUI 3
CoreDispatcher DispatcherQueue
Dispatcher.RunAsync(...) DispatcherQueue.TryEnqueue(...)
CoreApplication.MainView.CoreWindow.Dispatcher this.DispatcherQueue (da un Window o Page)

Windowing

UWP WinUI 3
ApplicationView AppWindow
ApplicationView.GetForCurrentView() AppWindow.GetFromWindowId(...)
ApplicationViewTitleBar AppWindowTitleBar
CoreWindow Microsoft.UI.Xaml.Window
SystemNavigationManager Pulsante Indietro tramite AppWindowTitleBar

Dialoghi e selezione

UWP WinUI 3
MessageDialog ContentDialog (imposta XamlRoot)
FileOpenPicker FileOpenPicker + InitializeWithWindow
FileSavePicker FileSavePicker + InitializeWithWindow
FolderPicker FolderPicker + InitializeWithWindow

Important

I selettori richiedono InitializeWithWindow prima di invocare PickSingleFileAsync (o simile):

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

ContentDialog richiede XamlRoot (non InitializeWithWindow):

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

Notifiche

UWP WinUI 3
Windows.UI.Notifications.ToastNotificationManager Microsoft.Windows.AppNotifications.AppNotificationManager
Windows.UI.Notifications.BadgeUpdateManager Microsoft.Windows.BadgeNotifications.BadgeNotificationManager
Windows.UI.Notifications.TileUpdateManager I riquadri sono deprecati: usare notifiche o widget
UWP WinUI 3
Frame.Navigate(typeof(MyPage)) Frame.Navigate(typeof(MyPage)) — invariato
SystemNavigationManager.BackRequested Gestire tramite NavigationView o AppWindow
Windows.UI.Core.Preview.SystemNavigationManagerPreview AppWindow.Closing evento

Ciclo di vita dell'app

UWP WinUI 3
Application.Current.Suspending Microsoft.Windows.AppLifecycle (richiede modifiche dell'architettura - vedere la nota)
Application.Current.Resuming AppInstance.GetCurrent().Activated (vedere la nota)
BackgroundTaskBuilder Le attività in background di SDK per app di Windows

Note

La migrazione del ciclo di vita dell'app WinUI 3 non è un semplice scambio di nomi API. Il SDK per app di Windows usa un modello di attivazione e sospensione diverso. Trattare il codice relativo al ciclo di vita come qualcosa che richiede una riscrittura dedicata anziché una sostituzione automatica. Per il modello completo, vedere la documentazione SDK per app di Windows ciclo di vita.

Impostazioni e archiviazione

UWP WinUI 3
ApplicationData.Current.LocalSettings Invariato
ApplicationData.Current.LocalFolder Invariato
Windows.Storage.KnownFolders Invariato

API che non cambiano

Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color e la maggior parte delle API WinRT all'esterno dello spazio dei nomi XAML rimane invariata.

Prompt di avvio

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.

Modifiche ai file di progetto

Sostituire il framework di destinazione 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>

Aggiungere il pacchetto SDK per app di Windows:

dotnet add package Microsoft.WindowsAppSDK

Contenuti correlati

  • Last updated on