Migrieren einer UWP-App zu WinUI 3

UWP befindet sich nicht mehr in der aktiven Entwicklung. WinUI 3 und die Windows App SDK sind ihre Nachfolger – und KI-Tools können die meisten Migrationen automatisieren. Die wichtigste Herausforderung besteht darin, dass KI-Modelle auf Jahren von UWP-Beispielen trainiert wurden. Ohne Anleitungen reproduzieren sie also die Muster, von denen Sie sich wegbewegen möchten. Diese Seite gibt Ihrem Agenten den Kontext, den er benötigt, um es richtig zu machen.

Installieren des WinUI-Agent-Plug-Ins

Der winui-uwp-migration Skill übernimmt die gängigen Ersetzungen automatisch:

gh copilot plugin install winui@awesome-copilot

Ausführliche Informationen finden Sie im WinUI-Agent-Plug-In .

API-Ersetzungstabelle

In den folgenden Tabellen sind die am häufigsten verwendeten API-Ersetzungen zusammengefasst. Die vollständige detaillierte Zuordnung , einschließlich Membern, Eigenschaften und weniger gängigen APIs, finden Sie unter Zuordnen von UWP-APIs und -Bibliotheken zum Windows App SDK.

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

Threading

UWP WinUI 3
CoreDispatcher DispatcherQueue
Dispatcher.RunAsync(...) DispatcherQueue.TryEnqueue(...)
CoreApplication.MainView.CoreWindow.Dispatcher this.DispatcherQueue (von a Window oder Page)

Windowing

UWP WinUI 3
ApplicationView AppWindow
ApplicationView.GetForCurrentView() AppWindow.GetFromWindowId(...)
ApplicationViewTitleBar AppWindowTitleBar
CoreWindow Microsoft.UI.Xaml.Window
SystemNavigationManager Schaltfläche "Zurück" über AppWindowTitleBar

Dialogfelder und Auswahlfelder

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

Important

Picker erfordern InitializeWithWindow, bevor PickSingleFileAsync (oder Ähnliches) aufgerufen wird:

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

ContentDialog erfordert XamlRoot (nicht InitializeWithWindow):

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

Benachrichtigungen

UWP WinUI 3
Windows.UI.Notifications.ToastNotificationManager Microsoft.Windows.AppNotifications.AppNotificationManager
Windows.UI.Notifications.BadgeUpdateManager Microsoft.Windows.BadgeNotifications.BadgeNotificationManager
Windows.UI.Notifications.TileUpdateManager Kacheln sind veraltet – Verwenden von Benachrichtigungen oder Widgets
UWP WinUI 3
Frame.Navigate(typeof(MyPage)) Frame.Navigate(typeof(MyPage)) — unverändert
SystemNavigationManager.BackRequested Handle über NavigationView oder AppWindow
Windows.UI.Core.Preview.SystemNavigationManagerPreview AppWindow.Closing-Ereignis

App-Lebenszyklus

UWP WinUI 3
Application.Current.Suspending Microsoft.Windows.AppLifecycle (erfordert Architekturänderungen — siehe Hinweis)
Application.Current.Resuming AppInstance.GetCurrent().Activated (siehe Hinweis)
BackgroundTaskBuilder Windows App SDK Hintergrundaufgaben

Note

WinUI 3-App-Lebenszyklusmigration ist kein einfacher API-Namenstausch. Die Windows App SDK verwendet ein anderes Aktivierungs- und Anhaltemodell. Behandeln Sie Lebenszykluscode als etwas, das eine eigene Überarbeitung erfordert, statt ihn automatisiert zu ersetzen. Informationen zum vollständigen Modell finden Sie in der Windows App SDK-Lifecycle-Dokumentation.

Einstellungen und Speicher

UWP WinUI 3
ApplicationData.Current.LocalSettings Unverändert
ApplicationData.Current.LocalFolder Unverändert
Windows.Storage.KnownFolders Unverändert

APIs, die sich nicht ändern

Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color und die meisten WinRT-APIs außerhalb des XAML-Namespaces bleiben unverändert.

Startaufforderung

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.

Änderungen an der Projektdatei

Ersetzen Sie das UWP-Zielframework:

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

Fügen Sie das Windows App SDK-Paket hinzu:

dotnet add package Microsoft.WindowsAppSDK

Verwandte Inhalte

  • Last updated on