Migrera en UWP-app till WinUI 3

UWP är inte längre under aktiv utveckling. WinUI 3 och Windows App SDK är dess efterföljare – och AI-verktyg kan automatisera större delen av migreringen. Den största utmaningen är att AI-modeller har tränats på år av UWP-exempel, så utan vägledning återskapar de mönster som du försöker flytta bort från. Den här sidan ger din agent den kontext den behöver för att få det rätt.

Installera plugin-programmet för WinUI-agenten

Färdigheten winui-uwp-migration hanterar de vanliga ersättningarna automatiskt:

gh copilot plugin install winui@awesome-copilot

Se Plugin-programmet för WinUI-agenten för fullständig information.

API-ersättningstabell

I följande tabeller sammanfattas de vanligaste API-ersättningarna. Fullständig detaljerad mappning – inklusive medlemmar, egenskaper och mindre vanliga API:er – finns i Mappa UWP-API:er och bibliotek till Windows App SDK.

Namnområden

Trådning

Windowing

Dialogrutor och väljare

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

Notifications

Nätverk och HTTP

Navigering

MVVM-mönster

dotnet add package CommunityToolkit.Mvvm

Appens livscykel

Inställningar och lagring

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:er som inte ändras

Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color och de flesta WinRT-API:er utanför XAML-namnområdet ändras inte.

Kontroller utan direkt motsvarighet

Vissa UWP-kontroller finns inte i WinUI 3. Välj en ersättning baserat på ditt scenario:

Pennanteckning, Win2D och utskrift

Dessa undersystem kräver specifika migreringssteg utöver namnområdesändringar.

Windows Ink

InkCanvas API:erna och InkPresenter flyttas till Microsoft.UI.Input.Inking men är i övrigt identiska. Den enda icke-uppenbara ändringen är CoreInputDeviceTypes:

InkStrokeContainer.SaveAsync() och LoadAsync() kräver fortfarande IRandomAccessStream. Överbrygga från System.IO strömmar:

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

Win2D-paketnamnet ändrades men API-ytan är identisk:

Alla Microsoft.Graphics.Canvas.* API:er (CanvasDevice, CanvasBitmap, CanvasRenderTarget, DrawInk) fungerar på samma sätt. Endast NuGet-paketreferensen behöver uppdateras.

Skriva ut

UWP-utskrift använder PrintManager.GetForCurrentView(). WinUI 3 kräver samverkan med fönsterhandtag:

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

Renderings-API PrintDocument :erna (Paginate, GetPreviewPage, AddPages) är oförändrade.

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.

Ändringar i projektfilen

Ersätt UWP-målramverket:

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

Lägg till Windows App SDK-paketet:

dotnet add package Microsoft.WindowsAppSDK

Relaterat innehåll

• Windows App SDK migreringsguide – fullständig manuell migreringsgenomgång
• Mappa UWP-API:er och bibliotek till Windows App SDK – omfattande API-mappningstabell
• Vad stöds när du migrerar från UWP till WinUI – funktionssupportstatus
• Migrera från WPF