Een UWP-app migreren naar WinUI 3

UWP wordt niet langer actief ontwikkeld. WinUI 3 en de Windows App SDK zijn opvolgers, en AI-hulpprogramma's kunnen de meeste migratie automatiseren. De belangrijkste uitdaging is dat AI-modellen zijn getraind op jaren van UWP-voorbeelden, dus zonder richtlijnen reproduceren ze de patronen waarvan u weg wilt gaan. Deze pagina geeft uw agent de context die deze nodig heeft om het goed te doen.

De WinUI-agentinvoegtoepassing installeren

De winui-uwp-migration vaardigheid verwerkt de algemene vervangingen automatisch:

gh copilot plugin install winui@awesome-copilot

Zie de WinUI-agentinvoegtoepassing voor meer informatie.

API-substitutietabel

In de volgende tabellen worden de meest voorkomende API-vervangingen samengevat. Zie UWP-API's en bibliotheken toewijzen aan de Windows App SDK voor de volledige gedetailleerde toewijzing, inclusief leden, eigenschappen en minder algemene API's.

Namespaces

Draadbewerking

Windowing

Dialoogvensters en selectievensters

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();

Meldingen

Netwerken en HTTP

Navigation

MVVM-patronen

dotnet add package CommunityToolkit.Mvvm

App-levenscyclus

Instellingen en opslag

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);

API's die niet worden gewijzigd

Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color en de meeste WinRT-API's buiten de XAML-naamruimte zijn ongewijzigd.

Besturingselementen zonder een direct equivalent

Sommige UWP-besturingselementen bestaan niet in WinUI 3. Kies een vervanging op basis van uw scenario:

Inkt, Win2D en afdrukken

Voor deze subsystemen zijn specifieke migratiestappen vereist die verder gaan dan wijzigingen in de naamruimte.

Windows inkt

De InkCanvas- en InkPresenter-API’s verhuizen naar Microsoft.UI.Input.Inking, maar zijn verder identiek. De ene niet-voor de hand liggende verandering is CoreInputDeviceTypes:

InkStrokeContainer.SaveAsync() en LoadAsync() hebben nog steeds IRandomAccessStream nodig. Brug van System.IO stromen:

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

De win2D-pakketnaam is gewijzigd, maar de API-surface is identiek:

Alle Microsoft.Graphics.Canvas.* API's (CanvasDevice, CanvasBitmap, CanvasRenderTarget, DrawInk) werken op dezelfde manier. Alleen de Verwijzing naar het NuGet-pakket moet worden bijgewerkt.

Drukkerij

UWP-afdrukken maakt gebruik van PrintManager.GetForCurrentView(). WinUI 3 vereist interoperabiliteit met vensterhandgrepen:

// 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);

De PrintDocument rendering-API's (Paginate, GetPreviewPage, AddPages) zijn ongewijzigd.

Startprompt

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.

Wijzigingen in projectbestanden

Vervang het UWP-doelframework:

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

Voeg het Windows App SDK-pakket toe:

dotnet add package Microsoft.WindowsAppSDK

Verwante inhoud

• Windows App SDK migratiehandleiding : volledige handleiding voor handmatige migratie
• UWP-API's en -bibliotheken toewijzen aan de Windows App SDK - uitgebreide API-toewijzingstabel
• Wat wordt ondersteund bij het migreren van UWP naar WinUI - status van functieondersteuning
• Migreren van WPF