Migrer d’ASP.NET Core 1.x vers la version 2.0

Article
11/30/2023

Dans cet article, nous vous montrons comment mettre à jour un projet ASP.NET Core 1.x existant vers ASP.NET Core 2.0. La migration de votre application vers ASP.NET Core 2.0 vous permet de tirer parti de nombreuses nouvelles fonctionnalités et améliorations des performances.

Les applications ASP.NET Core 1.x existantes sont basées sur des modèles de projet propres à la version. Les modèles de projet et le code de démarrage qu’ils contiennent évoluent en même temps que le framework ASP.NET Core. Outre le framework ASP.NET Core, vous devez aussi mettre à jour le code de votre application.

Prérequis

Consultez Bien démarrer avec ASP.NET Core.

Mettre à jour le Moniker du Framework cible

Les projets ciblant .NET Core doivent utiliser le Moniker du Framework cible d’une version supérieure ou égale à .NET Core 2.0. Recherchez le nœud <TargetFramework> dans le fichier .csproj et remplacez son texte interne par netcoreapp2.0 :

<TargetFramework>netcoreapp2.0</TargetFramework>

Les projets ciblant le .NET Framework doivent utiliser le Moniker du Framework cible d’une version supérieure ou égale à .NET Framework 4.6.1. Recherchez le nœud <TargetFramework> dans le fichier .csproj et remplacez son texte interne par net461 :

<TargetFramework>net461</TargetFramework>

Remarque

.NET Core 2.0 offre une surface d’exposition beaucoup plus grande que .NET Core 1.x. Si vous ciblez le .NET Framework uniquement car il manque des API dans .NET Core 1.x, le ciblage de .NET Core 2.0 fonctionnera sans doute.

Si le fichier projet contient <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion>, voir ce problème GitHub.

Mettre à jour la version du SDK .NET Core dans global.json

Si votre solution s’appuie sur un fichier global.json pour cibler une version spécifique du Kit de développement logiciel (SDK) .NET Core, mettez à jour sa propriété version pour utiliser la version 2.0 installée sur votre ordinateur :

{
  "sdk": {
    "version": "2.0.0"
  }
}

Mettre à jour les références de package

Le fichier .csproj dans un projet 1.x liste chaque package NuGet utilisé par le projet.

Dans un projet ASP.NET Core 2.0 ciblant .NET Core 2.0, une seule référence de métapackage dans le fichier .csproj remplace la collection de packages :

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
</ItemGroup>

Toutes les fonctionnalités d’ASP.NET Core 2.0 et d’Entity Framework Core 2.0 sont incluses dans le métapackage.

Les projets ASP.NET Core 2.0 ciblant le .NET Framework doivent continuer à référencer des packages NuGet spécifiques. Mettez à jour l’attribut Version de chaque nœud <PackageReference /> vers la version 2.0.0.

Par exemple, voici la liste des nœuds <PackageReference /> utilisés dans un projet ASP.NET Core 2.0 standard qui cible le .NET Framework :

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Authentication.Cookies" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="2.0.0" />
  <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.0" PrivateAssets="All" />
</ItemGroup>

Le package Microsoft.Extensions.CommandLineUtils a été mis hors service. Il est toujours disponible mais ne fait plus l’objet d’un support technique.

Mettre à jour les outils CLI .NET Core

Dans le fichier .csproj, mettez à jour l’attribut Version de chaque nœud <DotNetCliToolReference /> vers la version 2.0.0.

Par exemple, voici la liste des outils CLI utilisés dans un projet ASP.NET Core 2.0 standard qui cible .NET Core 2.0 :

<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
</ItemGroup>

Renommer la propriété PackageTargetFallback

Le fichier .csproj d’un projet 1.x utilisait un nœud et une variable PackageTargetFallback :

<PackageTargetFallback>$(PackageTargetFallback);portable-net45+win8+wp8+wpa81;</PackageTargetFallback>

Renommez le nœud et la variable AssetTargetFallback :

<AssetTargetFallback>$(AssetTargetFallback);portable-net45+win8+wp8+wpa81;</AssetTargetFallback>

Mettre à jour la méthode Main dans Program.cs

Dans les projets 1.x, la méthode Main de Program.cs se présentait comme ceci :

using System.IO;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore1App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = new WebHostBuilder()
                .UseKestrel()
                .UseContentRoot(Directory.GetCurrentDirectory())
                .UseIISIntegration()
                .UseStartup<Startup>()
                .UseApplicationInsights()
                .Build();

            host.Run();
        }
    }
}

Dans les projets 2.0, la méthode Main de Program.cs a été simplifiée :

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore2App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            BuildWebHost(args).Run();
        }

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
}

L’adoption de ce nouveau modèle 2.0 est vivement recommandée, et même obligatoire pour bénéficier des fonctionnalités de produit telles que Entity Framework (EF) Core Migrations. Par exemple, l’exécution de Update-Database à partir de la fenêtre de la Console du Gestionnaire de Package ou de dotnet ef database update à partir de la ligne de commande (sur des projets convertis vers ASP.NET Core 2.0) génère l’erreur suivante :

Unable to create an object of type '<Context>'. Add an implementation of 'IDesignTimeDbContextFactory<Context>' to the project, or see https://go.microsoft.com/fwlink/?linkid=851728 for additional patterns supported at design time.

Ajouter des fournisseurs de configuration

Dans les projets 1.x, l’ajout de fournisseurs de configuration à une application a été effectué via le constructeur Startup. Étapes nécessaires à la création d’une instance de ConfigurationBuilder, chargement des fournisseurs applicables (variables d’environnement, paramètres de l’application, etc.) et initialisation d’un membre de IConfigurationRoot.

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);

    if (env.IsDevelopment())
    {
        builder.AddUserSecrets<Startup>();
    }

    builder.AddEnvironmentVariables();
    Configuration = builder.Build();
}

public IConfigurationRoot Configuration { get; }

L’exemple précédent charge le membre Configuration avec les paramètres de configuration depuis appsettings.json ainsi que des fichiers appsettings.{Environment}.json correspondant à la propriété IHostingEnvironment.EnvironmentName. L’emplacement de ces fichiers est sur le même chemin que Startup.cs.

Dans les projets 2.0, le code de configuration réutilisable inhérent aux projets 1.x s’exécute en arrière-plan. Par exemple, les variables d’environnement et les paramètres de l’application sont chargés au démarrage. Le code de Startup.cs équivalent est réduit à l’initialisation de IConfiguration avec l’instance injectée :

public Startup(IConfiguration configuration)
{
    Configuration = configuration;
}

public IConfiguration Configuration { get; }

Pour supprimer les fournisseurs par défaut ajoutés par WebHostBuilder.CreateDefaultBuilder, appelez la méthode Clear sur la propriété IConfigurationBuilder.Sources dans ConfigureAppConfiguration. Pour rajouter des fournisseurs, utilisez la méthode ConfigureAppConfiguration dans Program.cs :

public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureAppConfiguration((hostContext, config) =>
        {
            // delete all default configuration providers
            config.Sources.Clear();
            config.AddJsonFile("myconfig.json", optional: true);
        })
        .Build();

La configuration utilisée par la méthode CreateDefaultBuilder dans l’extrait de code précédent peut être consultée ici.

Pour plus d’informations, consultez Configuration dans ASP.NET Core.

Déplacer le code d’initialisation de base de données

Dans les projets 1.x utilisant EF Core 1.x, une commande telle que dotnet ef migrations add effectue les opérations suivantes :

Instancie une instance Startup
Appelle la méthode ConfigureServices pour inscrire tous les services à l’injection de dépendances (notamment les types DbContext)
Exécute ses tâches obligatoires

Dans les projets 2.0 utilisant EF Core 2.0, Program.BuildWebHost est appelé pour obtenir les services d’application. Contrairement à 1.x, cela a pour autre effet secondaire d’appeler Startup.Configure. Si votre application 1.x a appelé le code d’initialisation de base de données dans sa méthode Configure, des problèmes inattendus peuvent se produire. Par exemple, si la base de données n’existe pas encore, le code d’amorçage s’exécute avant l’exécution de la commande EF Core Migrations. Ce problème entraîne l’échec de la commande dotnet ef migrations list si la base de données n’existe pas encore.

Considérez le code d’initialisation de l’amorçage 1.x suivant dans la méthode Configure de Startup.cs :

app.UseMvc(routes =>
{
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

SeedData.Initialize(app.ApplicationServices);

Dans les projets 2.0, déplacez l’appel de SeedData.Initialize vers la méthode Main de Program.cs :

var host = BuildWebHost(args);

using (var scope = host.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    try
    {
        // Requires using RazorPagesMovie.Models;
        SeedData.Initialize(services);
    }
    catch (Exception ex)
    {
        var logger = services.GetRequiredService<ILogger<Program>>();
        logger.LogError(ex, "An error occurred seeding the DB.");
    }
}

host.Run();

À compter de la version 2.0, il est déconseillé de faire quoi que ce soit dans BuildWebHost, sauf de créer et de configurer l’hôte web. Tout ce qui concerne l’exécution de l’application doit être géré en dehors de BuildWebHost, généralement dans la méthode Main de Program.cs.

Passer en revue le paramètre de compilation des vues Razor

La vitesse de démarrage d’application et la taille des bundles publiés ont une importance capitale pour vous. Pour ces raisons, la compilation des vues Razor est activée par défaut dans ASP.NET Core 2.0.

L’affectation de la valeur true à la propriété MvcRazorCompileOnPublish n’est plus nécessaire. Sauf si vous désactivez la compilation des vues, vous pouvez supprimer la propriété du fichier .csproj.

Quand vous ciblez le .NET Framework, vous devez néanmoins toujours référencer explicitement le package NuGet Microsoft.AspNetCore.Mvc.Razor.ViewCompilation dans votre fichier .csproj :

<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />

S’appuyer sur les fonctionnalités de mise en évidence d’Application Insights

La configuration sans effort de l’instrumentation des performances d’application est importante. Vous pouvez maintenant vous appuyer sur les nouvelles fonctionnalités de mise en évidence d’Application Insights disponibles dans les outils Visual Studio 2017.

Par défaut, les projets ASP.NET Core 1.1 créés dans Visual Studio 2017 ajoutaient Application Insights. Si vous n’utilisez pas le SDK Application Insights directement, en dehors de Program.cs et de Startup.cs, effectuez les étapes suivantes :

Si vous ciblez .NET Core, supprimez le nœud <PackageReference /> suivant dans le fichier .csproj :
```
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
```

Si vous ciblez .NET Core, supprimez l’appel de la méthode d’extension UseApplicationInsights de Program.cs :

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseIISIntegration()
        .UseStartup<Startup>()
        .UseApplicationInsights()
        .Build();

    host.Run();
}

Supprimez l’appel d’API côté client d’Application Insights du fichier _Layout.cshtml. Il comprend les deux lignes de code suivantes :
```
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
@Html.Raw(JavaScriptSnippet.FullScript)
```

Si vous utilisez le SDK Application Insights directement, continuez à le faire. La version 2.0 du métapackage inclut la dernière version d’Application Insights. Par conséquent, une erreur de passage à une version antérieure de package s’affiche si vous référencez une version antérieure.

Adopter les améliorations de l’authentification/Identity

ASP.NET Core 2.0 offre un nouveau modèle d’authentification, et plusieurs modifications importantes ont été apportées à ASP.NET Core Identity. Si vous avez créé votre projet avec l’option Comptes d’utilisateur individuels activée, ou si vous avez ajouté manuellement l’authentification ou Identity, consultez Migrer l’authentification et Identity vers ASP.NET Core 2.0.

Ressources supplémentaires

Changements importants dans ASP.NET Core 2.0

Migrer d’ASP.NET Core 1.x vers la version 2.0

Prérequis

Mettre à jour le Moniker du Framework cible

Mettre à jour la version du SDK .NET Core dans global.json

Mettre à jour les références de package

Mettre à jour les outils CLI .NET Core

Renommer la propriété PackageTargetFallback

Mettre à jour la méthode Main dans Program.cs

Ajouter des fournisseurs de configuration

Déplacer le code d’initialisation de base de données

Passer en revue le paramètre de compilation des vues Razor

S’appuyer sur les fonctionnalités de mise en évidence d’Application Insights

Adopter les améliorations de l’authentification/Identity

Ressources supplémentaires

Commentaires

Ressources supplémentaires