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

WinUI bevatInkCanvas, InkToolbaren InkPresenter als experimentele API's in experimentele releases van de Windows App SDK. Stabiele releases bevatten ze niet. Zie Handschriftbesturingselementen voor WinUI-apps voor installatie, aanpassing van werkbalken en bekende beperkingen.

In experimentele releases bevinden de besturingselementen en de typen die inktinvoer verwerken zich in Microsoft.UI.Xaml.Controls. Pennenstreken en tekenattributen blijven in Windows.UI.Input.Inking:

Elk UWP-type in de eerste twee rijen heeft een tegenhanger met dezelfde naam, maar Windows App SDK 2.5.4-experimenteel bevat niet al hun leden:

• InkStrokeContainer heeft geen openbare constructor en InkPresenter.StrokeContainer is alleen-lezen. Als u wilt schakelen tussen reeksen pennenstreken, slaat u elke set op met SaveAsync en herstelt u deze met LoadAsync, waardoor de huidige pennenstreken worden vervangen.
• SaveAsync en LoadAsync retourneert IAsyncAction, zodat ze geen voortgang rapporteren en SaveAsync het aantal bytes dat het heeft geschreven niet retourneert.
• InkStrokeContainer.GetRecognitionResults, InkStrokeContainer.UpdateRecognitionResultsen InkInputConfiguration.IsPenHapticFeedbackEnabled zijn niet beschikbaar.
• InkToolbarRulerButton.Ruler en de InkToolbar.IsRulerButtonCheckedChanged gebeurtenis zijn niet beschikbaar. UWP heeft InkToolbarRulerButton verouderd verklaard ten gunste van InkToolbarStencilButton, dus gebruik in plaats daarvan de stencilknop en de InkToolbar.IsStencilButtonCheckedChanged-gebeurtenis.

Windows App SDK 2.4.1-experimental voegde gum-API's toe, zoals InkToolbarEraserKind en InkToolbarEraserButton.SelectedEraser, die 2.5.4-experimental verwijderde. Ze maakten nooit deel uit van UWP, dus voeg ze niet toe aan gemigreerde code. Zie Wijzigingen van 2.4.1-experimenteel voor de volledige lijst.

Omdat typen zoals InkPresenter en InkStrokeContainer in beide naamruimten bestaan, veroorzaakt het importeren van zowel Microsoft.UI.Xaml.Controls als Windows.UI.Input.Inking fout CS0104 wanneer u deze namen gebruikt. Importeer Microsoft.UI.Xaml.Controlsen voeg aliasrichtlijnen toe voor de Windows.UI.Input.Inking typen die u gebruikt:

using Microsoft.UI.Xaml.Controls;
using InkDrawingAttributes = Windows.UI.Input.Inking.InkDrawingAttributes;
using InkStroke = Windows.UI.Input.Inking.InkStroke;

InkStrokeContainer.SaveAsync schrijft naar een IOutputStream, en LoadAsync leest van een IInputStream. Als u System.IO bestandsstromen wilt gebruiken, converteert u ze met AsOutputStream en AsInputStream. Het bestand heeft using System; nodig om op deze Windows Runtime-methoden te wachten, samen met using System.IO; en using Windows.Storage.Streams;:

// Save ink strokes to a file.
using (FileStream fileStream = File.Create(filePath))
using (IOutputStream output = fileStream.AsOutputStream())
{
    await inkStrokeContainer.SaveAsync(output);
    await output.FlushAsync();
}

// Load ink strokes from a file.
using (FileStream fileStream = File.OpenRead(filePath))
using (IInputStream input = fileStream.AsInputStream())
{
    await inkStrokeContainer.LoadAsync(input);
}

U kunt de werkbalk met het canvas verbonden houden met InkToolbar.TargetInkCanvas, of TargetInkPresenter zo instellen dat deze rechtstreeks met een InkPresenter wordt verbonden. Als u uw eigen hulpmiddelen wilt toevoegen aan de werkbalk, gebruikt InkToolbarCustomToolButton u en InkToolbarCustomToggleButton, zoals wordt weergegeven in de werkbalk Inkt aanpassen. Bekijk voordat u migreert de bekende beperkingen, zoals gerapporteerde problemen met de liniaal en stencils voor de gradenboog.

Als uw app een stabiele release moet gebruiken, is er geen ingebouwd inktbesturingselement om naar te migreren. Render stroken met Win2D en verwerk pointerinvoer zelf, of gebruik een inktbibliotheek van derden. Om InkToolbar te vervangen, gebruikt u een CommandBar met AppBarToggleButton items.

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)
- InkCanvas, InkToolbar, InkPresenter, InkStrokeContainer, and the other ink input types → Microsoft.UI.Xaml.Controls (experimental Windows App SDK releases only; if the project uses a stable release, flag them instead)
- Ink members that Windows App SDK 2.5.4-experimental doesn't include (new InkStrokeContainer(), assignments to InkPresenter.StrokeContainer, GetRecognitionResults, UpdateRecognitionResults, IsPenHapticFeedbackEnabled, InkToolbarRulerButton.Ruler, IsRulerButtonCheckedChanged, and progress or byte counts from SaveAsync and LoadAsync) → flag them
- PrintManager.GetForCurrentView → PrintManagerInterop.GetForWindow(hwnd)
- Win2D.uwp NuGet → Microsoft.Graphics.Win2D NuGet
- InkStroke, InkDrawingAttributes, InkPoint, InkStrokeBuilder → no change (Windows.UI.Input.Inking; use using aliases to avoid CS0104)

Do not use any Windows.UI.Xaml.* namespaces in new code.
Do not use CoreDispatcher — use DispatcherQueue.
Do not add InkToolbarEraserKind, SelectedEraser, or other eraser APIs from Windows App SDK 2.4.1-experimental. Version 2.5.4-experimental removed them.
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