Rencontrez l'assistant de mise à niveau .NET, votre entreprise de déménagement .NET 5

L'assistant de mise à niveau .NET est un outil de ligne de commande global qui vous guide tout au long de la migration de vos applications .NET Framework vers .NET 5, en automatisant plusieurs étapes douloureuses en cours de route. Dans cet article, nous passons en revue l'outil en migrant une application ASP.NET MVC.

Le déménagement est juste le pire.

Vous devez louer un camion, j'espère qu'il contiendra toutes vos affaires, implorez vos amis et votre famille de aider et ressentir la douleur pendant des jours après le déménagement. Et pendant le déménagement, vous vous dites: «Un jour, j'embaucherai quelqu'un pour me débarrasser de tout ce stress. Imaginez ce que je pourrais faire au lieu de tout ce travail fastidieux! La prochaine fois que vous déménagez, vous embauchez une entreprise de déménagement, et c'est incroyable . Les déménageurs gèrent tous les gros travaux pendant que vous vous concentrez sur l'installation de votre nouvelle maison.

C'est la promesse de l ' .NET Upgrade Assistant un outil de ligne de commande global qui vous aide à migrer votre .NET Framework apps to .NET 5. Si .NET Framework est la maison robuste qui montre son âge et devient de plus en plus difficile à réparer et .NET 5 est une maison moderne et efficace construite avec des matériaux de pointe, l'assistant de mise à niveau .NET est l'entreprise de déménagement qui vous simplifie la vie.

Soyons clairs: l'assistant de mise à niveau .NET n'est pas une baguette magique . Vous devrez probablement effectuer un travail manuel lors de la migration. Cependant, l'outil peut faire la plupart de vos tâches lourdes et vous permettre de vous concentrer sur ce qui est important.

Que fait exactement l'assistant de mise à niveau .NET? Dans la version préliminaire, il s'agit d'un outil guidé qui vous guide tout au long de votre migration.

Il effectue les tâches suivantes:

• Ajout d'analyseurs qui facilitent la mise à niveau
• Détermine les projets à mettre à niveau et dans quel ordre
• Met à jour votre projet fichier au format SDK
• Re-cible vos projets vers .NET 5
• Met à jour les dépendances de package NuGet vers des versions compatibles avec .NET 5 et supprime les dépendances transitives présentes dans packages.config
• Effectue des mises à jour C # pour remplacer les modèles .NET Framework par leurs équivalents .NET 5.
• Le cas échéant, ajoute des fichiers modèles communs

L'assistant de mise à niveau .NET vous permet de migrer à partir des types d'application .NET Framework suivants:

• Windows Formulaires
• WPF
• Applications ASP.NET MVC
• Applications console
• Bibliothèques de classes

Nous allons évaluer l'assistant de mise à niveau .NET en migrant une ancienne application ASP.NET MVC, eShopLegacyMVCSolution w qui exécute .NET Framework 4.7.2. Je l'ai emprunté au référentiel du livre électronique Microsoft, Moderniser les applications .NET existantes avec le cloud Azure et les conteneurs Windows par Cesar de la Torre. Mon référentiel daveabrock / UpgradeAssistantDemo contient à la fois la solution héritée et ma solution mise à niveau. En prime, vous pouvez consulter l'historique de mes commit pour voir comment le code change après chaque étape.

Avant de commencer

Avant de commencer à utiliser l'assistant de mise à niveau, assurez-vous que vous êtes familiarisé avec la documentation de portage de Microsoft et comprendre les limites de la migration, en particulier lorsque décide de migrer des applications ASP.NET . De plus, vous pouvez utiliser l'outil .NET Portability Analyzer pour comprendre quelles dépendances prennent en charge .NET 5. C'est comme appeler d'abord l'entreprise de déménagement pour savoir ce qu'elle peut et ne peut pas déplacer et combien de temps cela peut prendre. [19659003] Avant d'installer l'assistant de mise à niveau .NET, vous devez vous assurer d'installer les éléments suivants:

L'outil dépend également de l'outil try-convert pour convertir les fichiers de projet au style SDK. Vous devez disposer de la version 0.7.212201 ou ultérieure pour utiliser l'assistant de mise à niveau.

À partir d'un terminal, exécutez la commande suivante pour installer l'assistant de mise à niveau .NET. (C'est un outil global, vous pouvez donc exécuter la commande n'importe où.)

 dotnet tool  install  -g try-convert

Si try-convert est installé mais que vous devez effectuer une mise à niveau vers une version plus récente, exécutez ce qui suit:

 dotnet tool update -g try-convert

Installez l'assistant de mise à niveau .NET

Nous sommes maintenant prêts à installer l'assistant de mise à niveau .NET. Pour ce faire, exécutez ce qui suit à partir d'un terminal:

 dotnet tool  install  -g upgrade-assistant

Après avoir installé l'assistant de mise à niveau .NET, exécutez-le en naviguant jusqu'au dossier où se trouve votre solution et en entrant la commande suivante.

 upgrade-assistant  < MySolution.sln > [19659037] Utilisez l'assistant de mise à niveau pour migrer vers .NET 5 
 Pour commencer, j'exécute la commande suivante à partir de mon terminal. (La commande par défaut devrait fonctionner, mais, si nécessaire, vous pouvez  passer d'autres indicateurs  comme  - verbose .) 
 upgrade-assistant eShopDotNet5MVC.sln
 L'outil s'exécute et me montre les étapes qu'il va exécuter. Pour chaque étape du processus, je peux appliquer l'étape suivante du processus, l'ignorer, voir les détails ou configurer la journalisation. La plupart du temps, vous voudrez sélectionner  Appliquer l’étape suivante . Pour gagner du temps, vous pouvez appuyer sur  Entrée  pour ce faire.
 
 Lorsque l'outil démarre, il place un journal . txt  à la racine de votre projet.
 Sauvegarder le projet
 La première étape consiste à sauvegarder le projet. L'Assistant de mise à niveau .NET vous demande si vous souhaitez utiliser un chemin personnalisé pour votre sauvegarde ou un emplacement par défaut. Une fois cette opération terminée, nous sommes prêts à convertir le fichier de projet.
 
   
 Convertir les fichiers de projet en style SDK
 Les projets .NET 5 utilisent le style SDK format. Dans cette étape, l'assistant de mise à niveau convertit votre fichier de projet au format SDK à l'aide de l'outil  try-convert . Au cours de ce processus, nous voyons que l'outil nous avertit que quelques importations, comme  System.Web peuvent nécessiter une intervention manuelle après la migration.
 
 Mise à jour de TFM
 Ensuite, l'assistant de mise à niveau .NET mettra à jour le Target Framework Moniker (TFM) vers .NET 5.0. Dans mon cas, la valeur passe de  net472  à  net5.0 .
 
 Update NuGet Packages
 Once l'assistant de mise à niveau met à jour le TFM, il tente de mettre à jour les packages NuGet du projet. L'outil utilise un analyseur pour détecter les références à supprimer et les packages à mettre à niveau avec leurs versions .NET 5. Ensuite, l'outil met à jour les packages.
 
 Ajouter des fichiers modèles
 Une fois que l'outil a mis à jour les packages NuGet, il ajoute tous les fichiers modèles appropriés. ASP.NET Core utilise des fichiers de modèle pour la configuration et le démarrage. Il s'agit généralement de  Program.cs  Startup.cs  appsettings.json  et  appsettings.development.json .
 
 Migrer les fichiers de configuration d'application
 L'outil est maintenant prêt à migrer nos fichiers de configuration d'application. L'outil identifie les paramètres pris en charge, puis migre tous les paramètres configurables vers mon fichier  appSettings.json . Une fois cette opération terminée, l'outil migre  system.web.webPages.razor / pages / namespaces  en mettant à jour  _ViewImports.cshtml  avec une référence  @addTagHelper  à  ] Microsoft.AspNetCore.Mvc.TagHelpers .
 
 Update C # Source
 Désormais, l'assistant de mise à niveau .NET met à niveau les références de code C # vers leur. Homologues NET Core. Vous verrez plusieurs étapes répertoriées dans le terminal. Toutes ne s'appliquent pas. Dans ces cas, ils seront ignorés et marqués comme [Complete].
 Dans mon cas, l'étape supprime d'abord toute  en utilisant les instructions  qui font référence aux espaces de noms .NET Framework, comme  System. Web . Ensuite, cela garantit que mes appels  ActionResult  proviennent de l'espace de noms  Microsoft.AspNetCore.Mvc . Enfin, l'assistant de mise à niveau garantit que je n'utilise pas  HttpContext.Current que ASP.NET Core ne prend pas en charge.
 
 La dernière étape consiste à évaluer le projet suivant. Étant donné que notre solution ne comporte qu'un seul projet, l'outil se ferme.
 Résoudre manuellement les problèmes restants
 Lorsque vous revenez à votre projet, vous verrez des erreurs de compilation. C'est normal. Cet outil automatisera une grande partie de la migration pour vous, mais vous devrez tout de même régler certaines choses. La plupart de ces problèmes concernent la manière dont ASP.NET Core gère le démarrage, la configuration et le regroupement.
 Les fichiers  Global.asax  et  Global.asax.cs  ne sont plus nécessaires dans ASP .NET Core, car le modèle d'événement d'application global est remplacé par le modèle d'injection de dépendances d'ASP.NET Core, dans  Startup.cs .
 Vous n'aurez pas besoin du dossier  App_Start  ou l'un des fichiers qu'il contient ( BundleConfig.cs  FilterConfig.cs  et  RouteConfig.cs ). Vas y et supprime le. Ça fait du bien, n'est-ce pas?
 Après cela, la plupart de vos erreurs restantes sont liées au regroupement de vos éléments statiques. ASP.NET Core fonctionne avec plusieurs solutions de regroupement. Lisez la  documentation de regroupement  et choisissez ce qui fonctionne le mieux pour votre projet.
 Enfin, résolvez tous les problèmes qui subsistent. Votre kilométrage peut varier, mais mes modifications ont été minimes. Par exemple, dans mon fichier  _Layout.cshtml j'ai dû injecter un  IHttpContextAccessor  pour accéder à la  HttpContext.Session  et j'ai également dû nettoyer certains  ] Réponses ActionResult .
 Extension de l'assistant de mise à niveau .NET
 Alors que l'assistant de mise à niveau répond à la plupart de vos cas d'utilisation, il a  un modèle d'accessibilité  facultatif   qui permet vous permet de personnaliser les étapes de mise à niveau sans modifier l'outil vous-même. Par exemple, vous pouvez mapper explicitement les packages NuGet à leurs remplacements, ajouter des fichiers de modèle personnalisés et ajouter des étapes de mise à niveau personnalisées. Pour commencer, vous allez inclure un fichier  ExtensionManifest.json  qui définit où l'outil trouve les différents éléments d'extension. Vous avez besoin d'un manifeste, mais tous les éléments suivants sont facultatifs, vous ne pouvez donc définir que ce dont vous avez besoin.
 {
   "ExtensionName" :   "My awesome extension" [19659080] "PackageUpdater" :   {
     "PackageMapPath" :   "PackageMaps" 
  } 
   "TemplateInserter" :   {
     "TemplatePath" :   "Templates" 
  } 

   "ExtensionServiceProviders" :   [
     "MyAwesomeExtension" 
  ] [19659101]} 
 Lorsque vous exécutez l'assistant de mise à niveau, vous pouvez passer un argument  -e  pour transmettre l'emplacement du fichier manifeste ou définir une variable d'environnement  UpgradeAssistantExtensionPaths . Consultez  la documentation  pour plus de détails.
 Vous souvenez-vous quand nous avons supprimé manuellement le dossier  Global.asax  et le contenu du dossier  App_Start ? Si nous mettons à niveau de nombreux projets, pensez à ajouter une étape de mise à niveau personnalisée pour les supprimer.
 En savoir plus
 Comme je l'ai mentionné, l'assistant de mise à niveau .NET est un outil prometteur et puissant - cependant, il est en mode avant-première et est évolue rapidement. Assurez-vous de consulter le référentiel GitHub de l'outil pour vous mettre à jour et  signalez tout problème ou suggestion . Vous pouvez également  consulter la feuille de route de l'outil .
 Restez à l'affût des améliorations. Par exemple, .NET 5 est une version «actuelle» - cela signifie qu'il est pris en charge pendant trois mois après la livraison officielle de .NET 6 (le support prend fin en février 2022). .NET 6, qui sortira en novembre, est une version LTS (Long-Term Support), ce qui signifie qu’elle est prise en charge pendant au moins trois ans. En conséquence, vous verrez bientôt la possibilité de  choisir la version à cibler .
 Conclusion
 Dans cet article, nous avons visité le nouvel assistant de mise à niveau .NET et montré comment accélérer votre migration vers .NET 5. Avez-vous essayé? Laissez un commentaire et dites-moi ce que vous en pensez.