Dot.Blog

Passer des Xamarin.Forms à MAUI est encore plus simple grâce aux outils de migration mis à disposition par Microsoft. Vous avez dit "migration" ? Oui, et voici pourquoi et comment

L’assistant de Migration

Dans les articles précédents j’ai tenté de répondre à quelques questions préliminaires essentielles avant d’envisager de passer à MAUI et de migrer le code existant. Je vais supposer ici que vous avez lu ces articles, que vous avez un projet Xamarin.Forms à migrer et que vous souhaitez faire cette migration.

Allez-vous être seul dans cette migration à vous dépatouiller comme vous le pouvez ? Non.

Qui sera à vos côté ? En dehors de votre serviteur si vous faites appel à ses services, vous pourrez au moins compter sur l’Assistant de Migration que Microsoft offre généreusement pour faciliter un peu les choses.

Il s’agit d’une application qui va se charger non pas de tout migrer, mais au moins de rendre votre projet Xamarin.Forms compatible avec MAUI, par exemple en modifiant les dépendances à Xamarin.Forms et en ajustant certains namespaces. Mais ce n’est qu’une partie de son travail.

L’assistant de Migration Xamarin.Forms vers MAUI est une partie de l’Upgrade Assistant .NET qui couvre les divers assistants afférents aux plateformes ASP.NET MVC, Windows Forms, WPF, UWP/WinUI et Xamarin.Forms. Les assistants pour le mode Console et pour les DLL n’existent pas encore à la date d’écriture de ce billet (voir https://dotnet.microsoft.com/en-us/platform/upgrade-assistant pour se tenir au courant des dernières disponibilités).

Le nécessaire

Pour migrer une App Xamarin.Forms en MAU il faut préparer le terrain, c’est-à-dire au moins avec les bons outils installés.

Je passerai sur le fait qu’il faut un PC branché sur le secteur, qu’il faut que le compteur de la maison soit enclenché et que cela ne tombe pas sur un jour de coupure de courant. Mais outre cette bonne gestion des ressources physiques, il vous faudra surtout ensuite un Visual Studio à jour. Vérifier cet état par le biais de l’installateur de Visual Studio. Au moment où j’écris ces lignes (assez en amont de al sortie réelle de l’article) l’Assistant ne fonctionne que sous Windows, donc ajoutez à la liste des préparatifs, un PC branché sur le secteur un jour sans coupure de courant mais un PC qui tourne sous Windows à jour lui aussi !

Les outils spécifiques

Désormais MAUI est installé avec Visual Studio, si tel n’était pas le cas chez vous tapez la commande suivante sous Console : 

Dotnet workload install maui

Si vous avez déjà effectué cette manip, ou si votre Visual Studio a lui-même installé les outils MAUI, vous n’avez pas à répéter cette opération. Elle doit être effectuée une fois seulement.

Il faut maintenant installer l’Assistant de mise à niveau Microsoft

Il est important de noter que cette application ne peut pas traduire indépendamment les applications Xamarin.Forms en MAUI. Elle offre juste une aide pour le processus de mise à niveau.

C'est pourquoi l'application demande des instructions lors de son exécution, vous ne pouvez donc pas laisser la machine fonctionner pendant que vous allez discuter à la machine à café 🙂

Lancer l’Assistant

Changez le répertoire de votre invite de commande pour aller dans le répertoire où est stocké le fichier .sln (solution Visual Studio) à traiter.

Tapez alors :

upgrade-assistant upgrade SolutionName.sln

Attention à la sortie de la console. Si tout se passe bien, votre solution peut être transformée en maui sans problème.

Dans la section d'en-tête de la sortie de la console, vous verrez quelles étapes sont requises (ou suggérées) pour terminer la migration. Vous pouvez décider quoi faire de l'étape suivante : appliquer, ignorer ou faire autre chose. Si tout se passe bien, vous n'aurez qu'à appuyer sur Appliquer.

Une fois que vous avez terminé le processus de l'assistant de mise à niveau, vous pouvez regarder les modifications apportées sous Visual Studio. Principalement dans les codes sources et les fichiers de projet.

Par exemple la modification des espaces de noms (ici mis en évidence avec un différentiel entre le projet original et le projet migré par l’Assistant) :

On note ici que le « using Xamarin.essentials » a été supprimé de ce morceau de code et que d’autres namespaces apparaissent comme Microsoft.Maui, ou Microsoft.Maui.Essentials justement (les Essentials font désormais parti des paquets installés par défaut, plus besoin de le faire à la main quand on créé un nouveau projet).

C’est fini !

Et oui c’est fini ! Enfin pour ce qui est du travail de l’Assistant et de ces diverses propositions que vous aurez suivies ou non ou que vous appliquerez plus tard dans le processus de migration car il restera ici et là des ajustements à faire très certainement (surtout si la taille de l’App est importante).

Comme dans toute migration, plus le code de départ est académiquement propre et conforme aux bonnes règles d’écriture, moins il utilise de code tiers ou de contrôles externes, plus la migration « automatique » sera simple et directe. Dans le cas contraire il y aura un travail plus ou moins important à fournir pour mettre l’ensemble du code au diapason, voire réécrire certaines parties trop dépendantes d’anciens composants non mis à jour, etc. 

Trucs à savoir

Adresse de l’assistant : https://dotnet.microsoft.com/en-us/platform/upgrade-assistant  

Manuel de Migration (mis à jour assez souvent) : https://github.com/dotnet/maui/wiki/Migrating-from-Xamarin.Forms-(Preview) 

Je vous conseille après le téléchargement de l’assistant de prendre connaissance des diverses docs ou vidéos mises en ligne sur ce site par Microsoft. Les derniers conseils à jour pour la migration s’y trouveront car ils peuvent varier dans le temps (améliorations diverses notamment).

Pour l’instant, mais cela peut changer, seuls les projets iOS et Android sont pris en charge. Les projets UWP ou tvOS ou WatchOS ne le sont pas.

Parmi les choses à savoir :

• La documentation .NET MAUI est mise à jour presque tous les jours avec de la documentation sur les contrôles, les mises en page, les gestes (à peu près tout !!!) et est l'endroit idéal pour vérifier les nouvelles API ou comment enregistrer des contrôles personnalisés ou créer de nouveaux contrôles personnalisés via des gestionnaires.
• Migration iOS .NET6.0 : propriétés du fichier de projet
• Migration Android .NET6.0 : propriétés du fichier de projet
• Pour construire et exécuter les projets migrés via dotnet cli utilisez les commandes suivantes :   -t:Run exécutera l'application, donc pour ne  faire qu’un build de l’App, adaptez la commande en supprimant -t :run )
• iOS : dotnet build <path_to_iOS_csproj_file> -f net6.0-ios -c Debug -t:Run
• Android: dotnet build <path_to_Android_csproj_file> -f net6.0-ios -c Debug -t:Run
• Si vous rencontrez des problèmes de build dans VS2022 ou si l'application se construit mais ne se déploie pas, vérifiez le mappage de configuration pour votre solution et sélectionnez les options appropriées.
• Attendez-vous à de nombreux conflits d'espaces de noms ou à l'ajout d'un grand nombre d'alias et de chemins complets au lieu de simples instructions using.

On n’oubliera pas que les fichiers XAML sont aussi concernés, notamment par la présence de namespaces ou de référence à des contrôles qui doivent eux-aussi être migrés.

Il y a aussi à prendre en compte les changement d’API, tout n’est pas rigoureusement identique sous MAUI… Et heureusement car cela signifie que certaines erreurs ou incohérences ont été suprimées en profitant du passage à la nouvelle plateforme ! Toutefois il vous faudra en tenir compte…

Comme par exemple :

• Colors est maintenant dans Microsoft.Maui.Graphics
• Shapes est dans Microsoft.Maui.Controls
• Color.Default n’existe plus !  == utiliser ClearValue si vous le pouvez à la place
• Copier les styles par default fournis avec MUI pour une meilleur expérience.
• Color == Colors For exemple: Colors.Red;
• Frame: BorderColor= "Accent" n’existe pas
• ToolbarItem: Icon == IconImageSource
• Button: Image == ImageSource
• Span ForegroundColor n’existe pas
• OSTheme == AppTheme

Dernière chose, pour l’instant l’Assistant met à jour le code, en tout cas ce que j’ai présenté ici, mais il ne transforme la solution Xamarin.Forms en Projet Unique MAUI. Cette opération devra être effectuée à la main. Néanmoins les outils et docs étant en Preview pour certains je vous conseille de vous référer à la documentation officielle Microsoft au moment où vous aurez à utiliser l’Assistant pour prendre connaissance des dernières améliorations.

Autres sources à lire : 

https://github.com/dotnet/maui/wiki/Migrating-from-Xamarin.Forms-(Preview) 

Et pour migrer les DLL alors ?

L’assistant de migration ne couvre pas encore les DLL, avant de vous lancer regarder les sites Microsoft indiqués ici car la situation peut avoir changé. Mais si les choses restent en l’état, il faudra migrer à la main.

Refactoriser ou réécrire ou bifurquer ?

Votre bibliothèque SDK Xamarin.Forms cible probablement .NET Standard, Xamarin.iOS et Xamarin.Android. Une partie de votre code peut être prête à être utilisée, d'autres non. Vous passerez par un processus impliquant le tri des projets et la détermination de ce qu'il faut mettre à niveau, abandonner ou réécrire.

Une fois que vous avez updaté les frameworks cibles vers .net6.0 net6.0-ios net6.0-android,  vous devrez examiner chacun de vos projets un par un et voir si vous rencontrez des problèmes de compatibilité. Vous constaterez peut-être que vous n'avez tout simplement rien à faire. Et dans certains cas, vous devrez peut-être mettre à jour du code.

La refactorisation implique la mise à jour du code existant pour qu'il fonctionne dans le nouvel environnement sous .NET 6.

La bifurcation consiste à copier l'ancien code et à le coller dans un nouveau projet .NET 6. Si vous venez de .NET Standard, vous n'avez probablement pas besoin de le faire, mais vous devrez peut-être mettre à jour certains espaces de noms.

Comprendre vos dépendances

Si votre bibliothèque a des dépendances sur d'autres bibliothèques ou projets, vous devriez prendre le temps d'examiner leurs dépendances et de déterminer ce que vous pouvez ou ne pouvez pas migrer. Les packages NuGet externes dont dépendent vos projets ne peuvent pas cibler Xamarin.iOS ou Xamarin.Android ; ils doivent plutôt cibler .net6.0-ios et net6.0-android.

Mettre à niveau le projet CSPROJ

Le nouveau format CSPROJ est connu sous le nom de style SDK.

🚨IMPORTANT🚨

Si votre librairie utilise le SDK, vous devez le changer pour utiliser :MSBuild.Sdk.ExtrasMicrosoft.NET.Sdk

<!-- Old SDK reference -->
<Project Sdk="MSBuild.Sdk.Extras">
   ...
</Project>
<!-- New SDK reference -->
<Project Sdk="Microsoft.NET.Sdk">
   ...
</Project>

Mettre en œuvre le multiciblage d'un projet unique

Pour en savoir plus sur Single-Project Multitargeting , je vous recommande de lire d'abord la documentation de Microsoft ainsi que mes articles précédents.

Lorsque vos projets utilisent le format de projet SDK Style, vous pouvez cibler plusieurs frameworks dans le même projet en utilisant <TargetFrameworks>:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net6.0;net6.0-android;net6.0-ios</TargetFrameworks>
    ...
  </PropertyGroup>
</Project>

Résoudre les problèmes de code

Le ciblage des nouveaux frameworks .NET 6 peut entraîner des problèmes de compilation et de dépendance. Certaines bibliothèques .NET peuvent ne pas avoir de versions compatibles avec .NET 6. Vous devrez corriger tous les problèmes de compilateur qui apparaissent.

S'il manque une bibliothèque que vous utilisez dans .NET 6, vous devrez trouver une alternative ou écrire le code vous-même. La meilleure chose à faire est de la remplacer par une bibliothèque plus récente et prise en charge.

Vous pouvez en profiter pour refactoriser votre code existant et ajouter des tests unitaires. Vous devriez pouvoir mettre à niveau tous vos projets sans trop modifier le code d'origine.

Tirez parti du code existant

Votre code précédent peut toujours fonctionner sur .NET 6 avec quelques petits ajustements, vous pouvez donc généralement trouver un moyen de réutiliser votre code.

Gardez les noms de fichiers identiques pendant tout le processus. Si vous déplacez des fichiers dans de nouveaux dossiers, etc., vous aurez beaucoup de difficulté à les fusionner.

Si vous souhaitez que vos bibliothèques soient consommées par la communauté .NET MAUI, vous devez mettre à jour votre bibliothèque pour prendre en charge .net6.0 net6.0-ios et net6.0-android.

Conclusion

Bref on s’en serait douté, comme dans toute migration de code, les assistants ne font pas tout. La qualité du code de départ influe grandement sur le fonctionnement de ces outils qui partent du principe que le code est bien écrit, ce qui n’est pas toujours le cas… De même que les assistants de ce type supposent général, et c’est le cas ici, que le projet à migrer n’est pas un code à l’abandon et qu’il a été maintenu. Par exemple à la date où j’écris ces lignes seuls les projets Xamarin.Forms en 4.8 et plus sont pris en charge. Si vous avez de vieux projets Xamarin.Forms qui n’ont pas été mis à jour depuis des années, vous aurez une phase préliminaire à exécuter : les passer en Xamarin.Forms 5 !

De plus l’écriture de code informatique reste une activité très humaine, pour l’instant impossible à faire réaliser par une IA car du code c’est une forme d’écriture, de phraséologie, de grammaire, et surtout comme tout langage humain cela véhicule du sens, patent mais aussi latent ! L’intention du développeur est essentielle à connaître. Un humain expérimenté saura retrouver les intentions et corriger en conséquence. Un Assistant automatique n’a absolument pas cette capacité et aura tendance à introduire des incohérences liées à sa totale incompréhension des intentions humaines derrière le code écrit.

C’est pour cela qu’une migration réussie ne dépend pas tant de l’outillage que de la présence de développeurs expérimentés, voire de conseils venant de l’extérieur et ayant acquis l’expérience de telles migration.