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

WinUI innehåller InkCanvas, InkToolbaroch InkPresenter som experimentella API:er i experimentella versioner av Windows App SDK. De ingår inte i stabila utgåvor. Information om installation, anpassning av verktygsfält och kända begränsningar finns i Inmatningskontroller med pennstöd för WinUI-appar.

I experimentella versioner finns kontrollerna och de typer som bearbetar pennindata i Microsoft.UI.Xaml.Controls-namnområdet. Linjer och ritattribut finns kvar i Windows.UI.Input.Inking:

Varje UWP-typ i de två första raderna har en motsvarighet med samma namn, men Windows App SDK 2.5.4-experimental innehåller inte alla deras medlemmar:

• InkStrokeContainer har ingen offentlig konstruktor och InkPresenter.StrokeContainer är skrivskyddad. Om du vill växla mellan uppsättningar med streck sparar du varje uppsättning med SaveAsync och återställer den med LoadAsync, vilket ersätter de aktuella strecken.
• SaveAsync och LoadAsync returnerar IAsyncAction, så att de inte rapporterar förlopp och SaveAsync returnerar inte antalet byte som skrevs.
• InkStrokeContainer.GetRecognitionResults, InkStrokeContainer.UpdateRecognitionResultsoch InkInputConfiguration.IsPenHapticFeedbackEnabled är inte tillgängliga.
• InkToolbarRulerButton.Ruler och händelsen InkToolbar.IsRulerButtonCheckedChanged är inte tillgängliga. UWP har fasats ut till förmån för InkToolbarStencilButton, så använd stencilknappen och händelsen InkToolbar.IsStencilButtonCheckedChanged i stället.

Windows App SDK 2.4.1-experimental lade till raderings-API:er, såsom InkToolbarEraserButton.SelectedEraser och InkToolbarEraserKind, som 2.5.4-experimental tog bort. De ingick aldrig i UWP, så lägg inte till dem i migrerad kod. Den fullständiga listan finns i Ändringar från 2.4.1-experimental.

Eftersom typer som InkPresenter och InkStrokeContainer finns i båda namnrymderna, orsakar import av båda Microsoft.UI.Xaml.Controls och Windows.UI.Input.Inking felet CS0104 när du använder dessa namn. Importera Microsoft.UI.Xaml.Controlsoch lägg till aliasdirektiv för de Windows.UI.Input.Inking typer som du använder:

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

InkStrokeContainer.SaveAsync skriver till en IOutputStream, och LoadAsync läser från en IInputStream. Om du vill använda System.IO filströmmar konverterar du dem med AsOutputStream och AsInputStream. Filen måste using System; invänta dessa Windows Runtime metoder, tillsammans med using System.IO; och 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);
}

Du kan fortsätta att ansluta verktygsfältet till arbetsytan med InkToolbar.TargetInkCanvaseller ställa in TargetInkPresenter för att ansluta det direkt till en InkPresenter. Om du vill lägga till egna verktyg i verktygsfältet använder du InkToolbarCustomToolButton och InkToolbarCustomToggleButton, som du ser i Anpassa verktygsfältet för pennanteckning. Innan du migrerar bör du granska de kända begränsningarna, till exempel rapporterade problem med linjalen och gradmallarna.

Om din app måste använda en stabil version finns det ingen inbyggd inmatningskontroll för pennskrift att migrera till. Rendera linjer med Win2D och hantera pekarindata själv, eller använd ett pennanteckningsbibliotek från tredje part. Om du vill ersätta InkToolbaranvänder du en CommandBar med AppBarToggleButton objekt.

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

Ä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