Lire en anglais

Partager via

Migrer d’ASP.NET Core 2.0 vers 2.1

  • Article

Par Rick Anderson

Consultez Nouveautés d’ASP .NET Core 2.1 pour obtenir une vue d’ensemble des nouvelles fonctionnalités dans ASP .NET Core 2.1.

Cet article :

  • Décrit les principes de base de la migration d’une application ASP.NET Core 2.0 vers la version 2.1.
  • Fournit une vue d’ensemble des modifications apportées aux modèles d’application web ASP.NET Core.

Un moyen rapide d’obtenir une vue d’ensemble des modifications apportées à la version 2.1 consiste à :

  • Créez une application web ASP.NET Core 2.0 nommée WebApp1.
  • Validez webApp1 dans un système de contrôle de code source.
  • Supprimez WebApp1 et créez une application web ASP.NET Core 2.1 nommée WebApp1 au même endroit.
  • Passez en revue les modifications apportées à la version 2.1.

Cet article fournit une vue d’ensemble de la migration vers ASP.NET Core 2.1. Il ne contient pas la liste complète de toutes les modifications nécessaires à la migration vers la version 2.1. Certains projets peuvent nécessiter davantage d’étapes en fonction des options sélectionnées lors de la création du projet et des modifications apportées au projet.

Mettre à jour le fichier projet pour utiliser les versions 2.1

Mettez à jour le fichier projet :

  • Remplacez la version cible par .NET Core 2.1 en mettant à jour le fichier projet vers <TargetFramework>netcoreapp2.1</TargetFramework>.
  • Remplacez la référence de package pour Microsoft.AspNetCore.All par une référence de package pour Microsoft.AspNetCore.App. Vous devrez peut-être ajouter des dépendances qui ont été supprimées de Microsoft.AspNetCore.All. Pour plus d’informations, consultez Métapaquet Microsoft.AspNetCore.All pour ASP.NET Core 2.0 et Métapaquet Microsoft.AspNetCore.App pour ASP.NET Core.
  • Supprimez l’attribut « Version » sur la référence de package à Microsoft.AspNetCore.App. Les projets qui utilisent <Project Sdk="Microsoft.NET.Sdk.Web"> n’ont pas besoin de définir la version. La version est impliquée par la version cible et sélectionnée pour correspondre au mieux à la façon dont ASP.NET Core 2.1 fonctionne. Pour plus d’informations, consultez la section Règles pour les projets ciblant l’infrastructure partagée.
  • Pour les applications qui ciblent .NET Framework, mettez à jour chaque référence de package vers la version 2.1.
  • Supprimez les références aux éléments <DotNetCliToolReference> pour les packages suivants. Ces outils sont regroupés par défaut dans l’interface CLI .NET et n’ont pas besoin d’être installés séparément.
    • Microsoft.DotNet.Watcher.Tools (dotnet watch)
    • Microsoft.EntityFrameworkCore.Tools.DotNet (dotnet ef)
    • Microsoft.Extensions.Caching.SqlConfig.Tools (dotnet sql-cache)
    • Microsoft.Extensions.SecretManager.Tools (dotnet user-secrets)
  • Facultatif : vous pouvez supprimer l’élément <DotNetCliToolReference> pour Microsoft.VisualStudio.Web.CodeGeneration.Tools. Vous pouvez remplacer cet outil par une version mondialement installée en exécutant dotnet tool install -g dotnet-aspnet-codegenerator.
  • Pour la version 2.1, une bibliothèque de classes Razor est la solution recommandée pour distribuer des fichiers Razor. Si votre application utilise des vues incorporées ou s’appuie sur la compilation de fichiers Razor au runtime, ajoutez <CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory> à un <PropertyGroup> dans votre fichier projet.

Le balisage suivant montre le fichier projet 2.0 généré par le modèle :

XML 
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.3" PrivateAssets="All" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.4" PrivateAssets="All" />
  </ItemGroup>
  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.3" />
    <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.2" />
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.4" />
  </ItemGroup>
</Project>

Le balisage suivant montre le fichier projet 2.1 généré par le modèle :

XML 
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.1.1" PrivateAssets="All" />
  </ItemGroup>

</Project>

Règles pour les projets ciblant l’infrastructure partagée

Un framework partagé est un ensemble d’assemblys (fichiers.dll) qui ne sont pas dans les dossiers de l’application. Le framework partagé doit être installé sur l’ordinateur pour exécuter l’application. Pour plus d’informations, consultez Le framework partagé.

ASP.NET Core 2.1 inclut les infrastructures partagées suivantes :

La version spécifiée par la référence de package est la version minimale requise. Par exemple, un projet référençant les versions 2.1.1 de ces packages ne s’exécute pas sur une machine avec uniquement le runtime 2.1.0 installé.

Problèmes connus pour les projets ciblant une infrastructure partagée :

Mettre à jour vers les images Docker 2.1

Dans ASP.NET Core 2.1, les images Docker ont migré vers le référentiel GitHub dotnet/dotnet-docker. Le tableau suivant montre les modifications apportées à l’image Docker et aux balises :

2.0 2.1
microsoft/aspnetcore:2.0 microsoft/dotnet:2.1-aspnetcore-runtime
microsoft/aspnetcore-build:2.0 microsoft/dotnet:2.1-sdk

Modifiez les lignes FROM de votre Dockerfile pour utiliser les nouveaux noms d'image et balises dans la colonne 2.1 du tableau précédent. Pour plus d’informations, consultez Migration d’aspnetcore docker repos vers dotnet.

Modifications apportées à Main

Les images suivantes montrent les modifications apportées au fichier Program.cs généré par un modèle.

différences avec l’ancienne version

L’image précédente montre la version 2.0 avec les suppressions en rouge.

L’illustration suivante montre le code de la version 2.1. Le code en vert a remplacé celui de la version 2.0 :

différences avec la nouvelle version

Le code suivant montre la version 2.1 de Program.cs :

C# 
namespace WebApp1
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateWebHostBuilder(args).Build().Run();
        }

        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>();
    }
}

Le nouveau Main remplace l’appel à BuildWebHost par CreateWebHostBuilder. IWebHostBuilder a été ajouté pour prendre en charge une nouvelle infrastructure de test d’intégration.

Modifications apportées au démarrage

Le code suivant montre les modifications apportées au code généré par le modèle 2.1. Toutes les modifications sont du code nouvellement ajouté, à l’exception de UseBrowserLink, qui a été supprimé :

C# 
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace WebApp1
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.Configure<CookiePolicyOptions>(options =>
            {
                // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;
            });


            services.AddMvc()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Error");
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseCookiePolicy();
            // If the app uses Session or TempData based on Session:
            // app.UseSession();

            app.UseMvc();
        }
    }
}

Les modifications de code précédentes sont détaillées dans :

Modifications apportées au code d’authentification

ASP.NET Core 2.1 fournit ASP.NET Core Identity en tant que bibliothèque de classes (RCL) Razor.

L’interface utilisateur Identity 2.1 par défaut ne fournit pas de nouvelles fonctionnalités significatives par rapport à la version 2.0. Le remplacement d’Identity par le package RCL est facultatif. Les avantages du remplacement du code d’Identity généré par le modèle par la version RCL sont les suivants :

  • De nombreux fichiers sont déplacés hors de votre arborescence source.
  • Tous les correctifs de bogues ou nouvelles fonctionnalités d’Identity sont inclus dans le métapaquet Microsoft.AspNetCore.App. Vous obtenez automatiquement la mise à jour d’Identity quand Microsoft.AspNetCore.App est mis à jour.

Si vous avez apporté des modifications non triviales au code d’Identity généré par le modèle :

  • Les avantages précédents ne justifient probablement pas la conversion vers la version RCL.
  • Vous pouvez conserver votre code d’Identity ASP.NET Core 2.0. Il est entièrement pris en charge.

Identity 2.1 expose les points de terminaison avec la zone d’Identity. Par exemple, le tableau suivant présente des exemples de points de terminaison d’Identity qui passent de 2.0 à 2.1 :

URL 2.0 URL 2.1
/Account/Login /Identity/Account/Login
/Account/Logout /Identity/Account/Logout
/Account/Manage /Identity/Account/Manage

Les applications qui ont du code utilisant Identity et remplacent l’interface utilisateur d’Identity 2.0 par la bibliothèque d’Identity 2.1 doivent prendre en compte que les URL d’Identity ont le segment /Identity ajouté aux URI. Une façon de gérer les nouveaux points de terminaison d’Identityconsiste à configurer des redirections, par exemple de /Account/Login vers /Identity/Account/Login.

Mettre à jour Identity vers la version 2.1

Les options suivantes sont disponibles pour mettre à jour Identity vers la version 2.1.

  • Utilisez le code 2.0 de l’interface utilisateur d’Identity sans modification. L’utilisation du code 2.0 de l’interface utilisateur d’Identity est entièrement prise en charge. Il s’agit d’une bonne approche lorsque des modifications importantes ont été apportées au code d’Identity généré.
  • Supprimez votre code 2.0 d’Identityexistant et générez automatiquement les modèles d’Identity dans votre projet. Votre projet va utiliser la bibliothèque de classes Razor d’ASP.NET Core Identity. Vous pouvez générer du code et une interface utilisateur pour n’importe quel code d’interface utilisateur d’Identity que vous avez modifié. Appliquez vos modifications de code au code de l’interface utilisateur nouvellement généré.
  • Supprimez votre code 2.0 d’Identity existant et générez automatiquement les modèles d’Identity dans votre projet avec l’option Remplacer tous les fichiers.

Remplacer l’interface utilisateur d’Identity 2.0 par la bibliothèque de classes d’Identity 2.1 Razor

Cette section décrit les étapes à suivre pour remplacer le code d’Identity généré par le modèle ASP.NET Core 2.0 par la bibliothèque de classes Razor Identity d’ASP.NET Core. Les étapes suivantes concernent un projet Razor Pages, mais l’approche est similaire pour un projet MVC.

  • Vérifier que le fichier projet est mis à jour pour utiliser les versions 2.1
  • Supprimez les dossiers suivants et tous les fichiers qu’ils contiennent :
    • Contrôleurs
    • Pages/Account/
    • Extensions
  • Créez le projet.
  • Générez automatiquement des modèles d’Identity dans votre projet :
    • Sélectionnez le fichier _Layout.cshtml existant du projet.
    • Sélectionnez l’icône + sur le côté droit de la classe de contexte de données. Acceptez le nom par défaut.
    • Sélectionnez Ajouterpour créer une classe de contexte de données. La création d’un nouveau contexte de données est nécessaire pour générer automatiquement des modèles. Vous supprimez le nouveau contexte de données dans la section suivante.

Mettre à jour après la génération automatique de modèles d’Identity

  • Supprimez la classe dérivée IdentityDbContext générée automatiquement par le générateur de modèles d’Identity dans le dossier Areas/Identity/Data/.

  • Supprimez Areas/Identity/IdentityHostingStartup.cs.

  • Mettez à jour le fichier _LoginPartial.cshtml :

    • Déplacez Pages/_LoginPartial.cshtml vers Pages/Shared/_LoginPartial.cshtml.
    • Ajoutez asp-area="Identity" au formulaire et aux liens d’ancrage.
    • Mettez à jour l’élément <form /> vers <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">.

    Le code suivant montre le fichier _LoginPartial.cshtml mis à jour :

    CSHTML 
    @using Microsoft.AspNetCore.Identity

@inject SignInManager<ApplicationUser> SignInManager
@inject UserManager<ApplicationUser> UserManager

@if (SignInManager.IsSignedIn(User))
{
    <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">
        <ul class="nav navbar-nav navbar-right">
            <li>
                <a asp-area="Identity" asp-page="/Account/Manage/Index" title="Manage">Hello @UserManager.GetUserName(User)!</a>
            </li>
            <li>
                <button type="submit" class="btn btn-link navbar-btn navbar-link">Log out</button>
            </li>
        </ul>
    </form>
}
else
{
    <ul class="nav navbar-nav navbar-right">
        <li><a asp-area="Identity" asp-page="/Account/Register">Register</a></li>
        <li><a asp-area="Identity" asp-page="/Account/Login">Log in</a></li>
    </ul>
}

Mettez à jour ConfigureServices à l’aide du code suivant :

C# 
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

    services.AddDefaultIdentity<ApplicationUser>()
        .AddEntityFrameworkStores<ApplicationDbContext>()
        .AddDefaultTokenProviders();

    services.AddMvc();

    // Register no-op EmailSender used by account confirmation and password reset 
    // during development
    services.AddSingleton<IEmailSender, EmailSender>();
}

Modifications apportées aux fichiers Razorde projets Razor Pages

Fichier de disposition

  • Déplacer Pages/_Layout.cshtml vers Pages/Shared/_Layout.cshtml

  • Dans Areas/Identity/Pages/_ViewStart.cshtml, remplacez Layout = "/Pages/_Layout.cshtml" par Layout = "/Pages/Shared/_Layout.cshtml".

  • Le fichier _Layout.cshtml présente les modifications suivantes :

_ValidationScriptsPartial.cshtml

  • Pages/_ValidationScriptsPartial.cshtml passe à Pages/Shared/_ValidationScriptsPartial.cshtml.
  • jquery.validate/1.14.0 devient jquery.validate/1.17.0.

Nouveaux fichiers

Les fichiers suivants sont ajoutés :

  • Privacy.cshtml
  • Privacy.cshtml.cs

Consultez Prise en charge du RGPD dans ASP.NET Core pour obtenir plus d’informations sur les fichiers précédents.

Modifications apportées aux fichiers Razor de projets MVC

Fichier de disposition

Le fichier Layout.cshtml présente les modifications suivantes :

  • <partial name="_CookieConsentPartial" /> est ajouté.
  • jQuery passe de 2.2.0 à 3.3.1

_ValidationScriptsPartial.cshtml

jquery.validate/1.14.0 devient jquery.validate/1.17.0

Nouveaux fichiers et méthodes d’action

Les éléments suivants sont ajoutés :

  • Views/Home/Privacy.cshtml
  • La méthode d’action Privacy est ajoutée au contrôleur Home.

Consultez Prise en charge du RGPD dans ASP.NET Core pour obtenir plus d’informations sur les fichiers précédents.

Modifications apportées au fichier launchSettings.json

Comme les applications ASP.NET Core utilisent désormais HTTPS par défaut, le fichier Properties/launchSettings.json a changé.

Le fichier JSON suivant montre le fichier launchSettings.json précédent généré par le modèle 2.0 :

JSON 
{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:1799/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "WebApp1": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:1798/"
    }
  }
}

Le fichier JSON suivant montre le nouveau fichier launchSettings.json généré par le modèle 2.1 :

JSON 
{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:39191",
      "sslPort": 44390
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "WebApp1": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

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

Changements cassants

En-tête de la plage FileResult

FileResult ne traite plus l’en-tête Accept-Ranges par défaut. Pour activer l’en-tête Accept-Ranges, définissez EnableRangeProcessing sur true.

En-tête de la plage ControllerBase.File et PhysicalFile

Les méthodes ControllerBase suivantes ne traitent plus l’en-tête Accept-Ranges par défaut :

Pour activer l’en-tête Accept-Ranges , définissez le paramètre EnableRangeProcessing sur true.

Module ASP.NET Core (ANCM)

Si le module ASP.NET Core (ANCM) n'était pas un composant sélectionné lors de l'installation de Visual Studio ou si une version antérieure de l'ANCM était installée sur le système, téléchargez le dernier programme d'installation du pack .NET Core Hosting (téléchargement direct) et exécutez l'installateur. Pour plus d'informations, consultez Pack d'hébergement.

Modifications supplémentaires