Migración de una aplicación para UWP a WinUI 3

UWP ya no está en desarrollo activo. WinUI 3 y el SDK de Aplicaciones para Windows son sus sucesores, y las herramientas de inteligencia artificial pueden automatizar la mayor parte de la migración. El principal desafío es que los modelos de inteligencia artificial se entrenaron en años de ejemplos de UWP, por lo que sin instrucciones reproducen los patrones de los que intentas alejarte. Esta página proporciona a tu agente el contexto que necesita para hacerlo bien.

Instalación del complemento del agente de WinUI

La winui-uwp-migration función gestiona automáticamente las sustituciones comunes:

gh copilot plugin install winui@awesome-copilot

Consulte el complemento del agente de WinUI para obtener todos los detalles.

Tabla de sustitución de API

En las tablas siguientes se resumen las sustituciones de API más comunes. Para obtener la asignación detallada completa (incluidos los miembros, las propiedades y las API menos comunes), consulta Asignación de API y bibliotecas de UWP a la SDK de Aplicaciones para Windows.

Espacios de nombres

Threading

Windowing

Cuadros de diálogo y selectores

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

Notificaciones

Redes y HTTP

Navegación

Patrones de MVVM

dotnet add package CommunityToolkit.Mvvm

Ciclo de vida de la aplicación

Configuración y almacenamiento

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 que no cambian

Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color y la mayoría de las API de WinRT fuera del espacio de nombres XAML no cambian.

Controles sin un equivalente directo

Algunos controles de UWP no existen en WinUI 3. Elija un reemplazo en función de su escenario:

Ink, Win2D e impresión

Estos subsistemas requieren pasos de migración específicos más allá de los cambios en el espacio de nombres.

Windows Ink

Las InkCanvas API y InkPresenter se trasladan a Microsoft.UI.Input.Inking, pero por lo demás son idénticas. El cambio no obvio es CoreInputDeviceTypes:

InkStrokeContainer.SaveAsync() y LoadAsync() todavía requieren IRandomAccessStream. Puente desde flujos System.IO:

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

El nombre del paquete Win2D cambió, pero la superficie de API es idéntica:

Todas las Microsoft.Graphics.Canvas.* API (CanvasDevice, CanvasBitmap, CanvasRenderTarget, DrawInk) funcionan de la misma manera. Solo la referencia del paquete NuGet necesita actualizarse.

Impresión

La impresión de UWP utiliza PrintManager.GetForCurrentView(). WinUI 3 requiere interoperabilidad con el identificador de ventana:

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

Las PrintDocument API de representación (Paginate, GetPreviewPage, AddPages) no se modifican.

Mensaje de inicio

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.

Cambios en el archivo del proyecto

Reemplazar el marco de destino de 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>

Agregue el paquete SDK de Aplicaciones para Windows:

dotnet add package Microsoft.WindowsAppSDK

Contenido relacionado

• guía de migración de SDK de Aplicaciones para Windows: tutorial completo de migración manual
• Asignación de API y bibliotecas para UWP a la SDK de Aplicaciones para Windows: tabla completa de asignación de API
• Lo que se admite al migrar de UWP a WinUI : estado de compatibilidad de características
• Migrar desde WPF