Migrer une application UWP vers WinUI 3

UWP n’est plus en cours de développement actif. WinUI 3 et le SDK d'application Windows sont ses successeurs, et les outils IA peuvent automatiser la majeure partie de la migration. Le principal défi est que les modèles IA ont été formés sur des années d’échantillons UWP. Par conséquent, sans conseils, ils reproduisent les modèles que vous essayez de quitter. Cette page fournit à votre agent le contexte dont il a besoin pour bien faire les choses.

Installer le plug-in de l’agent WinUI

La winui-uwp-migration compétence gère automatiquement les substitutions courantes :

gh copilot plugin install winui@awesome-copilot

Pour plus d’informations, consultez le plug-in de l’agent WinUI .

Table de substitution d’API

Les tableaux suivants résument les substitutions d’API les plus courantes. Pour obtenir le mappage complet et détaillé — y compris les membres, les propriétés et les API moins courantes — consultez Mappage des API et bibliothèques UWP vers le SDK d'application Windows.

Espaces de noms

Thread

Windowing

Boîtes de dialogue et sélecteurs

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

Mise en réseau et HTTP

Navigation

Modèles MVVM

dotnet add package CommunityToolkit.Mvvm

Cycle de vie de l’application

Paramètres et stockage

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 qui ne changent pas

Windows.Devices.*, Windows.Media.*, Windows.UI.ViewManagement.UISettings, Windows.UI.Color et la plupart des API WinRT en dehors de l’espace de noms XAML sont inchangées.

Contrôles sans équivalent direct

Certains contrôles UWP n’existent pas dans WinUI 3. Choisissez un remplacement en fonction de votre scénario :

Encre, Win2D et impression

Ces sous-systèmes nécessitent des étapes de migration spécifiques au-delà des modifications apportées à l’espace de noms.

Windows Ink

Les API InkCanvas et InkPresenter sont déplacées vers Microsoft.UI.Input.Inking, mais sont par ailleurs identiques. Le changement non évident est CoreInputDeviceTypes:

InkStrokeContainer.SaveAsync() et LoadAsync() nécessitent toujours IRandomAccessStream. Pont à partir de flux 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

Le nom du package Win2D a changé, mais la surface de l’API est identique :

Toutes les Microsoft.Graphics.Canvas.* API (CanvasDevice, , CanvasBitmapCanvasRenderTarget, DrawInk) fonctionnent de la même façon. Seule la référence du package NuGet doit être mise à jour.

Impression

L’impression UWP utilise PrintManager.GetForCurrentView(). WinUI 3 nécessite l’interopérabilité du handle de fenêtre :

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

Les PrintDocument API de rendu (Paginate, , GetPreviewPageAddPages) sont inchangées.

Requête de démarrage

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.

modifications apportées au fichier Project

Remplacez le framework cible 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>

Ajoutez le package SDK d'application Windows :

dotnet add package Microsoft.WindowsAppSDK

Contenu connexe

• guide de migration SDK d'application Windows : procédure pas à pas complète de la migration manuelle
• Mappage des API et bibliothèques UWP à l’SDK d'application Windows : table complète de mappage d’API
• Ce qui est pris en charge lors de la migration d’UWP vers WinUI – état de prise en charge des fonctionnalités
• Migrer depuis WPF