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

WinUI inclut InkCanvas, InkToolbaret InkPresenter en tant qu’API expérimentales dans les versions expérimentales du SDK d'application Windows. Les versions stables ne les incluent pas. Pour la configuration, la personnalisation de la barre d’outils et les limitations connues, consultez Contrôles d’encrage pour les applications WinUI.

Dans les versions expérimentales, les contrôles et les types qui traitent l’entrée manuscrite se trouvent dans Microsoft.UI.Xaml.Controls. Les traits et les attributs de dessin restent dans Windows.UI.Input.Inking:

Chaque type UWP dans les deux premières lignes a un équivalent portant le même nom, mais SDK d'application Windows 2.5.4-experimental n'inclut pas tous leurs membres :

• InkStrokeContainer n’a aucun constructeur public et InkPresenter.StrokeContainer est en lecture seule. Pour basculer entre des ensembles de traits, enregistrez chaque ensemble avec SaveAsync et restaurez-le avec LoadAsync, ce qui remplace les traits actuels.
• SaveAsync et LoadAsync retournent IAsyncAction, de sorte qu’ils ne signalent pas la progression et SaveAsync ne retourne pas le nombre d’octets qu’il a écrits.
• InkStrokeContainer.GetRecognitionResults, InkStrokeContainer.UpdateRecognitionResultset InkInputConfiguration.IsPenHapticFeedbackEnabled ne sont pas disponibles.
• InkToolbarRulerButton.Ruler et l’événement InkToolbar.IsRulerButtonCheckedChanged ne sont pas disponibles. UWP a rendu obsolète InkToolbarRulerButton en faveur de InkToolbarStencilButton, utilisez donc le bouton gabarit et l’événement InkToolbar.IsStencilButtonCheckedChanged à la place.

SDK d'application Windows 2.4.1-experimental a ajouté des API de gomme, telles que InkToolbarEraserKind et InkToolbarEraserButton.SelectedEraser, que la version 2.5.4-experimental a supprimées. Ils n’ont jamais fait partie de UWP, donc ne les ajoutez pas au code migré. Pour obtenir la liste complète, consultez Modifications de la version expérimentale 2.4.1.

Étant donné que les types tels que InkPresenter et InkStrokeContainer existent dans les deux espaces de noms, l’importation des deux Microsoft.UI.Xaml.Controls et Windows.UI.Input.Inking provoque l’erreur CS0104 lorsque vous utilisez ces noms. Importez Microsoft.UI.Xaml.Controlset ajoutez des directives d’alias pour les Windows.UI.Input.Inking types que vous utilisez :

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

InkStrokeContainer.SaveAsync écrit dans un IOutputStream, et LoadAsync lit à partir d’un IInputStream. Pour utiliser des flux de fichiers System.IO, convertissez-les avec AsOutputStream et AsInputStream. Le fichier nécessite using System; pour attendre ces méthodes Windows Runtime, ainsi que using System.IO; et 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);
}

Vous pouvez continuer à connecter la barre d’outils au canevas avec InkToolbar.TargetInkCanvas, ou définir TargetInkPresenter pour la connecter directement à un InkPresenter. Pour ajouter vos propres outils à la barre d’outils, utilisez InkToolbarCustomToolButton et InkToolbarCustomToggleButton, comme indiqué dans Personnaliser la barre d’outils d’entrée manuscrite. Avant de migrer, passez en revue les limitations connues, telles que les problèmes signalés avec la règle et les pochoirs de rapporteur.

Si votre application doit utiliser une version stable, il n’existe aucun contrôle d’entrée manuscrite intégré vers lequel migrer. Affichez des traits avec Win2D et gérez vous-même l’entrée de pointeur, ou utilisez une bibliothèque d’entrée manuscrite tierce. Pour remplacer InkToolbar, utilisez un CommandBar avec des éléments AppBarToggleButton.

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

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