Migrer d’ASP.NET Core 2.0 vers 2.1
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.Allpar une référence de package pourMicrosoft.AspNetCore.App. Vous devrez peut-être ajouter des dépendances qui ont été supprimées deMicrosoft.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 Core 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)
- Microsoft.DotNet.Watcher.Tools (
- 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écutantdotnet tool install -g dotnet-aspnet-codegenerator. - Pour la version 2.1, une Razor bibliothèque de classes 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 :
<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 :
<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 :
Le kit SDK .NET Core 2.1.300 (d’abord inclus dans Visual Studio 15.6) a défini la version implicite de
Microsoft.AspNetCore.Appsur 2.1.0, ce qui a provoqué des conflits avec Entity Framework Core 2.1.1. La solution recommandée consiste à mettre à niveau le kit SDK .NET Core vers la version 2.1.301 ou ultérieure. Pour plus d’informations, consultez Les packages qui partagent des dépendances avec Microsoft.AspNetCore.App ne peuvent pas référencer les versions de correctif.Tous les projets qui doivent utiliser
Microsoft.AspNetCore.AllouMicrosoft.AspNetCore.Appdoivent ajouter une référence de package pour le package dans le fichier projet, même s’ils contiennent une référence de projet à un autre projet à l’aide deMicrosoft.AspNetCore.AllouMicrosoft.AspNetCore.App.Exemple :
MyAppa une référence de package àMicrosoft.AspNetCore.App.MyApp.Testsa une référence de projet àMyApp.csproj.
Ajoutez une référence de package pour
Microsoft.AspNetCore.AppàMyApp.Tests. Pour plus d’informations, consultez Les tests d’intégration sont difficiles à configurer et peuvent s’interrompre sur la maintenance de l’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 pour tirer parti des nouveaux idiomes basés sur le code recommandés dans ASP.NET Core 2.1
Modifications apportées à Main
Les images suivantes montrent les modifications apportées au fichier Program.cs généré par un modèle.
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 :
Le code suivant montre la version 2.1 de Program.cs :
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é :
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 :
- Prise en charge du RGPD dans ASP.NET Core pour
CookiePolicyOptionsetUseCookiePolicy. - Protocole HSTS (HTTP Strict Transport Security) pour
UseHsts. - Exiger HTTPS pour
UseHttpsRedirection. - SetCompatibilityVersion pour
SetCompatibilityVersion(CompatibilityVersion.Version_2_1).
Modifications apportées au code d’authentification
ASP.NET Core 2.1 fournit ASP.NET Core Identity en tant que bibliothèque de classes Razor (RCL).
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.Appest 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 utilisera la bibliothèque de classes d’IdentityRazor. 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 d’Identity ASP.NET Core Razor. 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
IdentityDbContextgé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 :
@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 :
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"parLayout = "/Pages/Shared/_Layout.cshtml".Le fichier _Layout.cshtml présente les modifications suivantes :
<partial name="_CookieConsentPartial" />est ajouté. Pour plus d’informations, consultez Prise en charge du RGPD dans ASP.NET Core.- jQuery passe de 2.2.0 à 3.3.1.
_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.cshtmlPrivacy.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
Privacyest 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 JSON suivant montre l’ancien fichier launchSettings.json généré par un modèle 2.0 :
{
"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 JSON suivant montre le nouveau fichier launchSettings.json généré par un modèle 2.1 :
{
"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 :
- Surcharges de ControllerBase.File
- ControllerBase.PhysicalFile
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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour