Migrer d’UWP vers le SDK d’application Windows avec l’Assistant Mise à niveau .NET

  • Article

L’Assistant Mise à niveau .NET (consultez Vue d’ensemble de l’Assistant Mise à niveau .NET) est une extension Visual Studio (recommandée), et un outil en ligne de commande, qui peut vous aider à migrer une application de plateforme Windows universelle (UWP) C# vers une application de la Bibliothèque d’interface utilisateur Windows (WinUI) 3 utilisant le SDK d’application Windows.

Notre feuille de route pour la prise en charge d’UWP dans l’Assistant Mise à niveau .NET comprend d’autres améliorations d’outils et la prise en charge de la migration pour les nouvelles fonctionnalités. Si vous rencontrez des problèmes liés à l’Assistant Mise à niveau .NET, vous pouvez les signaler dans Visual Studio en sélectionnant Aide>Envoyer des commentaires>Signaler un problème.

Consultez également le dépôt GitHub de l’Assistant Mise à niveau. Les options d’exécution de l’outil sur la ligne de commande sont documentées ici.

Installer l’Assistant Mise à niveau de .NET

Vous pouvez installer l’Assistant Mise à niveau .NET comme une extension Visual Studio ou un outil en ligne de commande .NET. Pour plus d’informations, consultez Installer l’Assistant Mise à niveau .NET.

Résumé

Quand vous utilisez l’Assistant Mise à niveau .NET pour migrer votre application UWP, voici les étapes générales et les phases du processus de migration effectuées par l’outil.

  • Copie éventuellement votre projet et migre la copie : laisse votre projet d’origine inchangé.
  • Migre éventuellement votre projet sur place (dans les mêmes dossiers et fichiers, sans renommer les dossiers) : ne fait pas de copie.
  • Met à niveau votre projet du format .NET Framework vers le dernier format de projet SDK .NET.
  • Nettoie les références de package NuGet. En plus des packages référencés par votre application, le fichier packages.config contient des références aux dépendances de ces packages. Par exemple, si vous avez ajouté une référence au package A, qui dépend du package B, les deux packages sont référencés dans le fichier packages.config. Dans le nouveau système de projet, seule la référence au package A est nécessaire. Cette étape analyse les références de package et supprime celles qui ne sont pas nécessaires. Votre application fait néanmoins toujours référence aux assemblys .NET Framework. Certains de ces assemblys peuvent être disponibles sous forme de packages NuGet. Cette étape analyse ces assemblys et référence le package NuGet approprié.
  • Cible .NET 6 et le SDK d’application Windows.
  • Remplace le moniker de framework cible (TFM) (consultez Frameworks cibles dans les projets de style SDK) .NET Framework par le SDK suggéré. Par exemple, net6.0-windows
  • Migre votre code source UWP de WinUI 2 vers WinUI 3, en effectuant les changements de code propres à la source.
  • Ajoute/met à jour tous les fichiers de modèle, de configuration et de code. Par exemple, ajoute les profils de publication nécessaires, App.xaml.cs, MainWindow.xaml.cs, MainWindow.xaml et autres.
  • Met à jour les espaces de noms et ajoute la navigation MainPage.
  • Tente de détecter et corriger les API qui sont différentes entre UWP et le SDK d’application Windows, et utilise les éléments TODO de la Liste des tâches pour marquer les API qui ne sont plus prises en charge.

Pendant son exécution, l’outil donne également des conseils de migration sous la forme de messages d’avertissement dans la sortie de l’outil, et des éléments TODO de la Liste des tâches sous la forme de commentaires dans le code source de votre projet (par exemple, quand une migration entièrement automatisée de votre code source UWP n’est pas possible). Un élément TODO de la Liste des tâches classique comprend un lien vers une rubrique dans cette documentation de migration. En tant que développeur, vous contrôlez toujours le processus de migration.

Conseil

Pour voir tous les éléments TODO générés par l’outil, consultez la Liste des tâches dans Visual Studio.

Remarque

Une fois l’exécution de l’outil terminée, vous pouvez choisir d’effectuer certaines étapes de suivi si nécessaire. Vous pouvez déplacer votre code de App.xaml.old.cs vers App.xaml.cs, et vous pouvez restaurer AssemblyInfo.cs à partir de la sauvegarde créée par l’outil.

Ce que l’outil prend en charge

Cette version de l’Assistant Mise à niveau .NET est actuellement en préversion et reçoit des mises à jour fréquentes. Actuellement, l’outil prend uniquement en charge le langage de programmation C#, et pas C++. Dans la plupart des cas, avec cette version, votre projet nécessite des efforts supplémentaires de votre part pour terminer la migration.

L’outil migre votre projet ainsi que votre code pour qu’il soit compilé. Toutefois, certaines fonctionnalités demandent une investigation et une correction (via les éléments TODO de la Liste des tâches). Pour plus d’informations sur les éléments à prendre en compte avant la migration, consultez Éléments pris en charge pendant la migration d’UWP vers WinUI 3.

En raison des limitations suivantes de la version actuelle de l’Assistant Mise à niveau .NET, vous pouvez choisir d’attendre une version ultérieure avant de migrer votre application :

  • La migration à partir des API ApplicationView n’est pas prise en charge.
  • La migration à partir d’API liées à AppWindow n’est pas prise en charge.

Si possible, l’outil tente de générer un avertissement, et cela bloque intentionnellement la compilation de votre code tant que vous ne le changez pas.

  • Les vues personnalisées ne sont pas prises en charge. Par exemple, vous ne recevez pas d’avertissement ou de correctif pour une boîte de dialogue personnalisée qui étend MessageDialog et appelle une API de manière incorrecte.
  • Les composants Windows Runtime ne sont pas pris en charge.
  • Les applications multifenêtres peuvent ne pas être migrées correctement.
  • Un projet qui suit une structure de fichier non standard (par exemple, App.xaml et App.xaml.cs qui ne sont pas dans le dossier racine) peut ne pas être migré correctement.

Le dépôt GitHub de l’Assistant Mise à niveau documente des conseils de résolution de problèmes et les problèmes connus. Si vous rencontrez des problèmes pendant l’utilisation de l’outil, signalez-les dans ce même dépôt GitHub, en leur appliquant l’étiquette de domaine UWP. Nous vous en sommes reconnaissants !

Remarque

Pour obtenir des conseils sur le processus de migration (et connaître les différences entre les fonctionnalités et les API UWP/SDK d’application Windows), consultez Migrer d’UWP vers le SDK d’application Windows.

Conseil

Vous pouvez voir votre version de l’outil en envoyant la commande upgrade-assistant --version.

Évaluer l’outil avec l’exemple d’application UWP PhotoLab

Prenons l’Assistant Mise à niveau .NET pour une version d’évaluation.

Comme matériel source, nous migrons l’exemple d’application UWP PhotoLab. PhotoLab est un exemple d’application permettant de consulter et de modifier des fichiers image. Il illustre les fonctionnalités XAML de disposition, de liaison de données et de personnalisation de l’interface utilisateur.

Remarque

Vous pouvez voir une étude de cas de l’exemple PhotoLab migré entièrement manuellement dans Migration vers le SDK d’application Windows de l’exemple d’application UWP PhotoLab.

  1. Commencez par cloner ou télécharger le code source de l’exemple PhotoLab à partir du lien ci-dessus.

Conseil

N’oubliez pas qu’une fois que nous avons utilisé l’outil pour automatiser la migration de l’application, des efforts manuels supplémentaires sont nécessaires pour terminer la migration.

  1. Ouvrez la solution PhotoLab dans Visual Studio.

  2. Après avoir installé l’extension de l’Assistant Mise à niveau .NET (consultez Installer l’Assistant Mise à niveau .NET plus haut dans cette rubrique), cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, puis cliquez sur Mettre à niveau.

  3. Choisissez l’option Mettre à niveau le projet vers une version .NET plus récente.

  4. Choisissez l’option Mise à niveau de projet sur place.

  5. Choisissez un framework cible.

  6. Cliquez sur Mettre à niveau la sélection.

  7. L’Assistant Mise à niveau .NET s’exécute et utilise la fenêtre Sortie de Visual Studio pour imprimer les informations et l’état de progression.

Vous pouvez monitorer la barre de progression jusqu’à ce que l’opération de mise à niveau soit terminée.

La migration de code de l’exemple d’application PhotoLab comprend les éléments suivants :

  • Changements des API Content Dialog et File Save Picker.
  • Mise à jour XAML du package Animations.
  • Affichage des messages d’avertissement et ajout d’éléments TODO de la Liste des tâches dans DetailPage.xaml, DetailPage.xaml.cs et MainPage.xaml.cs pour le bouton Précédent personnalisé.
  • Implémentation de la fonctionnalité du bouton Précédent et ajout d’un élément TODO de la Liste des tâches pour personnaliser le bouton XAML.
  • Vous avez accès à un lien vers la documentation pour en savoir plus sur l’implémentation du bouton Précédent.

Les numéros de version de votre .csproj résultant sont légèrement différents, mais ressemblent essentiellement à ceci (avec certains groupes de propriétés de configuration de build supprimés par souci de concision) :

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
    <OutputType>WinExe</OutputType>
    <DefaultLanguage>en-US</DefaultLanguage>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <EnableMsixTooling>true</EnableMsixTooling>
    <Platforms>x86;x64;arm64</Platforms>
    <PublishProfile>win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>
  <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
      <SubType>Designer</SubType>
    </AppxManifest>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.1.0" />
    <PackageReference Include="Microsoft.Graphics.Win2D" Version="1.0.0.30" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="6.0.0" />
    <PackageReference Include="CommunityToolkit.WinUI.UI.Animations" Version="7.1.2" />
  </ItemGroup>
  <ItemGroup>
    <Compile Remove="App.xaml.old.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="App.xaml.old.cs" />
  </ItemGroup>
</Project>

Comme vous pouvez le voir, le projet référence maintenant le SDK d’application Windows, WinUI 3 et .NET 6. Maintenant que PhotoLab a été migré, vous pouvez tirer parti de toutes les nouvelles fonctionnalités offertes par les applications WinUI 3 et développer votre application avec la plateforme.

Par ailleurs, l’Assistant Mise à niveau .NET ajoute des analyseurs au projet pour aider à poursuivre le processus de mise à niveau. Par exemple, le package NuGet Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers.

Suivi de la migration manuelle

À ce stade, vous pouvez ouvrir la solution ou le projet PhotoLab migré et voir les changements qui ont été effectués dans le code source. Le projet a besoin d’un peu plus de travail pour finir de tout raccorder avant que la version WinUI 3 soit générée, s’exécute et se comporte comme la version UWP.

Consultez la Liste des tâches dans Visual Studio (Afficher>Liste des tâches) afin de connaître les éléments TODO que vous devez actionner pour terminer manuellement la migration.

Il est possible que la version UWP (.NET Framework) de votre application contienne des références de bibliothèque que votre projet n’utilise pas. Vous devez analyser chaque référence et déterminer si elle est nécessaire ou non. L’outil a peut-être aussi ajouté ou mis à niveau une référence de package NuGet vers la mauvaise version.

L’Assistant Mise à niveau ne modifie pas le Package.appxmanifest, qui nécessite des modifications pour lancer l’application :

  1. Ajoutez cet espace de noms à l’élément <Package> racine :
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

  1. Modifiez l’élément <Application> de EntryPoint="appnamehere.App" vers EntryPoint="$targetentrypoint$"

  2. Remplacez toute Capability spécifiée par ceci :

<rescap:Capability Name="runFullTrust" />

Dans votre fichier .csproj, vous devez peut-être modifier le fichier projet pour définir <OutputType>WinExe</OutputType> et <UseMaui>False</UseMaui>.

Pour utiliser un grand nombre de contrôles XAML, vérifiez que votre fichier app.xaml contient <XamlControlsResources>, comme dans cet exemple :

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            <!-- Other merged dictionaries here -->
        </ResourceDictionary.MergedDictionaries>
        <!-- Other app resources here -->
    </ResourceDictionary>
</Application.Resources>

Conseils de dépannage

Plusieurs problèmes connus peuvent se produire lors de l’utilisation de l’Assistant Mise à niveau de .NET. Dans certains cas, il s’agit de problèmes avec l’outil try-convert que l’Assistant Mise à niveau de .NET utilise en interne.

Toutefois, pour d’autres conseils de résolution de problèmes et problèmes connus, consultez le dépôt GitHub de l’Assistant Mise à niveau.