Utiliser l’assistant de mise à niveau de .NET hérité

Article
06/06/2023

Dans cet article, vous allez apprendre à installer et à exécuter l’ancienne version de l’outil d’interface de ligne de commande (CLI) de l’Assistant de mise à niveau de .NET. À compter de la version 0.5.2, la base de code de l’outil CLI de l’assistant de mise à niveau de .NET a été rebasé sur l’extension Visual Studio. Cela signifie qu’il existe en fait deux outils CLI différents : les versions antérieures à 0.5.2, appelées collectivement version héritée, et les versions 0.5.2+ qui sont l’outil actuel.

La version héritée dispose de certaines fonctionnalités qui ne sont pas encore disponibles dans la nouvelle version, comme les commandes d’analyse ou les mises à niveau au niveau de la solution, mais elle ne présente pas certaines des nouvelles améliorations disponibles dans la nouvelle version (0.5.2+). Par conséquent, vous pouvez l’utiliser jusqu’à ce que la version actuelle gagne en capacité et en étendue.

Conseil

La version héritée de l’outil peut mettre à niveau les fichiers de solution.

Installer la version héritée

La version héritée de l’outil est installée de la même façon que la version actuelle, à l’exception que vous spécifiez la version 0.4.421302 :

dotnet tool install upgrade-assistant -g --version 0.4.421302

Important

L’installation de cet outil peut échouer si vous avez configuré d’autre sources de flux NuGet. Utilisez le paramètre --ignore-failed-sources pour traiter ces échecs comme des avertissements plutôt que des erreurs :

dotnet tool install upgrade-assistant -g --ignore-failed-sources --version 0.4.421302

Analyser votre application

La version héritée de l’outil inclut un mode d’analyse qui effectue un essai simplifié de la mise à niveau de votre application. Il peut fournir des informations sur les modifications qui peuvent être nécessaires avant le démarrage de la mise à niveau. Ouvrez un terminal et accédez au dossier où se trouve le projet ou la solution cible. Exécutez la commande upgrade-assistant analyze en passant le nom du projet ou de la solution que vous mettez à niveau.

Par exemple, voici la sortie après l’exécution du mode analyse avec l’application WPF .NET Framework :

> upgrade-assistant analyze .\WebSiteRatings.sln

[15:39:00 INF] Loaded 9 extensions
[15:39:02 INF] Using MSBuild from C:\Program Files\dotnet\sdk\7.0.201\
[15:39:02 INF] Using Visual Studio install from C:\Program Files\Microsoft Visual Studio\2022\Preview [v17]
[15:39:05 INF] Writing output to C:\code\migration\AnalysisReport.sarif
[15:39:06 INF] Recommending Windows TFM net7.0-windows for project WebSiteRatings.csproj because the project either has Windows-specific dependencies or builds to a WinExe
[15:39:06 INF] Marking assembly reference System.Configuration for removal based on package mapping configuration System.Configuration
[15:39:06 INF] Adding package System.Configuration.ConfigurationManager based on package mapping configuration System.Configuration
[15:39:08 INF] Package EntityFramework, Version=6.2.0 does not support the target(s) net7.0-windows but a newer version (6.4.4) does.
[15:39:09 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added
[15:39:10 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs
[15:39:13 INF] Recommending Windows TFM net7.0-windows for project StarVoteControl.csproj because the project either has Windows-specific dependencies or builds to a WinExe
[15:39:13 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added
[15:39:13 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs
[15:39:13 INF] Running analyzers on WebSiteRatings
[15:39:14 INF] Identified 0 diagnostics in project WebSiteRatings
[15:39:14 INF] Running analyzers on StarVoteControl
[15:39:15 INF] Identified 0 diagnostics in project StarVoteControl
[15:39:15 INF] Analysis Complete, the report is available at C:\code\migration\AnalysisReport.sarif

Il y a beaucoup d’informations de diagnostic interne dans la sortie, mais certaines informations sont utiles. Notez que le mode d’analyse indique que pendant une mise à niveau, le moniker du framework cible (TFM) du projet va être défini sur net7.0-windows au lieu de net7.0. Cette recommandation est due au fait que les projets référencés par la solution sont des projets WPF, une technologie Windows uniquement. Une application console serait probablement mise à niveau directement vers TFM net7.0, sauf si elle utilisait une bibliothèque ou du code spécifique à Windows.

Exécuter l’Assistant Mise à niveau

Ouvrez un terminal et accédez au dossier où se trouve le projet ou la solution cible. Exécutez la commande upgrade-assistant upgrade en passant le nom du projet ou de la solution que vous mettez à niveau.

Lorsque l’outil s’exécute, il affiche la liste des étapes qu’il effectue pour mettre à niveau le projet. À mesure que chaque étape est effectuée, l’outil fournit un ensemble de commandes numérotées permettant à l’utilisateur d’appliquer ou d’ignorer l’étape suivante. Il peut fournir d’autres options, comme :

Obtenir plus d’informations sur l’étape.
Changer les projets.
Ajuster les paramètres de journalisation.
Arrêter la mise à niveau et quitter.

Si vous appuyez sur Entrée sans choisir un numéro, c’est le premier élément de la liste qui est sélectionné.

À mesure que chaque étape s’initialise, l’outil peut fournir des informations sur ce qui peut se produire si vous appliquez l’étape.

Mettre à niveau une solution

Lorsque vous mettez à niveau une solution qui contient plusieurs projets, vous devez sélectionner le projet dans la solution qui correspond au point d’entrée. En fonction du projet de point d’entrée, un graphe des dépendances est créé pour déterminer les projets à mettre à niveau et dans quel ordre. Si la solution contient des projets qui ne font pas partie du graphe des dépendances, ils sont ignorés et vous devez mettre à niveau ces projets séparément. Les dépendances sont mises à niveau en premier, puis le projet de point d’entrée.

L’étape suivante consiste à choisir le projet à mettre à niveau. Le résultat ressemble à l’extrait de code qui suit :

Upgrade Steps

1. [Next step] Select an entrypoint
2. Select project to upgrade

Choose a command:
   1. Apply next step (Select an entrypoint)
   2. Skip next step (Select an entrypoint)
   3. See more step details
   4. Configure logging
   5. Exit

Conseil

Faites attention à la sortie de chaque étape, car elle peut contenir des informations sur un élément que l’outil ne peut pas mettre à niveau. Selon la complexité de votre application, vous devrez peut-être effectuer davantage de travail de mise à niveau une fois l’exécution de l’outil terminée.

Mettre à niveau le projet

Une fois qu’un projet est sélectionné, une liste des étapes de mise à niveau est affichée. La première étape, qui consiste à sauvegarder le projet, est sélectionnée. La liste des étapes ressemble à l’extrait de code suivant :

[15:50:50 INF] Initializing upgrade step Back up project

Upgrade Steps

Entrypoint: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj
Current Project: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj

1. [Next step] Back up project
2. Convert project file to SDK style
3. Clean up NuGet package references
    a. Duplicate reference analyzer
    b. Package map reference analyzer
    c. Target compatibility reference analyzer
    d. Upgrade assistant reference analyzer
    e. Windows Compatibility Pack Analyzer
    f. MyDotAnalyzer reference analyzer
    g. Newtonsoft.Json reference analyzer
    h. Windows App SDK package analysis
    i. Transitive reference analyzer
4. Update TFM
5. Update NuGet Packages
    a. Duplicate reference analyzer
    b. Package map reference analyzer
    c. Target compatibility reference analyzer
    d. Upgrade assistant reference analyzer
    e. Windows Compatibility Pack Analyzer
    f. MyDotAnalyzer reference analyzer
    g. Newtonsoft.Json reference analyzer
    h. Windows App SDK package analysis
    i. Transitive reference analyzer
6. Add template files
7. Update WCF service to CoreWCF (Preview)
8. Upgrade app config files
    a. Convert Application Settings
    b. Convert Connection Strings
    c. Disable unsupported configuration sections
9. Update source code
    a. Apply fix for UA0002: Types should be upgraded
    b. Apply fix for UA0012: 'UnsafeDeserialize()' does not exist
10. Move to next project

Choose a command:
   1. Apply next step (Back up project)
   2. Skip next step (Back up project)
   3. See more step details
   4. Select different project
   5. Configure logging
   6. Exit

Chaque étape détaille d’abord ce qu’elle va faire, puis vous invite à le faire. Toute étape qui ne s’applique pas est ignorée lorsque l’outil arrive à l’étape. Par exemple, si l’outil traite 7. Mettre à jour le service WCF vers CoreWCF (préversion), mais que votre application ne définit pas de service WCF, l’étape est ignorée et l’étape 8 est traitée. À son tour, si l’étape 8 ne s’applique pas, elle est également ignorée. De nombreuses étapes peuvent être ignorées lorsque l’outil tente de trouver l’étape suivante qui s’applique.

Dernières étapes

Après avoir mis à niveau vos projets, vous devez les compiler et les tester. Il reste probablement encore du travail à faire pour terminer la mise à niveau. Il est possible que la version .NET Framework de votre application contienne des références de bibliothèque que votre projet n’utilise pas, et qui ont été reportées. Analysez chaque référence et déterminez 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 une version incorrecte.

Enfin, recherchez des moyens de moderniser votre application. Pour obtenir des exemples, consultez Modernisations après la mise à niveau vers .NET à partir de .NET Framework