Migrer d’ASP.NET Core 2.2 vers 3.0

Par Scott Addie et Rick Anderson

Cet article explique comment mettre à jour un projet ASP.NET Core 2.2 existant vers ASP.NET Core 3.0. Il peut être utile de créer un projet ASP.NET Core 3.0 pour :

• Effectuer la comparaison avec le code ASP.NET Core 2.2.
• Copier les modifications appropriées dans votre projet ASP.NET Core 3.0.

Prérequis

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

Si votre solution repose sur un fichier global.json pour cibler une version spécifique du SDK .NET Core, mettez à jour sa propriété version vers la version 3.0 installée sur votre ordinateur :

{
  "sdk": {
    "version": "3.0.100"
  }
}

Mettre à jour le fichier projet

Mettre à jour la version cible de .Net Framework

ASP.NET Core 3.0 ou version ultérieure s’exécute uniquement sur .NET Core. Configurez le moniker de framework cible (TFM) sur netcoreapp3.0 :

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

</Project>

Supprimer les références de package obsolètes

Un grand nombre de packages NuGet ne sont pas produits pour ASP.NET Core 3.0. Ces références de package doivent être supprimées du fichier projet. Prenons l’exemple du fichier projet suivant pour une application web ASP.NET Core 2.2 :

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

  <PropertyGroup>
    <TargetFramework>netcoreapp2.2</TargetFramework>
    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App"/>
    <PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.2.0" PrivateAssets="All" />
  </ItemGroup>

</Project>

Fichier projet mis à jour pour ASP.NET Core 3.0 :

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

</Project>

Le fichier projet ASP.NET Core 3.0 mis à jour :

• Dans le <PropertyGroup> :

  • Met à jour le TFM vers netcoreapp3.0
  • Supprime l’élément <AspNetCoreHostingModel>. Pour plus d’informations, consultez la section Modèle d’hébergement in-process du présent document.

• Dans le <ItemGroup> :

  • Microsoft.AspNetCore.App est supprimé. Pour plus d’informations, consultez la section Références d’infrastructure du présent document.
  • Microsoft.AspNetCore.Razor.Design est supprimé et, dans la liste suivante, les packages ne sont plus produits.

Pour afficher la liste complète des packages qui ne sont plus produits, sélectionnez la liste de développement suivante :

Examiner les changements cassants

Examiner les changements cassants

Références d’infrastructure

Les fonctionnalités d’ASP.NET Core qui étaient disponibles via l’un des packages répertoriés ci-dessus sont disponibles dans le cadre de l’infrastructure partagée Microsoft.AspNetCore.App. L’infrastructure partagée est l’ensemble d’assemblys (fichiers .dll) installés sur l’ordinateur et comprend un composant runtime et un pack de ciblage. Pour plus d’informations, consultez Le framework partagé.

• Les projets qui ciblent le Kit de développement logiciel (SDK) Microsoft.NET.Sdk.Web référencent implicitement l’infrastructure Microsoft.AspNetCore.App.

  Aucune référence supplémentaire n’est requise pour ces projets :

  <Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
      <TargetFramework>netcoreapp3.0</TargetFramework>
    </PropertyGroup>
      ...
  </Project>
  

• Les projets qui ciblent le SDK Microsoft.NET.Sdk ou Microsoft.NET.Sdk.Razor doivent ajouter un explicite FrameworkReference à Microsoft.AspNetCore.App :

  <Project Sdk="Microsoft.NET.Sdk.Razor">
    <PropertyGroup>
      <TargetFramework>netcoreapp3.0</TargetFramework>
    </PropertyGroup>
  
    <ItemGroup>
      <FrameworkReference Include="Microsoft.AspNetCore.App" />
    </ItemGroup>
      ...
  </Project>
  

Builds dépendants de l’infrastructure avec Docker

Les builds dépendants de l’infrastructure des applications console qui utilisent un package dépendant de l’infrastructure partagée ASP.NET Core peuvent générer l’erreur d’exécution suivante :

It was not possible to find any compatible framework version
The specified framework 'Microsoft.AspNetCore.App', version '3.0.0' was not found.
  - No frameworks were found.

Microsoft.AspNetCore.App est l’infrastructure partagée qui contient le runtime ASP.NET Core et est uniquement présente sur l’image Docker dotnet/core/aspnet. Le SDK 3.0 réduit la taille des builds dépendants de l’infrastructure avec ASP.NET Core en n’incluant pas les copies en double des bibliothèques disponibles dans l’infrastructure partagée. Il s’offre une économie potentielle pouvant atteindre 18 Mo. Cependant, il exige que le runtime ASP.NET Core soit présent/installé pour exécuter l’application.

Pour déterminer si l’application a une dépendance (directe ou indirecte) sur l’infrastructure partagée ASP.NET Core, examinez le fichier runtimeconfig.json généré lors de la génération/publication de votre application. Le fichier JSON suivant présente une dépendance vis-à-vis de l’infrastructure partagée ASP.NET Core :

{
  "runtimeOptions": {
    "tfm": "netcoreapp3.0",
    "framework": {
      "name": "Microsoft.AspNetCore.App",
      "version": "3.0.0"
    },
    "configProperties": {
      "System.GC.Server": true
    }
  }
}

Pour les applications utilisant Docker, utilisez une image de base contenant ASP.NET Core 3.0. Par exemple, docker pull mcr.microsoft.com/dotnet/core/aspnet:3.0

Ajouter des références de package pour les assemblys supprimés

ASP.NET Core 3.0 supprime certains assemblys qui faisaient précédemment partie de la référence du package Microsoft.AspNetCore.App. Pour visualiser les assemblys qui ont été supprimés, comparez les deux dossiers de l’infrastructure partagée. Par exemple, pour une comparaison des versions 2.2.7 et 3.0.0 :

Pour continuer à utiliser les fonctionnalités fournies par les assemblys supprimés, référencez les versions 3.0 des packages correspondants :

• Une application web générée par un modèle avec des comptes d’utilisateur individuels exige d’ajouter les packages suivants :

  <Project Sdk="Microsoft.NET.Sdk.Web">
  
    <PropertyGroup>
      <TargetFramework>netcoreapp3.0</TargetFramework>
      <UserSecretsId>My-secret</UserSecretsId>
    </PropertyGroup>
  
    <ItemGroup>
      <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="3.0.0" />
      <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="3.0.0" />
      <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="3.0.0" />
      <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="3.0.0" />
      <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="3.0.0" />
    </ItemGroup>
  
  </Project>
  

• Microsoft.EntityFrameworkCore

  Pour plus d’informations sur le référencement du package spécifique au fournisseur de base de données, consultez l’article Fournisseurs de base de données.

• INTERFACE UTILISATEUR Identity

  La prise en charge de l’interface utilisateur Identity peut être ajoutée en référençant le package d’interface utilisateur Microsoft.AspNetCoreIdentity.

• Services SPA

  • Microsoft.AspNetCore.SpaServices
  • Microsoft.AspNetCore.SpaServices.Extensions

• Authentification : la prise en charge des flux d’authentification tiers est assurée sous forme de packages NuGet :

  • Facebook OAuth (Microsoft.AspNetCore.Authentication.Facebook)
  • Google OAuth (Microsoft.AspNetCore.Authentication.Google)
  • Authentification de compte Microsoft (Microsoft.AspNetCore.Authentication.MicrosoftAccount)
  • Authentification OpenID Connect (Microsoft.AspNetCore.Authentication.OpenIdConnect)
  • Jeton du porteur OpenID Connect (Microsoft.AspNetCore.Authentication.JwtBearer)
  • Twitter OAuth (Microsoft.AspNetCore.Authentication.Twitter)
  • Authentification WsFederation (Microsoft.AspNetCore.Authentication.WsFederation)

• Prise en charge de la mise en forme et de la négociation de contenu pour System.Net.HttpClient : le package NuGet Microsoft.AspNet.WebApi.Client fournit une extensibilité utile à System.Net.HttpClient avec des API comme ReadAsAsync et PostJsonAsync. Toutefois, ce package dépend de Newtonsoft.Json, et non de System.Text.Json. Par exemple, cela signifie que les noms de la propriété de sérialisation spécifiés par JsonPropertyNameAttribute (System.Text.Json) sont ignorés. Il existe un package NuGet plus récent qui contient des méthodes d’extension similaires, mais utilise System.Text.Json : System.Net.Http.Json.

• RazorCompilation au runtime : la prise en charge de la compilation au runtime des vues et des pages Razor fait désormais partie de Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

• Prise en charge de MVC Newtonsoft.Json (Json.NET) : la prise en charge de l’utilisation de MVC avec Newtonsoft.Json fait désormais partie de Microsoft.AspNetCore.Mvc.NewtonsoftJson.

Modifications au démarrage

L’image suivante représente les lignes supprimées et modifiées dans une application web Razor Pages ASP.NET Core 2.2 :

Dans l’image précédente, le code supprimé est affiché en rouge. Le code supprimé n’affiche pas le code d’options cookie, qui a été supprimé avant de comparer les fichiers.

L’image suivante représente les lignes ajoutées et modifiées dans une application web Razor Pages ASP.NET Core 3.0 :

Dans l’image précédente, le code ajouté est affiché en vert. Pour plus d’informations sur les modifications suivantes :

• services.AddMvc en services.AddRazorPages : consultez la section Inscription du service MVC du présent document.
• CompatibilityVersion : consultez l’article Version de compatibilité pour ASP.NET Core MVC.
• IHostingEnvironment en IWebHostEnvironment : consultez cette annonce GitHub (seulement disponible en anglais).
• app.UseAuthorization a été ajouté aux modèles pour démontrer que l’intergiciel d’autorisation de commande devait être ajouté. Si l’application n’utilise pas l’autorisation, vous pouvez supprimer l’appel à app.UseAuthorization en toute sécurité.
• app.UseEndpoints : consultez Razor Pages ou la section Migrer Startup.Configure du présent document.

Prise en charge de l’analyseur

Les projets qui ciblent Microsoft.NET.Sdk.Web renvoient implicitement aux analyseurs précédemment fournis dans le cadre du package Microsoft.AspNetCore.Mvc.Analyzers. Aucune référence supplémentaire n’est requise pour les activer.

Si votre application utilise les analyseurs d’API précédemment fournis avec le package Microsoft.AspNetCore.Mvc.Api.Analyzers, modifiez le fichier projet de sorte à renvoyer aux analyseurs fournis dans le cadre du SDK web .NET Core :

<Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
        <TargetFramework>netcoreapp3.0</TargetFramework>
        <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
    </PropertyGroup>

    ...
</Project>

Bibliothèque de classes Razor

Les projets de bibliothèque de classes Razor qui fournissent les composants d’interface utilisateur pour MVC doivent définir la propriété AddRazorSupportForMvc dans le fichier projet :

<PropertyGroup>
  <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
</PropertyGroup>

Modèle d’hébergement in-process

Les projets correspondent par défaut au modèle d’hébergement in-process dans ASP.NET Core 3.0 ou version ultérieure. Vous pouvez éventuellement supprimer la propriété <AspNetCoreHostingModel> dans le fichier projet si sa valeur est InProcess.

Kestrel

Configuration

Migrer la configuration Kestrel vers le générateur d’hôtes web fourni par ConfigureWebHostDefaults (Program.cs) :

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseStartup<Startup>();
        });

Si l’application crée l’hôte manuellement avec ConfigureWebHost au lieu de ConfigureWebHostDefaults, appelez UseKestrel sur le générateur d’hôtes web :

public static void Main(string[] args)
{
    var host = new HostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureWebHost(webBuilder =>
        {
            webBuilder.UseKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseIISIntegration()
            .UseStartup<Startup>();
        })
        .Build();

    host.Run();
}

Adaptateurs de connexion remplacés par l’intergiciel de connexion

Les adaptateurs de connexion (Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter) ont été supprimés de Kestrel. Remplacez les adaptateurs de connexion par l’intergiciel de connexion. L’intergiciel de connexion est similaire à l’intergiciel HTTP dans le pipeline ASP.NET Core, mais correspond aux connexions de niveau inférieur. HTTPS et la journalisation des connexions :

• ont été déplacés des adaptateurs de connexion vers l’intergiciel de connexion.
• Ces méthodes d’extension fonctionnent comme dans les précédentes versions d’ASP.NET Core.

Pour plus d’informations, consultez l’exemple TlsFilterConnectionHandler dans la section ListenOptions.Protocols de l’Kestrelarticle sur .

Abstractions de transport supprimées et rendues publiques

La couche de transport Kestrel a été exposée en tant qu’interface publique dans Connections.Abstractions. Dans le cadre de ces mises à jour :

• Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions et les types associés ont été supprimés.
• NoDelay a été déplacé de ListenOptions vers les options de transport.
• Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode a été supprimé de KestrelServerOptions.

Pour plus d’informations, consultez les ressources GitHub suivantes :

• Abstractions réseau client/serveur (dotnet/AspNetCore #10308)
• Implémenter une nouvelle abstraction d’écouteur de base et remise en plateforme Kestrel au-dessus (dotnet/AspNetCore #10321)

En-têtes d’amorce de fin de requête Kestrel

Pour les applications qui ciblent des versions antérieures d’ASP.NET Core :

• Kestrel ajoute des en-têtes d’amorce de fin segmentés HTTP/1.1 dans la collection d’en-têtes de requête.
• Les amorces de fin sont disponibles une fois que le corps de la requête a été lu jusqu’à la fin.

Cela provoque certains problèmes d’ambiguïté entre les en-têtes et les amorces de fin, qui déplacent les amorces de fin vers une nouvelle collection (RequestTrailerExtensions) dans la version 3.0.

Les amorces de fin de requête HTTP/2 sont les suivantes :

• Non disponible dans ASP.NET Core 2.2.
• Disponible dans la version 3.0 en tant que RequestTrailerExtensions.

De nouvelles méthodes d’extension de requête ont été ajoutées pour accéder à ces amorces de fin. Comme avec HTTP/1.1, les amorces de fin sont disponibles une fois que le corps de la requête a été lu jusqu’à la fin.

Pour la version 3.0, les méthodes RequestTrailerExtensions suivantes sont disponibles :

• GetDeclaredTrailers : obtient l’en-tête Trailer pour la requête qui répertorie les amorces de fin à attendre après le corps.
• SupportsTrailers : indique si la requête prend en charge la réception des en-têtes d’amorce de fin.
• CheckTrailersAvailable : détermine si la requête prend en charge les codes de fin et s’ils sont disponibles pour la lecture. Cette vérification ne suppose pas qu’il existe des amorces de fin à lire. Il peut n’y avoir aucune amorce de fin à lire même si true est retourné par cette méthode.
• GetTrailer : obtient l’en-tête de l’amorce de fin demandé à partir de la réponse. Vérifiez SupportsTrailers avant d’appeler GetTrailer, ou un NotSupportedException peut se produire si la requête ne prend pas en charge les en-têtes de fin.

Pour plus d’informations, consultez la section Placer des amorces de fin de requête dans une collection distincte (dotnet/AspNetCore #10410) (seulement disponible en anglais).

AllowSynchronousIO désactivé

AllowSynchronousIO active ou désactive les API d’E/S synchrones, comme HttpRequest.Body.Read, HttpResponse.Body.Writeet Stream.Flush. Ces API sont une source de privation de threads qui entraîne des incidents d’application. Dans la version 3.0, AllowSynchronousIO est désactivé par défaut. Pour plus d’informations, consultez la section E/S synchrones de cet Kestrelarticle.

Lorsqu’elles sont nécessaires, vous pouvez activer les E/S synchrones en configurant l’option AllowSynchronousIO sur le serveur utilisé (lors de l’appel de ConfigureKestrel, par exemple, si vous utilisez Kestrel). Notez que les serveurs (Kestrel, HttpSys, TestServer, etc.) ont tous leur propre AllowSynchronousIO option qui n’affecte pas les autres serveurs. Les E/S synchrones peuvent être activées pour tous les serveurs par requête avec l’option IHttpBodyControlFeature.AllowSynchronousIO :

var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();

if (syncIOFeature != null)
{
    syncIOFeature.AllowSynchronousIO = true;
}

Si vous rencontrez des problèmes avec les implémentations TextWriter ou d’autres flux qui appellent des API synchrones dans Dispose, appelez plutôt la nouvelle API DisposeAsync.

Pour plus d’informations, consultez l’annonce [Annonce] AllowSynchronousIO désactivé sur tous les serveurs (dotnet/AspNetCore #7644) (seulement disponible en anglais).

Mise en mémoire tampon du formateur de sortie

Les formateurs de sortie basés sur Newtonsoft.Json, XmlSerializeret DataContractSerializer prennent uniquement en charge la sérialisation synchrone. Pour que ces formateurs puissent fonctionner avec les restrictions AllowSynchronousIO du serveur, MVC met en mémoire tampon la sortie de ces formateurs avant d’écrire sur le disque. Suite à la mise en mémoire tampon, MVC inclut l’en-tête Content-Length lorsqu’il répond avec ces formateurs.

System.Text.Json prend en charge la sérialisation asynchrone et, par conséquent, le formateur basé sur System.Text.Json n’effectue pas la mise en mémoire tampon. Envisagez d’utiliser ce formateur pour améliorer les performances.

Pour désactiver la mise en mémoire tampon, les applications peuvent configurer SuppressOutputFormatterBuffering au démarrage :

services.AddControllers(options => options.SuppressOutputFormatterBuffering = true)

Notez que cela peut entraîner la levée d’une exception de runtime par l’application si AllowSynchronousIO n’est pas également configuré.

Assembly Microsoft.AspNetCore.Server.Kestrel.Https supprimé

Dans ASP.NET Core 2.1, les contenus de Microsoft.AspNetCore.Server.Kestrel.Https.dll ont été déplacés dans Microsoft.AspNetCore.Server.Kestrel.Core.dll. Il s’agit d’une mise à jour non cassante à l’aide des attributs TypeForwardedTo. Avec la version 3.0, l’assembly Microsoft.AspNetCore.Server.Kestrel.Https.dll et le package NuGet ont été supprimés.

Les bibliothèques faisant référence à Microsoft.AspNetCore.Server.Kestrel.Https doivent mettre à jour toutes les dépendances ASP.NET Core vers la version 2.1 ou ultérieure.

Les applications et les bibliothèques qui ciblent ASP.NET Core 2.1 ou version ultérieure doivent supprimer toutes les références directes au package Microsoft.AspNetCore.Server.Kestrel.Https.

Prise en charge de Newtonsoft.Json (Json.NET)

Dans le cadre du travail visant à améliorer l’infrastructure partagée ASP.NET Core, Newtonsoft.Json (Json.NET) a été supprimé de l’infrastructure partagée ASP.NET Core.

Le sérialiseur JSON par défaut pour ASP.NET Core est désormais System.Text.Json, qui est nouveau dans .NET Core 3.0. Envisagez d’utiliser System.Text.Json lorsque cela est possible. Il offre de hautes performances et ne nécessite aucune dépendance de bibliothèque supplémentaire. Toutefois, étant donné que System.Text.Json est nouveau, il se peut qu’il n’offre pas actuellement toutes les fonctionnalités dont votre application a besoin. Pour plus d’informations, consultez l’article Comment migrer de Newtonsoft.Json vers System.Text.Json.

Utiliser Newtonsoft.Json dans un projet SignalR ASP.NET Core 3.0

• Installez le package NuGet Microsoft.AspNetCore.SignalR.Protocols.NewtonsoftJson.

• Sur le client, chaînez un appel de méthode AddNewtonsoftJsonProtocol à l’instance HubConnectionBuilder :

  new HubConnectionBuilder()
      .WithUrl("/chathub")
      .AddNewtonsoftJsonProtocol(...)
      .Build();
  

• Sur le serveur, chaînez un appel de méthode AddNewtonsoftJsonProtocol à l’appel de méthode AddSignalR dans Startup.ConfigureServices :

  services.AddSignalR()
      .AddNewtonsoftJsonProtocol(...);
  

Utiliser Newtonsoft.Json dans un projet MVC ASP.NET Core 3.0

• Installez le package Microsoft.AspNetCore.Mvc.NewtonsoftJson.

• Mettez à jour Startup.ConfigureServices pour appeler AddNewtonsoftJson.

  services.AddMvc()
      .AddNewtonsoftJson();
  

  AddNewtonsoftJson est compatible avec les méthodes d’inscription du service MVC :

  • AddRazorPages
  • AddControllersWithViews
  • AddControllers

  services.AddControllers()
      .AddNewtonsoftJson();
  

  Les paramètres Newtonsoft.Json peuvent être définis dans l’appel sur AddNewtonsoftJson :

  services.AddMvc()
      .AddNewtonsoftJson(options =>
             options.SerializerSettings.ContractResolver =
                new CamelCasePropertyNamesContractResolver());
  

  Note : si la méthode AddNewtonsoftJson n’est pas disponible, vérifiez que vous avez installé le package Microsoft.AspNetCore.Mvc.NewtonsoftJson. Une erreur courante consiste à installer le package Newtonsoft.Json au lieu du package Microsoft.AspNetCore.Mvc.NewtonsoftJson.

Pour plus d’informations, consultez la section Ajouter la prise en charge du format JSON basé sur Newtonsoft.Json.

Inscription du service MVC

ASP.NET Core 3.0 ajoute de nouvelles options pour inscrire les scénarios MVC dans Startup.ConfigureServices.

Trois nouvelles méthodes d’extension de niveau supérieur dédiées aux scénarios MVC sur IServiceCollection sont disponibles. Les modèles utilisent ces nouvelles méthodes au lieu d’AddMvc. Toutefois, AddMvc continue de se comporter comme dans les versions précédentes.

L’exemple suivant ajoute la prise en charge des contrôleurs et des fonctionnalités liées à l’API, mais pas celle des vues ou des pages. Le modèle d’API utilise ce code :

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
}

L’exemple suivant ajoute la prise en charge des contrôleurs, des fonctionnalités liées à l’API, et des vues, mais pas celle des pages. Le modèle d’application web (MVC) utilise ce code :

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
}

L’exemple suivant ajoute la prise en charge de Razor Pages et la prise en charge minimale du contrôleur. Le modèle d’application web utilise ce code :

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();
}

Les nouvelles méthodes peuvent également être combinées. L’exemple suivant équivaut à appeler AddMvc dans ASP.NET Core 2.2 :

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
    services.AddRazorPages();
}

Code de démarrage de routage

Si une application appelle UseMvc ou UseSignalR, migrez l’application vers le routage des points de terminaison si possible. Pour améliorer la compatibilité du routage des points de terminaison avec les versions précédentes de MVC, nous avons rétabli certaines des modifications apportées à la génération d’URL introduites dans ASP.NET Core 2.2. Si vous avez rencontré des problèmes lors de l’utilisation du routage des points de terminaison avec la version 2.2, vous devriez enregistrer des améliorations dans ASP.NET Core 3.0 avec les exceptions suivantes :

• Si l’application implémente IRouter ou hérite de Route, utilisez DynamicRouteValuesTransformer à la place.
• Si l’application accède directement à RouteData.Routers dans MVC pour analyser les URL, vous pouvez la remplacer en utilisant LinkParser.ParsePathByEndpointName.
  • Définissez le routage avec un nom de route.
  • Utilisez LinkParser.ParsePathByEndpointName et transmettez le nom de route souhaité.

Le routage des points de terminaison prend en charge la même syntaxe de modèle de route et les mêmes fonctionnalités de création de routes que IRouter. Le routage des points de terminaison prend en charge IRouteConstraint. Le routage des points de terminaison prend en charge [Route], [HttpGet] et les autres attributs de routage MVC.

Pour la plupart des applications, seul Startup nécessite des modifications.

Migrer Startup.Configure

Conseil d’ordre général :

• Ajoutez UseRouting.

• Si l’application appelle UseStaticFiles, placez UseStaticFiles avant UseRouting.

• Si l’application utilise des fonctionnalités d’authentification/autorisation (comme AuthorizePage ou [Authorize]), passez l’appel à UseAuthentication et UseAuthorizationaprèsUseRouting et UseCors, mais avant UseEndpoints :

  public void Configure(IApplicationBuilder app)
  {
    ...
  
    app.UseStaticFiles();
  
    app.UseRouting();
    app.UseCors();
  
    app.UseAuthentication();
    app.UseAuthorization();
  
    app.UseEndpoints(endpoints => {
       endpoints.MapControllers();
    });
  

• Remplacez UseMvc ou UseSignalR par UseEndpoints.

• Si l’application utilise des scénarios CORS (comme [EnableCors]), passez l’appel à UseCors avant tout autre intergiciel utilisant CORS (par exemple, passez UseCors avant UseAuthentication, UseAuthorization et UseEndpoints).

• Remplacez IHostingEnvironment par IWebHostEnvironment et ajoutez une instruction using pour l’espace de noms Microsoft.AspNetCore.Hosting.

• Remplacez IApplicationLifetime par IHostApplicationLifetime (espace de noms Microsoft.Extensions.Hosting).

• Remplacez EnvironmentName par Environments (espace de noms Microsoft.Extensions.Hosting).

Le code suivant est un exemple de Startup.Configure dans une application ASP.NET Core 2.2 classique :

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseStaticFiles();

    app.UseAuthentication();

    app.UseSignalR(hubs =>
    {
        hubs.MapHub<ChatHub>("/chat");
    });

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

Après la mise à jour du code Startup.Configure précédent :

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseStaticFiles();

    app.UseRouting();

    app.UseCors();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chat");
        endpoints.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");
    });
}

Contrôles d'intégrité

Les contrôles d’intégrité utilisent le routage des points de terminaison avec l’hôte générique. Dans Startup.Configure, appelez MapHealthChecks sur le générateur de points de terminaison avec l’URL du point de terminaison ou le chemin relatif :

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
});

Les points de terminaison de contrôle d’intégrité peuvent :

• Spécifier un ou plusieurs hôtes/ports autorisés.
• Exiger une autorisation.
• Exiger CORS.

Pour plus d’informations, consultez Contrôles d’intégrité dans ASP.NET Core.

Conseils sur les intergiciels de sécurité

La prise en charge de l’autorisation et de CORS est unifiée autour de l’approche par intergiciel. Cela permet d’utiliser les mêmes intergiciels et les mêmes fonctionnalités dans ces scénarios. Cette version fournit un intergiciel d’autorisation mis à jour. L’intergiciel CORS a été amélioré pour comprendre les attributs utilisés par les contrôleurs MVC.

CORS

Auparavant, CORS pouvait être difficile à configurer. L’intergiciel était fourni pour certains cas d’usage, alors que les filtres MVC étaient destinés à être utilisés sans intergiciel dans les autres cas d’usage. Avec ASP.NET Core 3.0, nous recommandons que toutes les applications qui ont besoin de CORS utilisent l’intergiciel CORS en tandem avec le routage des points de terminaison. UseCors peut être fourni avec une stratégie par défaut. Si nécessaire, les attributs [EnableCors] et [DisableCors] peuvent être utilisés pour remplacer la stratégie par défaut.

Dans l’exemple suivant :

• CORS est activé pour tous les points de terminaison avec la stratégie nommée default.
• La classe MyController désactive CORS avec l’attribut [DisableCors].

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseCors("default");

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

[DisableCors]
public class MyController : ControllerBase
{
    ...
}

Autorisation

Dans les versions antérieures d’ASP.NET Core, la prise en charge des autorisations était assurée avec l’attribut [Authorize]. L’intergiciel d’autorisation n’était pas disponible. Dans ASP.NET Core 3.0, l’intergiciel d’autorisation est requis. Nous vous recommandons de placer l’intergiciel d’autorisation ASP.NET Core (UseAuthorization) immédiatement après UseAuthentication. Le middleware d’autorisation peut également être configuré avec une stratégie par défaut qui peut être remplacée.

Dans ASP.NET Core 3.0 ou version ultérieure, UseAuthorization est appelé dans Startup.Configure, et le HomeController suivant exige un utilisateur connecté :

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

public class HomeController : Controller
{
    [Authorize]
    public IActionResult BuyWidgets()
    {
        ...
    }
}

Lorsque vous utilisez le routage des points de terminaison, nous recommandons de ne pas configurer AuthorizeFilter, mais de s’appuyer sur l’intergiciel d’autorisation. Si l’application utilise un AuthorizeFilter comme filtre global dans MVC, nous recommandons de refactoriser le code pour fournir une stratégie dans l’appel à AddAuthorization.

DefaultPolicy étant initialement configurée pour exiger une authentification, aucune configuration supplémentaire n’est requise. Dans l’exemple suivant, les points de terminaison MVC sont marqués comme RequireAuthorization, de sorte que toutes les requêtes doivent être autorisées en fonction de DefaultPolicy. Toutefois, le HomeController autorise l’accès sans que l’utilisateur se connecte à l’application en raison de [AllowAnonymous] :

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute().RequireAuthorization();
    });
}

[AllowAnonymous]
public class HomeController : Controller
{
    ...
}

Autorisation pour les points de terminaison spécifiques

L’autorisation peut également être configurée pour des classes spécifiques de points de terminaison. Le code suivant est un exemple de conversion d’une application MVC qui a configuré une application globale AuthorizeFilter en une application dotée d’une stratégie spécifique qui exige une autorisation :

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

    static readonly string _RequireAuthenticatedUserPolicy = 
                            "RequireAuthenticatedUserPolicy";
    public IConfiguration Configuration { get; }

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

        // Pre 3.0:
        // services.AddMvc(options => options.Filters.Add(new AuthorizeFilter(...));

        services.AddControllersWithViews();
        services.AddRazorPages();
        services.AddAuthorization(o => o.AddPolicy(_RequireAuthenticatedUserPolicy,
                        builder => builder.RequireAuthenticatedUser()));

    }

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

        app.UseRouting();

        app.UseAuthentication();
        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute()
                .RequireAuthorization(_RequireAuthenticatedUserPolicy);
            endpoints.MapRazorPages();
        });
    }
}

Les stratégies peuvent également être personnalisées. DefaultPolicy est configurée pour exiger l’authentification :

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

    public IConfiguration Configuration { get; }

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

        services.AddControllersWithViews();
        services.AddRazorPages();
        services.AddAuthorization(options =>
        {
            options.DefaultPolicy = new AuthorizationPolicyBuilder()
              .RequireAuthenticatedUser()
              .Build();
        });

    }

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

        app.UseRouting();

        app.UseAuthentication();
        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute().RequireAuthorization();
            endpoints.MapRazorPages();
        });
    }
}

[AllowAnonymous]
public class HomeController : Controller
{

Vous pouvez également configurer tous les points de terminaison pour exiger une autorisation sans [Authorize] ou RequireAuthorization, en configurant une FallbackPolicy. FallbackPolicy est différente de DefaultPolicy. DefaultPolicy est déclenchée par [Authorize] ou RequireAuthorization, tandis que FallbackPolicy est déclenchée lorsqu’aucune autre stratégie n’est définie. FallbackPolicy est initialement configurée pour autoriser les requêtes sans autorisation.

L’exemple suivant est identique à l’exemple DefaultPolicy précédent, mais utilise FallbackPolicy pour toujours exiger l’authentification sur tous les points de terminaison, sauf quand [AllowAnonymous] est spécifié :

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddAuthorization(options =>
    {
        options.FallbackPolicy = new AuthorizationPolicyBuilder()
          .RequireAuthenticatedUser()
          .Build();
    });
}

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

[AllowAnonymous]
public class HomeController : Controller
{
    ...
}

L’autorisation par intergiciel fonctionne sans que l’infrastructure ait une connaissance spécifique de l’autorisation. Par instance, les contrôles d’intégrité n’ont aucune connaissance spécifique de l’autorisation. En revanche, les contrôles d’intégrité peuvent avoir une stratégie d’autorisation configurable appliquée par un intergiciel.

En outre, chaque point de terminaison peut personnaliser ses propres exigences d’autorisation. Dans l’exemple suivant, UseAuthorization traite l’autorisation avec DefaultPolicy mais le point de terminaison de contrôle d’intégrité /healthz exige un utilisateur admin :

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints
            .MapHealthChecks("/healthz")
            .RequireAuthorization(new AuthorizeAttribute(){ Roles = "admin", });
    });
}

La protection est implémentée pour certains scénarios. Endpoints Middleware lève une exception si une autorisation ou une stratégie CORS est ignorée en raison d’un intergiciel manquant. La prise en charge de l’analyseur pour fournir des commentaires supplémentaires sur une configuration incorrecte est en cours.

Gestionnaires d’autorisation personnalisés

Si l’application utilise des gestionnaires d’autorisation personnalisés, le routage des points de terminaison transmet aux gestionnaires un type de ressource différent de celui de MVC. Les gestionnaires qui s’attendent à ce que la ressource de contexte du gestionnaire d’autorisation soit de type AuthorizationFilterContext (type de ressource fourni par les filtres MVC) doivent être mis à jour pour gérer les ressources de type RouteEndpoint (type de ressource donné aux gestionnaires d’autorisation par le routage des points de terminaison).

MVC utilise toujours les ressources AuthorizationFilterContext. Par conséquent, si l’application utilise des filtres d’autorisation MVC avec l’autorisation du routage des points de terminaison, il peut être nécessaire de gérer les deux types de ressources.

SignalR

Le mappage des hubs SignalR se déroule désormais dans UseEndpoints.

Mappez chaque hub avec MapHub. Comme avec les versions précédentes, chaque hub est explicitement répertorié.

Dans l’exemple suivant, la prise en charge du hub SignalRChatHub a été ajoutée :

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>();
    });
}

Une nouvelle option permet decontrôler les limites de taille des messages à partir des clients. Par exemple, dans Startup.ConfigureServices :

services.AddSignalR(hubOptions =>
{
    hubOptions.MaximumReceiveMessageSize = 32768;
});

Dans ASP.NET Core 2.2, vous pouviez définir TransportMaxBufferSize qui contrôlait efficacement la taille maximale des messages. Dans ASP.NET Core 3.0, cette option contrôle désormais uniquement la taille maximale avant l’observation de la contre-pression.

Assemblys SignalR dans l’infrastructure partagée

Les assemblys SignalR ASP.NET Core côté serveur sont désormais installés avec le SDK .NET Core. Pour plus d’informations, consultez la section Supprimer les références de package obsolètes du présent document.

Contrôleurs MVC

Le mappage des contrôleurs se déroule désormais dans UseEndpoints.

Ajoutez MapControllers si l’application utilise le routage d’attributs. Étant donné que le routage inclut la prise en charge de nombreuses infrastructures dans ASP.NET Core 3.0 ou version ultérieure, l’ajout de contrôleurs routés par attribut est une option à activer.

Remplacez le code suivant :

• MapRoute avec MapControllerRoute
• MapAreaRoute avec MapAreaControllerRoute

Étant donné que le routage prend désormais en charge bien plus d’éléments que MVC, la terminologie a changé pour que ces méthodes reflètent clairement leur action. Les routes conventionnelles (comme MapControllerRoute/MapAreaControllerRoute/MapDefaultControllerRoute) s’appliquent dans l’ordre dans lequel elles sont ajoutées. Placez d’abord les routes les plus spécifiques (comme celles d’une zone).

Dans l’exemple suivant :

• MapControllers ajoute la prise en charge des contrôleurs routés par attribut.
• MapAreaControllerRoute ajoute une route conventionnelle pour les contrôleurs d’une zone.
• MapControllerRoute ajoute une route conventionnelle pour les contrôleurs.

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapAreaControllerRoute(
            "admin",
            "admin",
            "Admin/{controller=Home}/{action=Index}/{id?}");
        endpoints.MapControllerRoute(
            "default", "{controller=Home}/{action=Index}/{id?}");
    });
}

Suppression du suffixe asynchrone dans le nom des actions des contrôleurs

Dans ASP.NET Core 3.0, ASP.NET Core MVC supprime le suffixe Async dans le nom des actions des contrôleurs. Cette nouvelle valeur par défaut affecte le routage et la génération de liens. Par exemple :

public class ProductsController : Controller
{
    public async Task<IActionResult> ListAsync()
    {
        var model = await _dbContext.Products.ToListAsync();
        return View(model);
    }
}

Avant ASP.NET Core 3.0 :

• L’action précédente était accessible avec la route Products/ListAsync.

• La génération de liens exigeait de définir le suffixe Async. Par exemple :

  <a asp-controller="Products" asp-action="ListAsync">List</a>
  

Avec ASP.NET Core 3.0 :

• L’action précédente peut être accessible avec la route Products/List.

• La génération de liens n’exige pas de spécifier le suffixe Async. Par exemple :

  <a asp-controller="Products" asp-action="List">List</a>
  

Ce changement n’affecte pas les noms spécifiés à l’aide de l’attribut [ActionName]. Le comportement par défaut est désactivé avec le code suivant dans Startup.ConfigureServices :

services.AddMvc(options =>
    options.SuppressAsyncSuffixInActionNames = false);

Modifications apportées à la génération de liens

Il existe des différences dans la génération de liens (utilisation d’Url.Link et d’API similaires, par exemple). Il s’agit notamment des paramètres suivants :

• Par défaut, lorsque vous utilisez le routage des points de terminaison, la casse des paramètres de routage dans les URI générés n’est pas nécessairement conservée. Ce comportement peut être contrôlé avec l’interface IOutboundParameterTransformer.
• La génération d’un URI pour une route non valide (pour un contrôleur, une action ou une page qui n’existe pas) génère une chaîne vide sous le routage des points de terminaison au lieu de produire un URI non valide.
• Les valeurs ambiantes (paramètres de routage à partir du contexte actuel) ne sont pas automatiquement utilisées pour générer des liens avec routage des points de terminaison. Auparavant, lorsque vous génériez un lien vers une autre action (ou page), les valeurs de routage non spécifiées étaient déduites des valeurs ambiantes des routes actuelles. Avec le routage des points de terminaison, tous les paramètres de routage doivent être explicitement spécifiés lorsque vous générez des liens.

Razor Pages

Le mappage de Razor Pages se déroule désormais dans UseEndpoints.

Ajoutez MapRazorPages si l’application utilise Razor Pages. Étant donné que le routage des points de terminaison inclut la prise en charge de nombreuses infrastructures, l’ajout de Razor Pages est maintenant une option à activer.

Dans la méthode Startup.Configure suivante, MapRazorPages ajoute la prise en charge de Razor Pages :

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

Utiliser MVC sans routage de point de terminaison

L’utilisation de MVC avec UseMvc ou UseMvcWithDefaultRoute dans ASP.NET Core 3.0 exige une activation explicite dans Startup.ConfigureServices. Cela est obligatoire, car MVC doit savoir s’il peut s’appuyer sur l’intergiciel d’autorisation et CORS lors de l’initialisation. Un analyseur fourni avertit si l’application tente d’utiliser une configuration non prise en charge.

Si l’application nécessite une prise en charge IRouter héritée, désactivez EnableEndpointRouting avec l’une des approches suivantes dans Startup.ConfigureServices :

services.AddMvc(options => options.EnableEndpointRouting = false);

services.AddControllers(options => options.EnableEndpointRouting = false);

services.AddControllersWithViews(options => options.EnableEndpointRouting = false);

services.AddRazorPages().AddMvcOptions(options => options.EnableEndpointRouting = false);

Contrôles d'intégrité

Les contrôles d’intégrité peuvent être utilisés comme router-ware avec le routage des points de terminaison.

Ajoutez MapHealthChecks pour utiliser les contrôles d’intégrité avec le routage des points de terminaison. La méthode MapHealthChecks accepte des arguments similaires à UseHealthChecks. Utiliser MapHealthChecks plutôt qu’UseHealthChecks permet d’appliquer l’autorisation et d’avoir un contrôle plus précis sur la stratégie de correspondance.

Dans l’exemple suivant, MapHealthChecks est appelé pour un point de terminaison de contrôle d’intégrité à l’adresse /healthz :

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHealthChecks("/healthz", new HealthCheckOptions() { });
    });
}

HostBuilder remplace WebHostBuilder

Les modèles ASP.NET Core 3.0 utilisent un hôte générique. Les versions précédentes utilisaient un hôte web. Le code suivant représente la classe Program générée par le modèle ASP.NET Core 3.0 :

// requires using Microsoft.AspNetCore.Hosting;
// requires using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Le code suivant représente la classe Program générée par le modèle ASP.NET Core 2.2 :

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

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

IWebHostBuilder reste dans la version 3.0 et correspond au type de webBuilder vu dans l’exemple de code précédent. WebHostBuilder sera déconseillé dans les versions ultérieures et remplacé par HostBuilder.

Le changement le plus significatif de WebHostBuilder à HostBuilder concerne l’injection de dépendances (DI). Lorsque vous utilisez HostBuilder, vous pouvez uniquement injecter les éléments suivants dans le constructeur de Startup :

• IConfiguration
• IHostEnvironment
• IWebHostEnvironment

Les contraintes d’injection de dépendances (DI) de HostBuilder :

• permettent de générer le conteneur de DI une seule fois.
• éliminent les problèmes de durée de vie des objets qui en résultent (comme la résolution de plusieurs instances de singleton).

Pour plus d’informations, consultez l’article Éviter l’injection de services de démarrage dans ASP.NET Core 3 (seulement disponible en anglais).

AddAuthorization déplacé vers un autre assembly

Les méthodes AddAuthorization d’ASP.NET Core 2.2 ou version antérieure dans Microsoft.AspNetCore.Authorization.dll :

• ont été renommées AddAuthorizationCore.
• ont été déplacées vers Microsoft.AspNetCore.Authorization.Policy.dll.

Les applications qui utilisent à la fois Microsoft.AspNetCore.Authorization.dll et Microsoft.AspNetCore.Authorization.Policy.dll ne sont pas affectées.

Les applications qui n’utilisent pas Microsoft.AspNetCore.Authorization.Policy.dll doivent effectuer l’une des opérations suivantes :

• Ajouter une référence à Microsoft.AspNetCore.Authorization.Policy.dll. Cette approche fonctionne pour la plupart des applications et constitue la seule action requise.
• Basculer vers l’utilisation de AddAuthorizationCore

Pour plus d’informations, consultez l’article Un changement cassant dans une surcharge AddAuthorization(o =>) se trouve dans un autre assembly #386 (seulement disponible en anglais).

INTERFACE UTILISATEUR Identity

Identity met à jour l’interface utilisateur pour ASP.NET Core 3.0 :

• Il ajoute une référence de package vers Microsoft.AspNetCore.Identity.UI.
• Les applications qui n’utilisent pas Razor Pages doivent appeler MapRazorPages. Consultez la section Razor Pages du présent document.
• Bootstrap 4 est l’infrastructure d’interface utilisateur par défaut. Définissez une propriété de projet IdentityUIFrameworkVersion pour modifier la valeur par défaut. Pour plus d’informations, consultez cette annonce GitHub (seulement disponible en anglais).

SignalR

Le client JavaScript SignalR est passé de @aspnet/signalr à @microsoft/signalr. Pour réagir à ce changement, modifiez les références dans les fichiers package.json, les instructions require et les instructions import ECMAScript.

System.Text.Json est le protocole par défaut

System.Text.Json est désormais le protocole de hub par défaut utilisé à la fois par le client et le serveur.

Dans Startup.ConfigureServices, appelez AddJsonProtocol pour définir les options de sérialiseur.

Serveur :

services.AddSignalR(...)
        .AddJsonProtocol(options =>
        {
            options.PayloadSerializerOptions.WriteIndented = false;
        })

Client :

new HubConnectionBuilder()
    .WithUrl("/chathub")
    .AddJsonProtocol(options =>
    {
        options.PayloadSerializerOptions.WriteIndented = false;
    })
    .Build();

Basculer vers Newtonsoft.Json

Si vous utilisez des fonctionnalités Newtonsoft.Json qui ne sont pas prises en charge dans System.Text.Json, vous pouvez revenir à Newtonsoft.Json. Consultez la section Utiliser Newtonsoft.Json dans un projet SignalR ASP.NET Core 3.0 plus haut dans cet article.

Caches distribués Redis

Le package Microsoft.Extensions.Caching.Redis n’est pas disponible pour les applications ASP.NET Core 3.0 ou version ultérieure. Remplacez la référence de package par Microsoft.Extensions.Caching.StackExchangeRedis. Pour plus d’informations, consultez Mise en cache distribuée dans ASP.NET Core.

Activer la compilation au runtime

Avant ASP.NET Core 3.0, la compilation des vues au runtime était une fonctionnalité implicite de l’infrastructure. La compilation au runtime complète la compilation des vues à la génération. Elle permet à l’infrastructure de compiler les vues et les pages Razor (fichiers .cshtml) lorsque les fichiers sont modifiés, sans avoir à regénérer l’ensemble de l’application. Cette fonctionnalité prend en charge le scénario de modification rapide dans l’IDE et d’actualisation du navigateur pour afficher les modifications.

Dans ASP.NET Core 3.0, la compilation au runtime est une option d’activation. La compilation à la génération est le seul mécanisme de compilation des vues activé par défaut. Le runtime s’appuie sur Visual Studio ou sur dotnet-watch dans Visual Studio Code pour regénérer le projet lorsqu’il détecte les modifications apportées aux fichiers .cshtml. Dans Visual Studio, les modifications apportées aux fichiers .cs, .cshtml ou .razor dans le projet en cours d’exécution (Ctrl + F5) qui n’ont pas été débogués (F5) déclenchent la recompilation du projet.

Pour activer la compilation au runtime dans le projet ASP.NET Core 3.0 :

1. Installez le package NuGet Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

2. Mettez à jour Startup.ConfigureServices pour appeler AddRazorRuntimeCompilation :

   Pour ASP.NET Core MVC, utilisez le code suivant :

   services.AddControllersWithViews()
       .AddRazorRuntimeCompilation(...);
   

   Pour ASP.NET Core Razor Pages, utilisez le code suivant :

   services.AddRazorPages()
       .AddRazorRuntimeCompilation(...);
   

L’exemple à l’adresse https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation représente l’activation conditionnelle de la compilation au runtime en environnements de développement.

Pour plus d’informations sur la compilation des fichiers Razor, consultez l’article Compilation des fichiers Razor dans ASP.NET Core.

Migrer les bibliothèques avec le multiciblage

Les bibliothèques doivent souvent prendre en charge plusieurs versions d’ASP.NET Core. La plupart des bibliothèques compilées sur les versions précédentes d’ASP.NET Core doivent continuer à fonctionner sans problème. Les conditions suivantes exigent une compilation croisée de l’application :

• La bibliothèque s’appuie sur une fonctionnalité faisant l’objet d’un changement cassant binaire.
• La bibliothèque souhaite tirer parti des nouvelles fonctionnalités d’ASP.NET Core 3.0.

Par exemple :

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>netcoreapp3.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.0'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
    <PackageReference Include="Microsoft.AspNetCore" Version="2.1.0" />
  </ItemGroup>
</Project>

Utilisez #ifdefs pour activer les API spécifiques à ASP.NET Core 3.0 :

var webRootFileProvider =
#if NETCOREAPP3_0
    GetRequiredService<IWebHostEnvironment>().WebRootFileProvider;
#elif NETSTANDARD2_0
    GetRequiredService<IHostingEnvironment>().WebRootFileProvider;
#else
#error unknown target framework
#endif

Pour plus d’informations sur l’utilisation des API ASP.NET Core dans une bibliothèque de classes, consultez l’article Utiliser les API ASP.NET Core dans une bibliothèque de classes.

Modifications diverses

Par défaut, le système de validation de .NET Core 3.0 traite les paramètres non-nullables et les propriétés liées comme s’ils avaient un attribut [Required]. Pour plus d’informations, consultez la section Attribut [Required].

Publier

Supprimez les dossiers bin et obj dans le répertoire du projet.

TestServer

Pour les applications qui utilisent TestServer directement avec un hôte générique, créez le TestServer sur un IWebHostBuilder dans ConfigureWebHost :

[Fact]
public async Task GenericCreateAndStartHost_GetTestServer()
{
    using var host = await new HostBuilder()
        .ConfigureWebHost(webBuilder =>
        {
            webBuilder
                .UseTestServer()
                .Configure(app => { });
        })
    .StartAsync();

    var response = await host.GetTestServer().CreateClient().GetAsync("/");

    Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
}

Changements cassants d’API

Examinez les changements cassants :

• Liste complète des changements cassants apportés à ASP.NET Core 3.0 (seulement disponible en anglais).
• Changements cassants d’API Antiforgery, CORS, Diagnostics, MVC et Routing (seulement disponible en anglais). Cette liste inclut les changements cassants pour les commutateurs de compatibilité.
• Passez en revue les changements cassants entre la version 2.2 et la version 3.0 de .NET Core, d’ASP.NET Core et d’Entity Framework Core. Pour cela, consultez l’article sur les changements cassants de la migration de la version 2.2 à la version 3.0.

Routage des points de terminaison avec un paramètre fourre-tout

public static void Main(string[] args)
{
   AppContext.SetSwitch("Microsoft.AspNetCore.Routing.UseCorrectCatchAllBehavior", 
                         true);
   CreateHostBuilder(args).Build().Run();
}
// Remaining code removed for brevity.

.NET Core 3.0 sur Azure App Service

Le déploiement de .NET Core sur Azure App Service est terminé. .NET Core 3.0 est disponible avec tous les centres de données Azure App Service.

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.