Migrer d’ASP.NET Core 2.2 vers 3.0

  • Article

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 :

  • Comparez avec le code ASP.NET Core 2.2.
  • Copiez les modifications appropriées dans votre projet ASP.NET Core 3.0.

Prérequis

Mettre à jour la version du Kit de développement logiciel (SDK) .NET Core dans global.json

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

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

Mettre à jour le fichier projet

Mettre à jour l’infrastructure cible

ASP.NET Core 3.0 et versions ultérieures s’exécutent uniquement sur .NET Core. Définissez le moniker du 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 de votre fichier projet. Considérez le 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>

Fichier projet ASP.NET Core 3.0 mis à jour :

  • Dans le <PropertyGroup> :

    • Mises à jour le TFM pournetcoreapp3.0
    • Supprime l’élément <AspNetCoreHostingModel> . Pour plus d’informations, consultez Modèle d’hébergement in-process dans ce document.

  • Dans le <ItemGroup> :

    • Microsoft.AspNetCore.App est supprimé. Pour plus d’informations, consultez Informations de référence sur l’infrastructure dans ce document.
    • Microsoft.AspNetCore.Razor.Design est supprimé et dans la liste suivante des packages qui 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 :

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.Cookie s
  • Microsoft.AspNetCore.Authentication.Core
  • Microsoft.AspNetCore.Authentication.OAuth
  • Microsoft.AspNetCore.Authorization.Policy
  • Microsoft.AspNetCore.Cookie Politique
  • 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.Razor Pages
  • Microsoft.AspNetCore.Mvc.TagHelpers
  • Microsoft.AspNetCore.Mvc.ViewFeatures
  • Microsoft.AspNetCore.Razor
  • Microsoft.AspNetCore.Razor. Duree
  • Microsoft.AspNetCore.Razor. Conception
  • 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

Passer en revue les modifications cassants

Passer en revue les modifications cassants

Informations de référence sur l’infrastructure

Les fonctionnalités de ASP.NET Core qui étaient disponibles via l’un des packages répertoriés ci-dessus sont disponibles dans le cadre de l’infrastructure Microsoft.AspNetCore.App partagée. 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 Microsoft.NET.Sdk ou Microsoft.NET.Sdk.Razor le Kit de développement logiciel (SDK) 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épendantes du framework à l’aide de Docker

Les builds dépendantes de l’infrastructure des applications console qui utilisent un package qui dépend du ASP.NET Core framework partagé 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.Appest l’infrastructure partagée contenant le runtime ASP.NET Core et est uniquement présent sur l’image Docker dotnet/core/aspnet. Le Kit de développement logiciel (SDK) 3.0 réduit la taille des builds dépendantes de l’infrastructure à l’aide de ASP.NET Core en n’incluant pas les copies en double des bibliothèques disponibles dans l’infrastructure partagée. Il s’agit d’une économie potentielle de jusqu’à 18 Mo, mais elle nécessite 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 runtimeconfig.json fichier généré lors d’une génération/publication de votre application. Le fichier ON suivant JSmontre 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
    }
  }
}

Si votre application utilise Docker, utilisez une image de base qui inclut 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 Microsoft.AspNetCore.App package. Pour visualiser les assemblys qui ont été supprimés, comparez les deux dossiers d’infrastructure partagés. Par exemple, une comparaison des versions 2.2.7 et 3.0.0 :

comparaison des assemblys d’infrastructure partagée

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 montre les lignes supprimées et modifiées dans une application web pages ASP.NET Core 2.2 Razor :

lignes supprimées et modifiées dans une application web ASP.NET Core 2.2 Razor

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

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

lignes ajoutées et modifiées dans une application web ASP.NET Core 3.0 Razor

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

Prise en charge de l’analyseur

Les projets qui ciblent Microsoft.NET.Sdk.Web implicitement référencent des 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 des analyseurs d’API précédemment fournis à l’aide du package Microsoft.AspNetCore.Mvc.Api.Analyzers , modifiez votre fichier projet pour référencer les analyseurs fournis dans le cadre du Kit de développement logiciel (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

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

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

Modèle d’hébergement in-process

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

Kestrel

Configuration

Migrer Kestrel la configuration 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ôte 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 Adaptateurs de connexion par l’intergiciel de connexion. Le middleware de connexion est similaire à l’intergiciel HTTP dans le pipeline ASP.NET Core, mais pour les connexions de niveau inférieur. HTTPS et 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 versions précédentes de ASP.NET Core.

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

Abstractions de transport déplacé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 à l’option 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 bande-annonce de demande

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

  • Kestrel ajoute des en-têtes de bande-annonce segmentés HTTP/1.1 dans la collection d’en-têtes de requête.
  • Les bandes-annonces sont disponibles une fois que le corps de la demande est lu à la fin.

Cela soulève certaines préoccupations concernant l’ambiguïté entre les en-têtes et les bandes-annonces, de sorte que les bandes-annonces ont été déplacées vers une nouvelle collection (RequestTrailerExtensions) dans la version 3.0.

Les bandes-annonces 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 demande sont présentes pour accéder à ces bandes-annonces. Comme avec HTTP/1.1, les bandes-annonces sont disponibles une fois que le corps de la demande est lu jusqu’à la fin.

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

  • GetDeclaredTrailers: obtient l’en-tête de requête Trailer qui répertorie les bandes-annonces à attendre après le corps.
  • SupportsTrailers: indique si la demande prend en charge la réception d’en-têtes de bande-annonce.
  • CheckTrailersAvailable: vérifie si la demande prend en charge les bandes-annonces et si elles sont disponibles pour être lues. Cette case activée ne suppose pas qu’il existe des bandes-annonces à lire. Il se peut qu’il n’y ait pas de bandes-annonces à lire même si true est retourné par cette méthode.
  • GetTrailer: obtient l’en-tête de fin demandé à partir de la réponse. Vérifiez SupportsTrailers avant d’appeler GetTrailer, ou un NotSupportedException peut se produire si la demande ne prend pas en charge les en-têtes de fin.

Pour plus d’informations, consultez Placer des bandes-annonces de demande dans une collection distincte (dotnet/AspNetCore #10410).

AllowSynchronousIO désactivé

AllowSynchronousIO active ou désactive les API d’E/S synchrones, telles que HttpRequest.Body.Read, HttpResponse.Body.Writeet Stream.Flush. Ces API sont une source de famine de 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 l’articleKestrel.

Si des E/S synchrones sont nécessaires, elles peuvent être activées en configurant l’option sur le AllowSynchronousIO serveur utilisé (lors de l’appel ConfigureKestrelde , par exemple, si vous utilisez Kestrel). Notez que les serveurs (Kestrel, HttpSys, TestServer, etc.) ont tous leur propre AllowSynchronousIO option qui n’affectera pas les autres serveurs. Les E/S synchrones peuvent être activées pour tous les serveurs sur une base par demande à l’aide de l’option IHttpBodyControlFeature.AllowSynchronousIO :

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

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

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

Pour plus d’informations, consultez [Annonce] AllowSynchronousIO désactivé dans tous les serveurs (dotnet/AspNetCore #7644).

Mise en mémoire tampon du formateur de sortie

Newtonsoft.Json, XmlSerializeret les DataContractSerializer formateurs de sortie basés prennent uniquement en charge la sérialisation synchrone. Pour permettre à ces formateurs d’utiliser les restrictions AllowSynchronousIO du serveur, MVC met en mémoire tampon la sortie de ces formateurs avant d’écrire sur le disque. À la suite de la mise en mémoire tampon, MVC inclut l’en-tête Content-Length lors de la réponse à l’aide de ces formateurs.

System.Text.Json prend en charge la sérialisation asynchrone et, par conséquent, le System.Text.Json formateur basé ne met pas 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 si AllowSynchronousIO n’est pas également configuré.

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

Dans ASP.NET Core 2.1, le contenu de Microsoft.AspNetCore.Server.Kestrel Https.dll ont été déplacés vers Microsoft.AspNetCore.Server.Kestrel. Core.dll. Il s’agissait d’une mise à jour sans rupture utilisant TypeForwardedTo des attributs. Pour la version 3.0, le Microsoft.AspNetCore.ServerKestrel vide. Https.dll assembly et le package NuGet ont été supprimés.

Bibliothèques référençant Microsoft.AspNetCore.Server.Kestrel. Https doit mettre à jour ASP.NET Core dépendances vers la version 2.1 ou ultérieure.

Les applications et bibliothèques ciblant ASP.NET Core 2.1 ou version ultérieure doivent supprimer toutes les références directes à Microsoft.AspNetCore.ServerKestrel. Package 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 ON par défaut JSpour ASP.NET Core est maintenant System.Text.Json, ce qui est nouveau dans .NET Core 3.0. Envisagez d’utiliser System.Text.Json lorsque cela est possible. Il est hautement performant et ne nécessite pas de dépendance de bibliothèque supplémentaire. Toutefois, étant donné System.Text.Json qu’il s’agit de fonctionnalités nouvelles, il se peut que votre application ait besoin de fonctionnalités manquantes. Pour plus d’informations, consultez Comment migrer de Newtonsoft.Json vers System.Text.Json.

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

  • Installez Microsoft.AspNetCore.SignalR. Package NuGet Protocols.NewtonsoftJson .

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

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

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

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

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

  • 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’inscription du service MVC :

    • AddRazorPages
    • AddControllersWithViews
    • AddControllers
    services.AddControllers()
    .AddNewtonsoftJson();

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

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

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

Pour plus d’informations, consultez Ajouter la prise en charge du format ON basé JSsur Newtonsoft.Json.

Inscription du service MVC

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

Trois nouvelles méthodes d’extension de niveau supérieur liées aux scénarios MVC sur IServiceCollection sont disponibles. Les modèles utilisent ces nouvelles méthodes au lieu de 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 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 et des vues liées à l’API, mais pas pour les 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 du point 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 d’utilisation du routage de point de terminaison dans la version 2.2, attendez-vous à 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 comme remplacement.
  • Si l’application accède RouteData.Routers directement à L’intérieur de MVC pour analyser les URL, vous pouvez le remplacer par l’utilisation de LinkParser.ParsePathByEndpointName.
    • Définissez l’itinéraire avec un nom d’itinéraire.
    • Utilisez LinkParser.ParsePathByEndpointName et transmettez le nom de l’itinéraire souhaité.

Le routage de point de terminaison prend en charge la même syntaxe de modèle d’itinéraire et les mêmes fonctionnalités de création de modèle d’itinéraire que IRouter. Le routage de point de terminaison prend en charge IRouteConstraint. Le routage de point de terminaison prend en charge [Route], [HttpGet]et les autres attributs de routage MVC.

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

Migrer Startup.Configure

Conseils généraux :

  • Ajoutez UseRouting.

  • Si l’application appelle UseStaticFiles, placezUseStaticFiles avantUseRouting.

  • Si l’application utilise des fonctionnalités d’authentification/autorisation telles que AuthorizePage ou [Authorize], placez l’appel à UseAuthentication et UseAuthorization: après et UseRoutingUseCors, mais avant UseEndpoints:

    public void Configure(IApplicationBuilder app)
{
  ...

  app.UseStaticFiles();

  app.UseRouting();
  app.UseCors();

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

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

  • Remplacez ou UseSignalR par UseMvcUseEndpoints.

  • Si l’application utilise des scénarios CORS , tels que [EnableCors], placez l’appel à UseCors avant tout autre intergiciel qui utilise CORS (par exemple, place UseCors avant UseAuthentication, UseAuthorizationet UseEndpoints).

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

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

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

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 précédent Startup.Configure :

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 la plupart des applications, les appels à UseAuthentication, UseAuthorizationet UseCors doivent apparaître entre les appels à UseRouting et UseEndpoints pour être efficaces.

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 middleware . Cela permet d’utiliser les mêmes intergiciels et 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. Le middleware était fourni pour être utilisé dans certains cas d’usage, mais les filtres MVC étaient destinés à être utilisés sans l’intergiciel dans d’autres cas d’usage. Avec ASP.NET Core 3.0, nous recommandons que toutes les applications qui nécessitent CORS utilisent le middleware CORS en tandem avec le routage des points de terminaison. UseCors peut être fourni avec une stratégie par défaut, et [EnableCors] les attributs peuvent [DisableCors] être utilisés pour remplacer la stratégie par défaut si nécessaire.

Dans l’exemple suivant :

  • CORS est activé pour tous les points de terminaison avec la default stratégie nommée.
  • La MyController classe 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 de ASP.NET Core, la prise en charge de l’autorisation était fournie via 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. L’intergiciel d’autorisation peut également être configuré avec une stratégie par défaut, qui peut être remplacée.

Dans ASP.NET Core version 3.0 ou ultérieure, UseAuthorization est appelé dans Startup.Configure, et les éléments suivants HomeController nécessitent 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()
    {
        ...
    }
}

Lors de l’utilisation du routage de point de terminaison, nous vous déconseillons de configurer AuthorizeFilter et de s’appuyer plutôt sur l’intergiciel d’autorisation. Si l’application utilise un AuthorizeFilter comme filtre global dans MVC, nous vous recommandons de refactoriser le code pour fournir une stratégie dans l’appel à AddAuthorization.

Le DefaultPolicy est initialement configuré pour exiger une authentification. Aucune configuration supplémentaire n’est donc requise. Dans l’exemple suivant, les points de terminaison MVC sont marqués comme RequireAuthorization de sorte que toutes les demandes doivent être autorisées en fonction du DefaultPolicy. Toutefois, le autorise l’accès HomeController 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 des 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 application avec une stratégie spécifique nécessitant 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. est DefaultPolicy configuré 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 un FallbackPolicy. le FallbackPolicy est différent de .DefaultPolicy est DefaultPolicy déclenché par [Authorize] ou RequireAuthorization, tandis que le FallbackPolicy est déclenché lorsqu’aucune autre stratégie n’est définie. FallbackPolicy est initialement configuré pour autoriser les demandes sans autorisation.

L’exemple suivant est identique à l’exemple précédent DefaultPolicy , mais utilise pour toujours exiger l’authentification FallbackPolicy 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, mais les contrôles d’intégrité peuvent avoir une stratégie d’autorisation configurable appliquée par l’intergiciel (middleware).

En outre, chaque point de terminaison peut personnaliser ses exigences d’autorisation. Dans l’exemple suivant, UseAuthorization traite l’autorisation avec , DefaultPolicymais le /healthz point de terminaison de case activée d’intégrité nécessite un admin utilisateur :

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 mauvaise 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 passe 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 (le 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 routage de point de terminaison).

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

SignalR

Le mappage des SignalR hubs a désormais lieu à l’intérieur de UseEndpoints.

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

Dans l’exemple suivant, la prise en charge du ChatHubSignalR hub est ajoutée :

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

Il existe une nouvelle option pour contrô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 pouvez définir et TransportMaxBufferSize qui contrôlerait 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 pression arrière.

SignalR assemblys dans l’infrastructure partagée

SignalR ASP.NET Core assemblys côté serveur sont maintenant installés avec le Kit de développement logiciel (SDK) .NET Core. Pour plus d’informations, consultez Supprimer les références de package obsolètes dans ce document.

Contrôleurs MVC

Le mappage des contrôleurs a désormais lieu à l’intérieur de UseEndpoints.

Ajoutez MapControllers si l’application utilise le routage d’attributs. Étant donné que le routage prend 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 d’adhésion.

Remplacez le code suivant :

  • MapRoute avec MapControllerRoute
  • MapAreaRoute avec MapAreaControllerRoute

Étant donné que le routage prend désormais en charge plus que MVC, la terminologie a changé pour que ces méthodes indiquent clairement ce qu’elles font. Les routes conventionnelles telles que MapControllerRoute//MapAreaControllerRouteMapDefaultControllerRoute sont appliquées dans l’ordre dans lequel elles sont ajoutées. Placez d’abord des itinéraires plus spécifiques (par exemple, des itinéraires pour une zone).

Dans l’exemple suivant :

  • MapControllers ajoute la prise en charge des contrôleurs routés par attributs.
  • MapAreaControllerRoute ajoute un itinéraire conventionnel pour les contrôleurs dans 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 de suffixes asynchrones des noms d’actions de contrôleur

Dans ASP.NET Core 3.0, ASP.NET Core MVC supprime le Async suffixe des noms d’actions de contrôleur. Le routage et la génération de liens sont impactés par cette nouvelle valeur par défaut. 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 est accessible sur l’itinéraire Products/ListAsync .

  • Génération de lien requise en spécifiant le Async suffixe. Par exemple :

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

Dans ASP.NET Core 3.0 :

  • L’action précédente est accessible sur l’itinéraire Products/List .

  • La génération de liens ne nécessite pas de spécifier le Async suffixe. 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 peut être 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 (à l’aide Url.Link d’API similaires, par exemple). Il s’agit notamment des paramètres suivants :

  • Par défaut, lors de l’utilisation du routage de point de terminaison, la casse des paramètres de route 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 un itinéraire non valide (un contrôleur/une action ou une page qui n’existe pas) génère une chaîne vide sous le routage du point de terminaison au lieu de produire un URI non valide.
  • Les valeurs ambiantes (paramètres de routage du contexte actuel) ne sont pas utilisées automatiquement dans la génération de liens avec le routage de point de terminaison. Auparavant, lors de la génération d’un lien vers une autre action (ou page), les valeurs de route non spécifiées étaient déduites des valeurs ambiantes des routes actuelles . Lors de l’utilisation du routage de point de terminaison, tous les paramètres d’itinéraire doivent être spécifiés explicitement lors de la génération de liens.

Razor Pages

Les pages de mappage Razor ont désormais lieu à l’intérieur de UseEndpoints.

Ajoutez MapRazorPages si l’application utilise Razor Pages. Étant donné que le routage de point de terminaison prend en charge de nombreux frameworks, l’ajout Razor de Pages est désormais une option d’adhésion.

Dans la méthode suivante Startup.Configure , 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 via UseMvc ou UseMvcWithDefaultRoute dans ASP.NET Core 3.0 nécessite un consentement explicite à l’intérieur de Startup.ConfigureServices. Cela est obligatoire, car MVC doit savoir s’il peut s’appuyer sur l’autorisation et le middleware CORS pendant l’initialisation. Un analyseur est fourni pour avertir si l’application tente d’utiliser une configuration non prise en charge.

Si l’application nécessite une prise en charge héritée IRouter , désactivez EnableEndpointRouting 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 routeur-ware avec le routage de point de terminaison.

Ajoutez MapHealthChecks pour utiliser les contrôles d’intégrité avec le routage de point de terminaison. La MapHealthChecks méthode accepte des arguments similaires à UseHealthChecks. L’avantage de l’utilisation MapHealthChecks de sur UseHealthChecks est la possibilité d’appliquer une 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 case activée 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 l’hôte générique. Les versions précédentes utilisaient l’hôte web. Le code suivant montre la classe générée Program 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 montre la classe générée par Program 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 est le type du webBuilder vu dans l’exemple de code précédent. WebHostBuilder sera déconseillé dans une version ultérieure 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 Startuple constructeur de :

Les contraintes d’di HostBuilder :

  • Activez le conteneur d’idi à générer 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 Éviter l’injection de service de démarrage dans ASP.NET Core 3.

AddAuthorization déplacé vers un autre assembly

Les méthodes ASP.NET Core 2.2 et inférieures AddAuthorization dans Microsoft.AspNetCore.Authorization.dll:

  • Ont été renommés AddAuthorizationCore.
  • Ont été déplacés vers Microsoft.AspNetCore.Authorization.Policy.dll.

Les applications qui utilisent à la foisMicrosoft.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 :

  • Ajoutez une référence à Microsoft.AspNetCore.Authorization.Policy.dll. Cette approche fonctionne pour la plupart des applications et est tout ce qui est nécessaire.
  • Basculer vers l’utilisation AddAuthorizationCore

Pour plus d’informations, consultez Changement cassant dans AddAuthorization(o =>) la surcharge vit dans un assembly différent #386.

Interface utilisateur du service Identity

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

  • Ajoutez une référence de package à Microsoft.AspNetCore.Identity Interface utilisateur.
  • Les applications qui n’utilisent Razor pas Pages doivent appeler MapRazorPages. Voir Razor Pages dans ce document.
  • Bootstrap 4 est l’infrastructure d’interface utilisateur par défaut. Définissez une IdentityUIFrameworkVersion propriété de projet pour modifier la valeur par défaut. Pour plus d’informations, consultez cette annonce GitHub.

SignalR

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

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

System.Text.Json est désormais le protocole Hub par défaut utilisé 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 de Newtonsoft.Json qui ne sont pas prises en charge dans System.Text.Json, vous pouvez revenir à Newtonsoft.Json. Consultez Utiliser Newtonsoft.Json dans un projet ASP.NET Core 3.0 SignalR plus haut dans cet article.

Caches distribués Redis

Le package Microsoft.Extensions.Caching.Redis n’est pas disponible pour ASP.NET Core applications 3.0 ou ultérieures. 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.

Accepter la compilation du runtime

Avant ASP.NET Core 3.0, la compilation au runtime des vues était une fonctionnalité implicite de l’infrastructure. La compilation du runtime complète la compilation au moment de la génération des vues. Il permet à l’infrastructure de compiler Razor des vues et des pages (.cshtml fichiers) lorsque les fichiers sont modifiés, sans avoir à reconstruire 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 du runtime est un scénario d’adhésion. La compilation au moment de la build est le seul mécanisme de compilation d’affichage activé par défaut. Le runtime s’appuie sur Visual Studio ou dotnet-watch dans Visual Studio Code pour reconstruire le projet lorsqu’il détecte les modifications apportées aux .cshtml fichiers. Dans Visual Studio, les modifications apportées aux .csfichiers , .cshtmlou .razor dans le projet en cours d’exécution (Ctrl+F5), mais non débogués (F5), déclenchent la recompilation du projet.

Pour activer la compilation du runtime dans votre projet ASP.NET Core 3.0 :

  1. Installez Microsoft.AspNetCore.Mvc.Razor. Package NuGet RuntimeCompilation .

  2. Mettre à 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 sur https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation montre un exemple d’activation conditionnelle de la compilation du runtime dans les environnements de développement.

Pour plus d’informations sur Razor la compilation de fichiers, consultez Razor compilation de fichiers dans ASP.NET Core.

Migrer des bibliothèques via le multi-ciblage

Les bibliothèques doivent souvent prendre en charge plusieurs versions de ASP.NET Core. La plupart des bibliothèques compilées par rapport aux versions précédentes de ASP.NET Core doivent continuer à fonctionner sans problème. Les conditions suivantes nécessitent la compilation croisée de l’application :

  • La bibliothèque s’appuie sur une fonctionnalité qui a un changement binaire cassant.
  • La bibliothèque souhaite tirer parti des nouvelles fonctionnalités de 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 ASP.NET Core API spécifiques à la version 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 Utiliser ASP.NET Core API dans une bibliothèque de classes.

Modifications diverses

Le système de validation dans .NET Core 3.0 et versions ultérieures 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 Attribut [Obligatoire].

Publier

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

TestServer

Pour les applications qui utilisent TestServer directement avec l’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 d’API cassants

Passez en revue les changements cassants :

Routage de point de terminaison avec le paramètre catch-all

Avertissement

Un paramètre catch-all peut faire correspondre les mauvais routages en raison d’un bogue dans le routage. Les applications affectées par ce bogue présentent les caractéristiques suivantes :

  • Un routage catch-all, par exemple, {**slug}"
  • Le routage catch-all ne fait pas correspondre les demandes qu’il doit faire correspondre.
  • La suppression d’autres routes fait que la route catch-all commence à 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 et versions ultérieures. 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 dans 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 a été installée sur le système, téléchargez le dernier programme d’installation de l’offre groupée d’hébergement .NET Core (téléchargement direct) et exécutez le programme d’installation. Pour plus d’informations, consultez Bundle d’hébergement.