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

Threading

Windowing

Dialogfelder und Auswahlfelder

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

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

Benachrichtigungen

Netzwerk und HTTP

Navigation

MVVM-Muster

dotnet add package CommunityToolkit.Mvvm

App-Lebenszyklus

Einstellungen und Speicher

var appData = Path.Combine(
    Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
    "YourAppName");
Directory.CreateDirectory(appData);
var json = JsonSerializer.Serialize(data);
await File.WriteAllTextAsync(Path.Combine(appData, "settings.json"), json);

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.

Steuerelemente ohne direkte Entsprechung

Einige UWP-Steuerelemente sind in WinUI 3 nicht vorhanden. Wählen Sie einen Ersatz basierend auf Ihrem Szenario aus:

Ink, Win2D und Druck

Für diese Subsysteme sind bestimmte Migrationsschritte erforderlich, die über Namespaceänderungen hinausgehen.

Windows Ink

Die InkCanvas- und InkPresenter-APIs werden nach Microsoft.UI.Input.Inking verschoben, sind aber ansonsten identisch. Die eine nicht offensichtliche Änderung lautet CoreInputDeviceTypes:

InkStrokeContainer.SaveAsync() und LoadAsync() erfordern weiterhin IRandomAccessStream. Brücke aus System.IO-Streams:

// Saving ink strokes to a file using System.IO
using var memoryStream = new MemoryStream();
using var ras = memoryStream.AsRandomAccessStream();
await inkStrokeContainer.SaveAsync(ras);
await File.WriteAllBytesAsync(filePath, memoryStream.ToArray());

// Loading ink strokes from a file
var bytes = await File.ReadAllBytesAsync(filePath);
using var ms = new MemoryStream(bytes);
using var ras = ms.AsRandomAccessStream();
await inkStrokeContainer.LoadAsync(ras);

Win2D

Der Name des Win2D-Pakets wurde geändert, die API-Oberfläche ist jedoch identisch:

Alle Microsoft.Graphics.Canvas.* APIs (CanvasDevice, CanvasBitmap, CanvasRenderTarget, DrawInk) funktionieren auf die gleiche Weise. Nur der NuGet-Paketverweis muss aktualisiert werden.

Druck

UWP-Druck verwendet PrintManager.GetForCurrentView(). WinUI 3 erfordert die Interoperabilität mit Fensterhandles:

// UWP
var printManager = PrintManager.GetForCurrentView();
printManager.PrintTaskRequested += OnPrintTaskRequested;
await PrintManager.ShowPrintUIAsync();

// WinUI 3 — must pass window handle
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
var printManager = PrintManagerInterop.GetForWindow(hwnd);
printManager.PrintTaskRequested += OnPrintTaskRequested;
await PrintManagerInterop.ShowPrintUIForWindowAsync(hwnd);

Die PrintDocument Rendering-APIs (Paginate, GetPreviewPage, AddPages) sind 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
- Pivot → TabView, NavigationView (top mode), or RadioButtons (no direct equivalent)
- InkToolbar custom subclasses → rebuild as CommandBar with AppBarToggleButton
- PrintManager.GetForCurrentView → PrintManagerInterop.GetForWindow(hwnd)
- Win2D.uwp NuGet → Microsoft.Graphics.Win2D NuGet
- Windows.UI.Input.Inking.* → Microsoft.UI.Input.Inking.*

Do not use any Windows.UI.Xaml.* namespaces in new code.
Do not use CoreDispatcher — use DispatcherQueue.
x:Bind defaults to Mode=OneTime. Add Mode=OneWay for any binding that should update at runtime.
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

• Windows App SDK Migrationshandbuch – vollständige manuelle Migrationsanleitung
• Zuordnen von UWP-APIs und -Bibliotheken zum Windows App SDK – umfassende API-Zuordnungstabelle
• Was wird bei der Migration von UWP zu WinUI unterstützt – Featureunterstützungsstatus
• Von WPF migrieren