Partager via

Créer un plan de portage

Avant de passer directement au code, prenez le temps d’effectuer les étapes de pré-migration recommandées. Cet article vous donne un aperçu des types de problèmes que vous pouvez rencontrer et vous aide à décider d’une approche qui est la plus logique.

Importante

Le port d'API a été abandonné au profit de l'analyse binaire avec l'outil Assistant de mise à niveau .NET. Le service backend du port API a été fermé. Pour utiliser l’outil, vous devrez l’utiliser hors connexion. Pour plus d’informations, consultez README du port API .NET.

Porter votre code

Veillez à suivre les conditions préalables au portage du code avant de continuer. Soyez prêt à choisir la meilleure approche pour vous et à commencer le portage du code.

Importante

L’Assistant Mise à niveau .NET est officiellement obsolète. Utilisez plutôt l’agent de conversation de modernisation GitHub Copilot , qui est inclus avec Visual Studio 2026 et Visual Studio 2022 17.14.16 ou version ultérieure. Cet agent analyse vos projets et vos dépendances, produit un plan de migration pas à pas avec des recommandations ciblées et des correctifs de code automatisés, et valide chaque modification afin de pouvoir valider ou restaurer. Il automatise les tâches courantes de portage : mise à jour des fichiers projet, remplacement des API déconseillées et résolution des problèmes de génération, afin de pouvoir moderniser plus rapidement avec moins d’efforts manuels.

Se concentrer principalement sur le compilateur

Cette approche fonctionne bien pour les projets de faible envergure ou les projets qui utilisent un nombre restreint d’API .NET Framework. Elle est simple :

  1. Si vous le souhaitez, exécutez ApiPort sur votre projet. Si vous exécutez ApiPort, prenez connaissance du rapport sur les problèmes que vous devrez résoudre.
  2. Copiez tout votre code dans un nouveau projet .NET.
  3. Pendant que vous vous référez au rapport de portabilité (s’il a été généré), résolvez les erreurs du compilateur jusqu’à ce que le projet se compile intégralement.

Bien qu’elle ne soit pas structurée, cette approche axée sur le code résout souvent rapidement les problèmes. Un projet contenant uniquement des modèles de données pourrait constituer un candidat idéal à cette approche.

Restez sur .NET Framework jusqu’à ce que les problèmes de portabilité soient résolus

Cette approche est peut-être la meilleure si vous préférez avoir du code compilable pendant tout le processus. L’approche est la suivante :

  1. Exécutez ApiPort sur un projet.
  2. Résolvez les problèmes en utilisant différentes API portables.
  3. Notez toutes les zones où vous n’avez pas la possibilité d’utiliser une solution de rechange directe.
  4. Répétez les étapes précédentes pour tous les projets à porter jusqu’à ce que vous ayez la certitude que tous sont prêts à être copiés dans un nouveau projet .NET.
  5. Copiez le code dans un nouveau projet .NET.
  6. Résolvez tous les problèmes pour lesquels vous avez noté qu’il n’existe pas de solution de rechange directe.

Cette approche prudente est plus structurée que celle qui consiste à résoudre simplement les erreurs de compilation, mais elle reste relativement centrée sur le code et présente l’avantage de toujours conserver du code compilable. Les moyens de résoudre les problèmes qui n’ont pas pu être traités en utilisant simplement une autre API peuvent varier considérablement. Il peut être nécessaire de développer un plan plus complet pour certains projets, ce qui est couvert par l’approche suivante.

Développer un plan d’attaque complet

Cette approche est peut-être la meilleure pour les projets complexes et de grande envergure, dans lesquels il peut être nécessaire de restructurer le code ou de réécrire complètement certains passages pour prendre en charge .NET. L’approche est la suivante :

  1. Exécutez ApiPort sur un projet.

  2. Déterminez les endroits où chaque type non portable est utilisé et l’impact sur la portabilité globale.

    • Déterminez la nature de ces types. Sont-ils peu nombreux mais fréquemment utilisés ? Sont-ils nombreux mais rarement utilisés ? Leur utilisation est-elle concentrée ou est-elle répartie à travers tout le code ?
    • Est-il facile d’isoler le code non portable, afin de le traiter plus facilement ?
    • Faut-il refactoriser le code ?
    • Pour les types qui ne sont pas portables, y a-t-il des API alternatives qui accomplissent la même tâche ? Par exemple, si vous utilisez la classe WebClient, utilisez la classe HttpClient à la place.
    • Existe-t-il d’autres API portables permettant d’accomplir une tâche, même s’il ne s’agit pas d’un remplacement immédiat ? Par exemple, si vous utilisez XmlSchema pour analyser le code XML, mais que vous n’avez pas besoin de la détection de schéma XML, vous pouvez utiliser les API System.Xml.Linq et implémenter l’analyse par vous-même au lieu de dépendre d’une API.

  3. Si vous avez des assemblys difficiles à porter, est-il intéressant de les laisser sur le .NET Framework pour l’instant ? Voici quelques éléments à prendre en considération :

    • Certaines des fonctionnalités de votre bibliothèque pourraient ne pas être compatibles avec .NET, car elles dépendent trop des fonctionnalités propres à .NET Framework ou à Windows. Cela vaut-il la peine de laisser cette fonctionnalité de côté pour le moment et de publier une version .NET temporaire de votre bibliothèque avec moins de fonctionnalités jusqu’à ce que des ressources soient disponibles pour porter ces fonctionnalités ?
    • Une refactorisation serait-elle utile ?

  4. Est-il raisonnable d’écrire votre propre implémentation d’une API .NET Framework non disponible ?

    Vous pouvez envisager de copier, de modifier et d’utiliser du code provenant de la source de référence de .NET Framework. Le code source de référence est sous licence du MIT, ce qui vous laisse la liberté d’utiliser la source comme base pour votre propre code. Veillez simplement à mentionner correctement ce qui est propriété de Microsoft dans votre code.

  5. Répétez ce processus si nécessaire pour les différents projets.

La phase d’analyse peut prendre un certain temps, selon la taille de votre code base. Passer du temps sur cette phase pour déterminer précisément l’étendue des modifications nécessaires et pour développer un plan fait en général gagner du temps finalement, en particulier en cas de codebase complexe.

Votre plan peut impliquer des modifications importantes de votre codebase tout en continuant à cibler .NET Framework 4.7.2. Cela en fait une version plus structurée de l’approche précédente. La mise en œuvre du plan dépend du code base.

Approche mixte

Il est probable que vous allez combiner les approches ci-dessus de façon différente selon les projets. Faites ce qui a le plus de sens pour vous et pour votre codebase.

Transférer vos tests

La meilleure façon de vérifier que tout fonctionne quand vous avez porté votre code est de tester votre code quand vous l’avez porté sur .NET. Pour cela, vous devez utiliser une infrastructure de test qui génère et exécute des tests pour .NET. Vous avez actuellement trois options :

En définitive, le travail de portage dépend fortement de la structuration du code .NET Framework. Il est recommandé de commencer par la base de votre bibliothèque, qui constitue les composants fondamentaux de votre code pour le portage. Il peut s’agir de modèles de données ou d’autres classes et méthodes fondamentales utilisées directement ou indirectement par tout le reste.

  1. Portez le projet de test qui teste la couche en cours de portage de votre bibliothèque.
  2. Copiez la base de votre bibliothèque dans un nouveau projet .NET et sélectionnez la version de .NET Standard que vous voulez prendre en charge.
  3. Apportez les modifications nécessaires pour compiler le code. Il est possible que la plupart nécessitent l’ajout de dépendances de package NuGet à votre fichier csproj.
  4. Exécutez les tests et procédez aux ajustements nécessaires.
  5. Sélectionnez la couche suivante de code à porter et répétez les étapes précédentes.

Si vous commencez par la base de votre bibliothèque et que vous vous déplacez vers l’extérieur en testant chaque couche au fur et à mesure, le portage devient un processus systématique où les problèmes sont isolés sur une seule couche de code à la fois.

Étapes suivantes

  • Last updated on