Eseguire la migrazione di un'app UWP a WinUI 3

La piattaforma UWP non è più in fase di sviluppo attivo. WinUI 3 e il SDK per app di Windows sono i suoi successori e gli strumenti di intelligenza artificiale possono automatizzare la maggior parte della migrazione. La sfida principale è che i modelli di intelligenza artificiale sono stati sottoposti a training su anni di esempi UWP, quindi senza indicazioni riproducono i modelli da cui si sta tentando di allontanarsi. Questa pagina fornisce all'agente il contesto necessario per farlo correttamente.

Installare il plug-in dell'agente WinUI

La winui-uwp-migration competenza gestisce automaticamente le sostituzioni comuni:

gh copilot plugin install winui@awesome-copilot

Per informazioni dettagliate, vedere il plug-in dell'agente WinUI .

Tabella di sostituzione API

Le tabelle seguenti riepilogano le sostituzioni API più comuni. Per la mappatura completa e dettagliata, inclusi membri, proprietà e API meno comuni, consulta Mappatura delle API e delle librerie UWP a SDK per app di Windows.

Namespaces

Gestione dei thread

Windowing

Dialoghi e selezione

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

Notifiche

Rete e HTTP

Navigation

Modelli MVVM

dotnet add package CommunityToolkit.Mvvm

Ciclo di vita dell'app

Impostazioni e archiviazione

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 che non cambiano

Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color e la maggior parte delle API WinRT all'esterno dello spazio dei nomi XAML rimane invariata.

Controlli senza un equivalente diretto

Alcuni controlli UWP non esistono in WinUI 3. Scegliere una sostituzione in base al proprio scenario:

input penna, Win2D e stampa

Questi sottosistemi richiedono passaggi di migrazione specifici oltre le modifiche dello spazio dei nomi.

Windows Ink

Le InkCanvas API e InkPresenter passano a Microsoft.UI.Input.Inking ma sono altrimenti identiche. Una modifica non ovvia è CoreInputDeviceTypes:

InkStrokeContainer.SaveAsync() e LoadAsync() richiedono IRandomAccessStreamancora . Ponte dai System.IO flussi:

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

Il nome del pacchetto Win2D è stato modificato ma la superficie dell'API è identica:

Tutte le Microsoft.Graphics.Canvas.* API (CanvasDevice, CanvasBitmap, CanvasRenderTarget, DrawInk) funzionano allo stesso modo. È necessario aggiornare solo il riferimento al pacchetto NuGet.

Stampa

La stampa UWP usa PrintManager.GetForCurrentView(). WinUI 3 richiede l'interoperabilità con l'handle di finestra:

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

Le PrintDocument API di rendering (Paginate, GetPreviewPage, AddPages) sono invariate.

Prompt di avvio

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.

Modifiche ai file di progetto

Sostituire il framework di destinazione UWP:

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

Aggiungere il pacchetto SDK per app di Windows:

dotnet add package Microsoft.WindowsAppSDK

Contenuti correlati

• SDK per app di Windows guida alla migrazione : procedura dettagliata completa per la migrazione manuale
• Mappatura delle API e delle librerie UWP a SDK per app di Windows — tabella completa di mappatura delle API
• Cosa è supportato durante la migrazione da UWP a WinUI : stato del supporto delle funzionalità
• Eseguire la migrazione da macchine virtuali Windows