Analyseur de portabilité .NET

Remarque

API Port est désormais déprécié au profit de l’analyse binaire effectuée par l’Assistant 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.

Vous voulez que vos bibliothèques prennent en charge plusieurs plateformes ? Vous souhaitez voir combien de travail est nécessaire pour que votre application .NET Framework s’exécute sur .NET Core ? L’analyseur de portabilité .NET est un outil qui analyse les assemblys et fournit un rapport détaillé sur les API .NET manquantes pour que les applications ou bibliothèques soient portables sur vos plateformes .NET ciblées spécifiées. L’Analyseur de portabilité est proposé comme Extension Visual Studio, qui analyse un assembly par projet, et comme application console ApiPort, qui analyse les assemblys par fichier ou répertoire spécifié.

Une fois que vous avez converti votre projet pour cibler la nouvelle plateforme, comme .NET Core, vous pouvez utiliser l’analyseur de compatibilité de plateforme basé sur Roslyn pour identifier les API qui lèvent des exceptions PlatformNotSupportedException et d’autres problèmes de compatibilité.

Cibles courantes

• .NET Core : possède une conception modulaire, prend en charge l’installation côte à côte et cible des scénarios multiplateformes. L’installation côte à côte vous permet d’adopter de nouvelles versions de .NET Core sans interrompre les autres applications. Si votre objectif est de porter votre application vers .NET Core et de prendre en charge plusieurs plateformes, c’est la cible recommandée.
• ;NET Standard : Inclut les API .NET Standard disponibles sur toutes les implémentations de .NET. Si votre objectif consiste à faire en sorte que votre bibliothèque s’exécute sur toutes les plateformes prises en charge par .NET, c’est la cible recommandée.
• ASP.NET Core : Infrastructure web moderne reposant sur .NET Core. Si votre objectif est de porter votre application web vers .NET Core pour prendre en charge plusieurs plateformes, c’est la cible recommandée.
• .NET Core + Extensions de plateforme : Inclut les API .NET Core en plus du Pack de compatibilité Windows, qui fournit un grand nombre de technologies .NET Framework disponibles. Il s’agit d’une cible recommandée pour le portage de votre application depuis le .NET Framework vers .NET Core sur Windows.
• .NET Standard + Extensions de plateforme : Inclut les API .NET Standard en plus du Pack de compatibilité Windows, qui fournit un grand nombre de technologies .NET Framework disponibles. Il s’agit d’une cible recommandée pour le portage de votre bibliothèque depuis le .NET Framework vers .NET Core sur Windows.

Comment utiliser l’Analyseur de portabilité .NET

Pour commencer à utiliser l’Analyseur de portabilité .NET dans Visual Studio, vous devez d’abord télécharger l’extension à partir du Visual Studio Marketplace et l’installer. Il fonctionne sur les versions Visual Studio 2017 et Visual Studio 2019.

Important

L’analyseur de portabilité .NET n’est pas pris en charge dans Visual Studio 2022.

Configurer-la dans Visual Studio via Analyser>Paramètres de l’Analyseur de portabilité et choisir vos plateformes cibles, c’est-à-dire les plateformes/versions .NET dont vous souhaitez évaluer les écarts de portabilité en les comparant à la plateforme/version avec laquelle votre assembly actuel est créé.

Vous pouvez aussi utiliser l’application console ApiPort et la télécharger à partir du référentiel ApiPort. Vous pouvez utiliser l’option de commande listTargets pour afficher la liste des cibles disponibles, puis sélectionner les plateformes cibles en spécifiant l’option de commande -t ou --target.

Vue d’ensemble de la solution

Une étape utile dans l’analyse d’une solution avec de nombreux projets consisterait à visualiser les dépendances pour comprendre quel sous-ensemble d’assemblys dépendent de quoi. La recommandation générale est d’appliquer les résultats de l’analyse dans une approche ascendante en commençant par les nœuds terminaux dans un graphique des dépendances.

Pour le récupérer, vous pouvez exécuter la commande suivante :

ApiPort.exe analyze -r DGML -f [directory or file]

Le résultat ressemble à ce qui suit lors de l’ouverture dans Visual Studio :

Analyser la portabilité

Pour analyser l’ensemble de votre projet dans Visual Studio, cliquez avec le bouton droit sur votre projet dans l’Explorateur de solutions et sélectionnez Analyser la portabilité des assemblys. Sinon, accédez au menu Analyser et sélectionnez Analyser la portabilité des assemblys. À partir de là, sélectionnez l’exécutable ou la DLL de votre projet.

Vous pouvez également utiliser l’application console ApiPort.

Tapez la commande suivante pour analyser le répertoire actuel :

ApiPort.exe analyze -f .

Pour analyser une liste spécifique de fichiers .dll, tapez la commande suivante :

ApiPort.exe analyze -f first.dll -f second.dll -f third.dll

Pour cibler une version spécifique, utilisez le paramètre -t :

ApiPort.exe analyze -t ".NET, Version=5.0" -f .

Exécuter ApiPort.exe -? pour obtenir plus d’aide.

Il est recommandé d’inclure tous les fichiers exe et dll associés dont vous êtes propriétaire et que vous souhaitez porter, et d’exclure les fichiers dont dépend votre application, mais dont vous n’êtes pas propriétaire et que vous ne pouvez pas porter. Vous obtiendrez ainsi le rapport de portabilité le plus pertinent possible.

Consulter et interpréter les résultats de portabilité

Seules les API qui ne sont pas prises en charge par une plateforme cible apparaissent dans le rapport. Après avoir exécuté l’analyse dans Visual Studio, vous verrez s’afficher un lien vers le fichier du rapport de portabilité .NET. Si vous avez utilisé l’application console ApiPort, votre rapport de portabilité de .NET est enregistré en tant que fichier dans le format que vous avez spécifié. Le format par défaut est un fichier Excel (.xlsx) dans votre répertoire actuel.

Synthèse de la portabilité

La section sur la synthèse de la portabilité du rapport montre le pourcentage de portabilité de chaque assembly inclus lors de l’exécution. Dans l’exemple précédent, 71,24 % des API .NET Framework utilisées dans l’application svcutil sont disponibles dans .NET Core + Extensions de plateforme. Si vous exécutez l’outil Analyseur de portabilité .NET sur plusieurs assemblys, chaque assembly doit avoir une ligne dans le rapport de synthèse de la portabilité.

Détails

La section des détails du rapport liste les API manquantes de l’une des plateformes cibles sélectionnées.

• Type cible : le type a une API manquante dans une plateforme cible
• Membre cible : la méthode est manquante dans une plateforme cible
• Nom de l’assembly : assembly .NET Framework dans lequel réside l’API manquante.
• Chacune des plateformes cibles sélectionnées correspond à une colonne, telle que « .NET Core » : la valeur « Non pris en charge » signifie que l’API n’est pas prise en charge sur cette plateforme cible.
• Changements recommandés : API ou technologie de remplacement recommandée. Actuellement, ce champ est vide ou obsolète pour un grand nombre d’API. En raison du grand nombre d’API, il est très difficile de le maintenir à jour. Nous étudions d’autres solutions pour fournir des informations utiles aux clients.

Assemblys manquants

Vous trouverez peut-être une section sur les assemblys manquants dans votre rapport. Cette section contient une liste d’assemblys qui sont référencés par vos assemblys analysés et qui n’ont pas été analysés. Si c’est un assembly qui vous appartient, incluez-le dans l’exécution de l’Analyseur de portabilité d’API afin d’obtenir un rapport de portabilité détaillé au niveau de l’API. S’il s’agit d’une bibliothèque tierce, vérifiez si une version plus récente prend en charge votre plateforme cible et envisagez de passer à la version la plus récente. Au final, vous devriez obtenir une liste qui inclut tous les assemblys tiers dont dépend votre application et qui confirme qu’ils ont une version prenant en charge votre plateforme cible.

Pour plus d’informations sur l’analyseur de portabilité .NET, consultez la documentation GitHub.