Migrer d’ASP.NET Core 3.1 vers 6.0

  • Article

Cet article explique comment mettre à jour un projet ASP.NET Core 3.1 existant vers ASP.NET Core 6.0. Pour effectuer une mise à niveau d’ASP.NET Core 5.0 vers la version 6.0, veuillez consulter la rubrique Migrer d’ASP.NET Core 5.0 vers 6.0.

Prérequis

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

Si vous comptez sur un fichier global.json pour cibler une version spécifique du SDK .NET, mettez à jour la propriété version vers la version du SDK .NET 6.0 qui est installée. Par exemple :

{
  "sdk": {
-    "version": "3.1.200"
+    "version": "6.0.100"
  }
}

Mettre à jour le framework cible

Mettez à jour le moniker de framework cible (TFM) du fichier projet vers net6.0 :

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

  <PropertyGroup>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

</Project>

Mettre à jour les références de package

Dans le fichier projet, mettez à jour chaque attribut de référence de package Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.* et System.Net.Http.JsonVersion vers la version 6.0.0 ou ultérieure. Par exemple :

<ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="3.1.6" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="3.1.6" />
-    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="3.1.6" />
-    <PackageReference Include="System.Net.Http.Json" Version="3.2.1" />
+    <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="6.0.0" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="6.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="6.0.0" />
+    <PackageReference Include="System.Net.Http.Json" Version="6.0.0" />
</ItemGroup>

Supprimez les dossiers bin et obj

Vous devrez peut-être supprimer les dossiers bin et obj. Exécutez dotnet nuget locals --clear all pour effacer le cache de package NuGet.

Modèle d'hébergement minimal

Les modèles ASP.NET Core génèrent du code à l’aide du nouveau modèle d’hébergement minimal. Le modèle d’hébergement minimal unifie Startup.cs et Program.cs en un seul fichier Program.cs. ConfigureServices et Configure ne sont plus utilisés. Les applications qui migrent d’ASP.NET Core 3.1 vers la version 6.0 n’ont pas besoin d’utiliser le modèle d’hébergement minimal ; l’utilisation de Startup et de l’hôte générique par les modèles ASP.NET Core 3.1 est entièrement prise en charge.

Pour utiliser Startup avec le nouveau modèle d’hébergement minimal, veuillez consulter la rubrique Utilisez Startup avec le nouveau modèle d’hébergement minimal.

Pour migrer vers le nouveau modèle d’hébergement minimal à l’aide du modèle suivant utilisé par les modèles ASP.NET Core 6.0, veuillez consulter les rubriques Exemples de code migré vers le nouveau modèle d’hébergement minimal dans ASP.NET Core 6.0 et Migrer d’ASP.NET Core 5.0 vers 6.0

Mettre à jour les bibliothèques de classes Razor (RCL)

Migrez les bibliothèques de classes Razor (RCL) pour tirer parti des nouvelles API ou fonctionnalités introduites comme parties d’ASP.NET Core 6.0.

Pour mettre à jour une RCL qui cible des composants :

  1. Mettez à jour les propriétés suivantes dans le fichier projet :

    <Project Sdk="Microsoft.NET.Sdk.Razor">
  <PropertyGroup>
-     <TargetFramework>netstandard2.0</TargetFramework>
-     <RazorLangVersion>3.0</RazorLangVersion>
+     <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  2. Mettez à jour d’autres packages vers leurs dernières versions. Vous trouverez les dernières versions sur NuGet.org.

Pour mettre à jour une RCL ciblant MVC, mettez à jour les propriétés suivantes dans le fichier projet :

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

Blazor

Pour adopter toutes les fonctionnalités 5.0 et les fonctionnalités 6.0 pour les applications Blazor, nous vous recommandons de suivre le processus ci-dessous :

  • Créez un nouveau projet 6.0 Blazor à partir de l'un des modèles de projet Blazor. Pour plus d’informations, consultez Outils pour ASP.NET Core Blazor.
  • Déplacez les composants et le code de l’application vers l’application 6.0 en apportant des modifications pour adopter les nouvelles fonctionnalités 5.0 et 6.0.

Mettre à jour les images Docker

Pour les applications utilisant Docker, mettez à jour vos instructions et scripts DockerfileFROM. Utilisez une image de base qui inclut le runtime ASP.NET Core 6.0. Considérez la différence de commande docker pull suivante entre ASP.NET Core 3.1 et 6.0 :

- docker pull mcr.microsoft.com/dotnet/core/aspnet:3.1
+ docker pull mcr.microsoft.com/dotnet/aspnet:6.0

Dans le cadre du déplacement vers « .NET » comme nom de produit, les images Docker ont été déplacées des référentiels mcr.microsoft.com/dotnet/core vers mcr.microsoft.com/dotnet. Si vous souhaitez en savoir plus, veuillez consulter la rubrique .NET 5.0 - Changement de nom du référentiel Docker (dotnet/dotnet-docker #1939).

Modifications de liaison de modèle dans ASP.NET Core MVC et Razor Pages

Les valeurs DateTime sont liées au modèle en tant qu’heures en temps universel coordonné

Dans ASP.NET Core 3.1 et versions antérieures, les valeurs DateTime étaient liées au modèle en tant qu’heure locale, où le fuseau horaire était déterminé par le serveur. Les valeurs DateTime liées à partir de la mise en forme d’entrée (JSON) et les valeurs DateTimeOffset ont été liées en tant que fuseaux horaires UTC.

Dans ASP.NET Core 5.0 et versions ultérieures, la liaison de modèle lie systématiquement les valeurs DateTime au fuseau horaire UTC.

Pour conserver le comportement précédent, supprimez DateTimeModelBinderProvider dans Startup.ConfigureServices :

services.AddControllersWithViews(options =>
    options.ModelBinderProviders.RemoveType<DateTimeModelBinderProvider>());

ComplexObjectModelBinderProvider \ ComplexObjectModelBinder remplace ComplexTypeModelBinderProvider \ ComplexTypeModelBinder

Pour ajouter la prise en charge de liaison de modèle des types d’enregistrements C# 9 , le ComplexTypeModelBinderProvider est :

  • Annoté comme obsolète.
  • N’est plus inscrit par défaut.

Les applications qui s’appuient sur la présence du ComplexTypeModelBinderProvider dans la collection ModelBinderProviders doivent référencer le nouveau fournisseur de Binder :

- var complexModelBinderProvider = options.ModelBinderProviders.OfType<ComplexTypeModelBinderProvider>();
+ var complexModelBinderProvider = options.ModelBinderProviders.OfType<ComplexObjectModelBinderProvider>();

UseDatabaseErrorPage obsolète

Les modèles ASP.NET Core 3.1 qui incluent une option pour les comptes d’utilisateur individuels génèrent un appel à UseDatabaseErrorPage. UseDatabaseErrorPage est désormais obsolète et doit être remplacé par une combinaison de AddDatabaseDeveloperPageExceptionFilter et UseMigrationsEndPoint, comme indiqué dans le code suivant :

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(
            Configuration.GetConnectionString("DefaultConnection")));
+   services.AddDatabaseDeveloperPageExceptionFilter();
    services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
        .AddEntityFrameworkStores<ApplicationDbContext>();
    services.AddRazorPages();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
+       app.UseMigrationsEndPoint();
-       app.UseDatabaseErrorPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

Si vous souhaitez en savoir plus, veuillez consulter la rubrique Rendre obsolète l’intergiciel DatabaseErrorPage (dotnet/aspnetcore #24987).

Module de base ASP.NET (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.

Changement de nom de l'application

Dans .NET 6, WebApplicationBuilder normalise le chemin racine du contenu pour qu'il se termine par un DirectorySeparatorChar. La plupart des applications migrées depuis HostBuilder ou WebHostBuilder n'auront pas le même nom d'application car elles ne sont pas normalisées. Si vous souhaitez en savoir plus, veuillez consulter la rubrique SetApplicationName.

Examiner les changements avec rupture

Consultez les ressources suivantes :