Partager via

Migrer de ASP.NET Core 3.1 vers .NET 6

Cet article explique comment mettre à jour un projet ASP.NET Core 3.1 existant vers ASP.NET Core dans .NET 6. Pour effectuer une mise à niveau de ASP.NET Core dans .NET 5 vers .NET 6, consultez Migrer de ASP.NET Core dans .NET 5 vers .NET 6.

Prerequisites

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

Si vous vous appuyez sur un global.json fichier pour cibler une version spécifique du Kit de développement logiciel (SDK) .NET, mettez à jour la version propriété vers la version du SDK .NET 6 installée. Par exemple :

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

Mettre à jour la version cible de .Net Framework

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 de projet, mettez à jour l’attribut Version de chaque référence de package Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.* et System.Net.Http.Json sur 6.0.0 ou version 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 du 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 de ASP.NET Core 3.1 vers .NET 6 n’ont pas besoin d’utiliser le modèle d’hébergement minimal, et Startupl’hôte générique utilisé par les modèles ASP.NET Core 3.1 est entièrement pris en charge.

Pour utiliser Startup avec le nouveau modèle d’hébergement minimal, consultez Utiliser 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 dans .NET 6, consultez les exemples de code migrés vers le nouveau modèle d’hébergement minimal dans ASP.NET Core dans .NET 6 et migrer de ASP.NET Core dans .NET 5 vers .NET 6

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

Migrez les bibliothèques de classes (RCLs) pour tirer parti des nouvelles API ou fonctionnalités introduites dans ASP.NET Core dans .NET 6.

Pour mettre à jour une RCL qui cible des composants :

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

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

  2. Mettez à jour les autres packages vers leurs dernières versions. Les dernières versions sont disponibles sur NuGet.org.

Pour mettre à jour une RCL ciblant MVC, mettez à jour les propriétés suivantes dans le fichier de 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 6.0 pour les applications Blazor, nous vous recommandons de procéder comme suit :

  • Créez un projet Blazor 6.0 depuis 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 les modifications nécessaires 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 ASP.NET Core dans le runtime .NET 6. Considérez la différence de commande suivante docker pull entre ASP.NET Core 3.1 et .NET 6 :

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

Dans le cadre du passage à « .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. Pour plus d’informations, consultez .NET 5.0 – Changement de nom du référentiel Docker (dotnet/dotnet-docker #1939).

Modifications de la 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 UTC

Dans ASP.NET Core 3.1 ou version antérieure, DateTime les valeurs étaient liées au modèle comme heure locale, où le fuseau horaire a été déterminé par le serveur. Les valeurs DateTime liées à partir du formatage d’entrée (JSON) et les valeurs DateTimeOffset étaient liées en tant que fuseaux horaires UTC.

Dans .NET 5 ou version ultérieure, la liaison de modèle lie de manière cohérente les DateTime valeurs avec le 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 des types d’enregistrement C# 9 pour la liaison de modèles, ComplexTypeModelBinderProvider est :

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

Les applications qui dépendent de la présence de ComplexTypeModelBinderProvider dans la collection ModelBinderProviders doivent référencer le nouveau fournisseur de liaison :

- 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’utilisateurs 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();
    }

Pour plus d’informations, consultez Obsolète du middleware DatabaseErrorPage (dotnet/aspnetcore #24987).

Module ASP.NET Core (ANCM)

Si vous n’aviez pas sélectionné le composant module ASP.NET Core (ANCM) lors de l’installation de Visual Studio ou si une version antérieure de l’ANCM est 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. Si vous souhaitez en savoir plus, veuillez consulter la rubrique 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 cassants

Consultez les ressources suivantes :