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 le framework cible

ASP.NET Core 3.0 ou ultérieur s’exécute uniquement sur .NET Core. Définissez le Target Framework Moniker (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 fabriqués, sélectionnez la liste déroulante suivante :

Cliquez pour développer la liste des packages qui ne sont plus produits
  • Microsoft.AspNetCore
  • Microsoft.AspNetCore.All
  • Microsoft.AspNetCore.App
  • Microsoft.AspNetCore.Antiforgery
  • Microsoft.AspNetCore.Authentication
  • Microsoft.AspNetCore.Authentication.Abstractions
  • Microsoft.AspNetCore.Authentication.Cookies
  • Microsoft.AspNetCore.Authentication.Core
  • Microsoft.AspNetCore.Authentication.OAuth
  • Microsoft.AspNetCore.Authorization.Policy
  • Microsoft.AspNetCore.CookiePolicy
  • Microsoft.AspNetCore.Cors
  • Microsoft.AspNetCore.Diagnostics
  • Microsoft.AspNetCore.Diagnostics.HealthChecks
  • Microsoft.AspNetCore.HostFiltering
  • Microsoft.AspNetCore.Hosting
  • Microsoft.AspNetCore.Hosting.Abstractions
  • Microsoft.AspNetCore.Hosting.Server.Abstractions
  • Microsoft.AspNetCore.Http
  • Microsoft.AspNetCore.Http.Abstractions
  • Microsoft.AspNetCore.Http.Connections
  • Microsoft.AspNetCore.Http.Extensions
  • Microsoft.AspNetCore.HttpOverrides
  • Microsoft.AspNetCore.HttpsPolicy
  • Microsoft.AspNetCore.Identity
  • Microsoft.AspNetCore.Localization
  • Microsoft.AspNetCore.Localization.Routing
  • Microsoft.AspNetCore.Mvc
  • Microsoft.AspNetCore.Mvc.Abstractions
  • Microsoft.AspNetCore.Mvc.Analyzers
  • Microsoft.AspNetCore.Mvc.ApiExplorer
  • Microsoft.AspNetCore.Mvc.Api.Analyzers
  • Microsoft.AspNetCore.Mvc.Core
  • Microsoft.AspNetCore.Mvc.Cors
  • Microsoft.AspNetCore.Mvc.DataAnnotations
  • Microsoft.AspNetCore.Mvc.Formatters.Json
  • Microsoft.AspNetCore.Mvc.Formatters.Xml
  • Microsoft.AspNetCore.Mvc.Localization
  • Microsoft.AspNetCore.Mvc.Razor
  • Microsoft.AspNetCore.Mvc.Razor.ViewCompilation
  • Microsoft.AspNetCore.Mvc.RazorPages
  • Microsoft.AspNetCore.Mvc.TagHelpers
  • Microsoft.AspNetCore.Mvc.ViewFeatures
  • Microsoft.AspNetCore.Razor
  • Microsoft.AspNetCore.Razor.Runtime
  • Microsoft.AspNetCore.Razor.Design
  • Microsoft.AspNetCore.ResponseCaching
  • Microsoft.AspNetCore.ResponseCaching.Abstractions
  • Microsoft.AspNetCore.ResponseCompression
  • Microsoft.AspNetCore.Rewrite
  • Microsoft.AspNetCore.Routing
  • Microsoft.AspNetCore.Routing.Abstractions
  • Microsoft.AspNetCore.Server.HttpSys
  • Microsoft.AspNetCore.Server.IIS
  • Microsoft.AspNetCore.Server.IISIntegration
  • Microsoft.AspNetCore.Server.Kestrel
  • Microsoft.AspNetCore.Server.Kestrel.Core
  • Microsoft.AspNetCore.Server.Kestrel. Https
  • Microsoft.AspNetCore.Server.Kestrel. Transport.Abstractions
  • Microsoft.AspNetCore.Server.Kestrel. Transport.Sockets
  • Microsoft.AspNetCore.Session
  • Microsoft.AspNetCore.SignalR
  • Microsoft.AspNetCore.SignalR.Core
  • Microsoft.AspNetCore.StaticFiles
  • Microsoft.AspNetCore.WebSockets
  • Microsoft.AspNetCore.WebUtilities
  • Microsoft.Net.Http.Headers

Examiner les changements majeurs

Examiner les changements cassants

Référence du framework

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 :

Comparaison des assemblys du framework partagé

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

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 :

Lignes supprimées et modifiées dans une application web Razor 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 :

Lignes ajoutées et modifiées dans une application web Razor 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 :

Prise en charge des analyseurs

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>

Razor bibliothèque de classes

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 dans le processus

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

Paramétrage

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

L’intergiciel de connexion remplace les adaptateurs 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 pour les 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’article Kestrel.

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 :

Kestrel En-têtes de fin de requête

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 en-têtes de fin sont disponibles après que le corps de la requête a été lu jusqu’à la fin.

Cela soulève des préoccupations quant à l’ambiguïté entre les en-têtes et les sections de fin ; les sections de fin ont donc été déplacées vers une nouvelle collection (RequestTrailerExtensions) en 3.0.

Les champs d'en-tête de fin de requête HTTP/2 sont :

  • 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 la requête sont disponibles pour accéder à ces en-têtes de fin. Comme avec HTTP/1.1, les en-têtes de fin sont disponibles une fois la lecture du corps de la requête terminée.

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

  • GetDeclaredTrailers : obtient l’en-tête de requête Trailer qui répertorie les en-têtes de fin attendus après le corps.
  • SupportsTrailers : indique si la requête prend en charge la réception des en-têtes de fin.
  • CheckTrailersAvailable : vérifie si la requête prend en charge les en-têtes de fin et s’ils peuvent être lus. Cette vérification ne suppose pas qu’il existe des amorces de fin à lire. Il se peut qu’il n’y ait aucun en-tête de fin à lire, même si true est renvoyé par cette méthode.
  • GetTrailer : récupère l’en-tête de fin demandé de la réponse. Vérifiez SupportsTrailers avant d’appeler GetTrailer, sinon un NotSupportedException risque de se produire si la requête ne prend pas en charge les en-têtes de fin de message.

Pour plus d’informations, consultez Placer les en-têtes de fin de requête dans une collection distincte (dotnet/AspNetCore #10410).

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 saturation des threads, entraînant des plantages 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. En raison de la mise en mémoire tampon, MVC inclura l’en-tête Content-Length dans les réponses utilisant ces composants de formatage.

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. Pensez à utiliser cet outil de mise en forme 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 amener l’application à lever une exception d’exécution si AllowSynchronousIO n’est pas également configuré.

Assembly Microsoft.AspNetCore.Server.Kestrel.Https supprimé(e)

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’agissait d’une mise à jour rétrocompatible reposant sur des attributs TypeForwardedTo. Dans la version 3.0, l’assembly vide 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 nouvelles méthodes d’enregistrement des services 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 des pages Razor et une prise en charge minimale des contrôleurs. 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 d'initialisation du 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 de point de terminaison dans la version 2.2, vous devriez constater des améliorations dans ASP.NET Core 3.0, à l’exception des points suivants :

  • 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 UseStaticFilesavantUseRouting.

  • 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?}");
    });
}

Avertissement

Pour être efficaces avec la plupart des applications, les appels à UseAuthentication, UseAuthorizationet UseCors doivent apparaître entre les appels à UseRouting et UseEndpoints.

Vérifications d’état

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 des vérifications d’état peuvent :

  • Spécifier un ou plusieurs hôtes/ports autorisés.
  • Exiger une autorisation.
  • Exiger le protocole 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. Un intergiciel d’autorisation mis à jour est fourni dans cette version, et le middleware CORS est amélioré afin qu’il puisse 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 vous recommandons que toutes les applications qui nécessitent 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 le middleware d’autorisation ASP.NET Core (UseAuthorization) immédiatement après UseAuthentication. L’intergiciel 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. Le middleware des points de terminaison génère une exception si une stratégie d’autorisation ou CORS est ignorée en raison de l’absence du middleware correspondant. La prise en charge par l’analyseur de la fourniture d’informations supplémentaires en cas d’erreur de configuration 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 ChatHubSignalR 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.

SignalR assemblys dans le framework partagé

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 est accessible à l’URL 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);

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 prend en charge de nombreux frameworks, l’ajout de Razor Pages doit désormais être activé explicitement.

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 nécessaire, car MVC doit savoir s’il peut s’appuyer sur l’autorisation et l’intergiciel CORS pendant l’initialisation. Un analyseur fourni avertit si l’application tente d’utiliser une configuration non prise en charge.

Si l’application nécessite une compatibilité héritée avec IRouter, désactivez EnableEndpointRouting en utilisant 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);

Vérifications de l’état

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 vérifications d’intégrité avec le routage des points de terminaison. La méthode MapHealthChecks accepte des arguments similaires à UseHealthChecks. L’avantage d’utiliser MapHealthChecks plutôt que UseHealthChecks est de pouvoir appliquer des autorisations et bénéficier d’un contrôle plus fin sur la stratégie de correspondance.

Dans l’exemple suivant, MapHealthChecks est utilisé pour un point de terminaison de vérification de l’état à 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 :

Les contraintes HostBuilder DI :

  • Permettre au conteneur DI de n’être créé qu’une seule fois.
  • Évite les problèmes de durée de vie des objets qui en résultent, comme la résolution de plusieurs instances de singletons.

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 a été déplacé vers un autre assembly

Les méthodes AddAuthorization d’ASP.NET Core 2.2 et versions antérieures 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 Modification avec rupture de compatibilité : la surcharge AddAuthorization(o =>) se trouve dans un autre assembly #386.

Identity interface utilisateur

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

  • Ajoutez une référence au package 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(...);

Le modèle à https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation présente un exemple d'activation conditionnelle de la compilation à l'exécution dans les environnements Development.

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

Le système de validation dans .NET Core 3.0 ou version ultérieure traite les paramètres non nullables ou les propriétés liées comme s’ils avaient un [Required] attribut. 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);
}

Modifications majeures

Utilisez les articles de Changements avec rupture dans .NET pour trouver les changements avec rupture susceptibles de s’appliquer lors de la mise à niveau d’une application vers une version plus récente de .NET.

Pour plus d’informations, consultez les ressources suivantes :

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

Avertissement

Un paramètre fourre-tout peut faire correspondre des routes de manière incorrecte en raison d’un bogue dans le routage. Les applications affectées par ce bogue présentent les caractéristiques suivantes :

  • Une route générique, par exemple, {**slug}"
  • La route fourre-tout ne correspond pas aux requêtes auxquelles elle devrait correspondre.
  • La suppression des autres routes permet à la route fourre-tout de se mettre à fonctionner.

Consultez les bogues GitHub 18677 et 16579, par exemple les cas qui ont rencontré ce bogue.

Un correctif d’opt-in pour ce bogue est contenu dans le Kit de développement logiciel (SDK) .NET Core 3.1.301 ou ultérieur. Le code suivant définit un commutateur interne qui corrige ce bogue :

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.

  • Last updated on