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.
- Visual Studio 2019 avec la charge de travail ASP.NET et développement web
- .NET Core 3.0 SDK
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"
}
}
ASP.NET Core 3.0 ou version ultérieure s’exécute uniquement sur .NET Core. Configurez le moniker de framework cible (TFM) sur netcoreapp3.0
:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp3.0</TargetFramework>
</PropertyGroup>
</Project>
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.
- Met à jour le TFM vers
Dans le
<ItemGroup>
:Microsoft.AspNetCore.App
est supprimé. Pour plus d’informations, consultez la section Références d’infrastructure du présent document.Microsoft.AspNetCore.Razor.Design
est supprimé et, dans la liste suivante, les packages ne sont plus produits.
Pour afficher la liste complète des packages qui ne sont plus produits, sélectionnez la liste de développement suivante :
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 cassants
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’infrastructureMicrosoft.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
ouMicrosoft.NET.Sdk.Razor
doivent ajouter un expliciteFrameworkReference
àMicrosoft.AspNetCore.App
:<Project Sdk="Microsoft.NET.Sdk.Razor"> <PropertyGroup> <TargetFramework>netcoreapp3.0</TargetFramework> </PropertyGroup> <ItemGroup> <FrameworkReference Include="Microsoft.AspNetCore.App" /> </ItemGroup> ... </Project>
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
ASP.NET Core 3.0 supprime certains assemblys qui faisaient précédemment partie de la référence du package Microsoft.AspNetCore.App
. Pour visualiser les assemblys qui ont été supprimés, comparez les deux dossiers de l’infrastructure partagée. Par exemple, pour une comparaison des versions 2.2.7 et 3.0.0 :
Pour continuer à utiliser les fonctionnalités fournies par les assemblys supprimés, référencez les versions 3.0 des packages correspondants :
Une application web générée par un modèle avec des comptes d’utilisateur individuels exige d’ajouter les packages suivants :
<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp3.0</TargetFramework> <UserSecretsId>My-secret</UserSecretsId> </PropertyGroup> <ItemGroup> <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="3.0.0" /> <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="3.0.0" /> <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="3.0.0" /> <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="3.0.0" /> <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="3.0.0" /> </ItemGroup> </Project>
-
Pour plus d’informations sur le référencement du package spécifique au fournisseur de base de données, consultez l’article Fournisseurs de base de données.
INTERFACE UTILISATEUR Identity
La prise en charge de l’interface utilisateur Identity peut être ajoutée en référençant le package d’interface utilisateur Microsoft.AspNetCoreIdentity.
Services SPA
Authentification : la prise en charge des flux d’authentification tiers est assurée sous forme de packages NuGet :
- Facebook OAuth (Microsoft.AspNetCore.Authentication.Facebook)
- Google OAuth (Microsoft.AspNetCore.Authentication.Google)
- Authentification de compte Microsoft (Microsoft.AspNetCore.Authentication.MicrosoftAccount)
- Authentification OpenID Connect (Microsoft.AspNetCore.Authentication.OpenIdConnect)
- Jeton du porteur OpenID Connect (Microsoft.AspNetCore.Authentication.JwtBearer)
- Twitter OAuth (Microsoft.AspNetCore.Authentication.Twitter)
- Authentification WsFederation (Microsoft.AspNetCore.Authentication.WsFederation)
Prise en charge de la mise en forme et de la négociation de contenu pour
System.Net.HttpClient
: le package NuGet Microsoft.AspNet.WebApi.Client fournit une extensibilité utile àSystem.Net.HttpClient
avec des API commeReadAsAsync
etPostJsonAsync
. Toutefois, ce package dépend deNewtonsoft.Json
, et non deSystem.Text.Json
. Par exemple, cela signifie que les noms de la propriété de sérialisation spécifiés parJsonPropertyNameAttribute
(System.Text.Json
) sont ignorés. Il existe un package NuGet plus récent qui contient des méthodes d’extension similaires, mais utiliseSystem.Text.Json
: System.Net.Http.Json.RazorCompilation au runtime : la prise en charge de la compilation au runtime des vues et des pages Razor fait désormais partie de Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.
Prise en charge de MVC
Newtonsoft.Json
(Json.NET) : la prise en charge de l’utilisation de MVC avecNewtonsoft.Json
fait désormais partie deMicrosoft.AspNetCore.Mvc.NewtonsoftJson
.
L’image suivante représente les lignes supprimées et modifiées dans une application web Razor Pages ASP.NET Core 2.2 :
Dans l’image précédente, le code supprimé est affiché en rouge. Le code supprimé n’affiche pas le code d’options cookie, qui a été supprimé avant de comparer les fichiers.
L’image suivante représente les lignes ajoutées et modifiées dans une application web Razor Pages ASP.NET Core 3.0 :
Dans l’image précédente, le code ajouté est affiché en vert. Pour plus d’informations sur les modifications suivantes :
services.AddMvc
enservices.AddRazorPages
: consultez la section Inscription du service MVC du présent document.CompatibilityVersion
: consultez l’article Version de compatibilité pour ASP.NET Core MVC.IHostingEnvironment
enIWebHostEnvironment
: consultez cette annonce GitHub (seulement disponible en anglais).app.UseAuthorization
a été ajouté aux modèles pour démontrer que l’intergiciel d’autorisation de commande devait être ajouté. Si l’application n’utilise pas l’autorisation, vous pouvez supprimer l’appel àapp.UseAuthorization
en toute sécurité.app.UseEndpoints
: consultez Razor Pages ou la section Migrer Startup.Configure du présent document.
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>
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>
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
.
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();
}
Les adaptateurs de connexion (Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter
) ont été supprimés de Kestrel. Remplacez les adaptateurs de connexion par l’intergiciel de connexion. L’intergiciel de connexion est similaire à l’intergiciel HTTP dans le pipeline ASP.NET Core, mais correspond aux connexions de niveau inférieur. HTTPS et la journalisation des connexions :
- ont été déplacés des adaptateurs de connexion vers l’intergiciel de connexion.
- Ces méthodes d’extension fonctionnent comme dans les précédentes versions d’ASP.NET Core.
Pour plus d’informations, consultez l’exemple TlsFilterConnectionHandler dans la section ListenOptions.Protocols de l’Kestrelarticle sur .
La couche de transport Kestrel a été exposée en tant qu’interface publique dans Connections.Abstractions
. Dans le cadre de ces mises à jour :
Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions
et les types associés ont été supprimés.- NoDelay a été déplacé de ListenOptions vers les options de transport.
Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode
a été supprimé de KestrelServerOptions.
Pour plus d’informations, consultez les ressources GitHub suivantes :
- Abstractions réseau client/serveur (dotnet/AspNetCore #10308)
- Implémenter une nouvelle abstraction d’écouteur de base et remise en plateforme Kestrel au-dessus (dotnet/AspNetCore #10321)
Pour les applications qui ciblent des versions antérieures d’ASP.NET Core :
- Kestrel ajoute des en-têtes d’amorce de fin segmentés HTTP/1.1 dans la collection d’en-têtes de requête.
- Les amorces de fin sont disponibles une fois que le corps de la requête a été lu jusqu’à la fin.
Cela provoque certains problèmes d’ambiguïté entre les en-têtes et les amorces de fin, qui déplacent les amorces de fin vers une nouvelle collection (RequestTrailerExtensions
) dans la version 3.0.
Les amorces de fin de requête HTTP/2 sont les suivantes :
- Non disponible dans ASP.NET Core 2.2.
- Disponible dans la version 3.0 en tant que
RequestTrailerExtensions
.
De nouvelles méthodes d’extension de requête ont été ajoutées pour accéder à ces amorces de fin. Comme avec HTTP/1.1, les amorces de fin sont disponibles une fois que le corps de la requête a été lu jusqu’à la fin.
Pour la version 3.0, les méthodes RequestTrailerExtensions
suivantes sont disponibles :
GetDeclaredTrailers
: obtient l’en-têteTrailer
pour la requête qui répertorie les amorces de fin à attendre après le corps.SupportsTrailers
: indique si la requête prend en charge la réception des en-têtes d’amorce de fin.CheckTrailersAvailable
: détermine si la requête prend en charge les codes de fin et s’ils sont disponibles pour la lecture. Cette vérification ne suppose pas qu’il existe des amorces de fin à lire. Il peut n’y avoir aucune amorce de fin à lire même sitrue
est retourné par cette méthode.GetTrailer
: obtient l’en-tête de l’amorce de fin demandé à partir de la réponse. VérifiezSupportsTrailers
avant d’appelerGetTrailer
, ou un NotSupportedException peut se produire si la requête ne prend pas en charge les en-têtes de fin.
Pour plus d’informations, consultez la section Placer des amorces de fin de requête dans une collection distincte (dotnet/AspNetCore #10410) (seulement disponible en anglais).
AllowSynchronousIO
active ou désactive les API d’E/S synchrones, comme HttpRequest.Body.Read
, HttpResponse.Body.Write
et Stream.Flush
. Ces API sont une source de privation de threads qui entraîne des incidents d’application. Dans la version 3.0, AllowSynchronousIO
est désactivé par défaut. Pour plus d’informations, consultez la section E/S synchrones de cet Kestrelarticle.
Lorsqu’elles sont nécessaires, vous pouvez activer les E/S synchrones en configurant l’option AllowSynchronousIO
sur le serveur utilisé (lors de l’appel de ConfigureKestrel
, par exemple, si vous utilisez Kestrel). Notez que les serveurs (Kestrel, HttpSys, TestServer, etc.) ont tous leur propre AllowSynchronousIO
option qui n’affecte pas les autres serveurs. Les E/S synchrones peuvent être activées pour tous les serveurs par requête avec l’option IHttpBodyControlFeature.AllowSynchronousIO
:
var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();
if (syncIOFeature != null)
{
syncIOFeature.AllowSynchronousIO = true;
}
Si vous rencontrez des problèmes avec les implémentations TextWriter ou d’autres flux qui appellent des API synchrones dans Dispose, appelez plutôt la nouvelle API DisposeAsync.
Pour plus d’informations, consultez l’annonce [Annonce] AllowSynchronousIO désactivé sur tous les serveurs (dotnet/AspNetCore #7644) (seulement disponible en anglais).
Les formateurs de sortie basés sur Newtonsoft.Json, XmlSerializeret DataContractSerializer prennent uniquement en charge la sérialisation synchrone. Pour que ces formateurs puissent fonctionner avec les restrictions AllowSynchronousIO du serveur, MVC met en mémoire tampon la sortie de ces formateurs avant d’écrire sur le disque. Suite à la mise en mémoire tampon, MVC inclut l’en-tête Content-Length lorsqu’il répond avec ces formateurs.
System.Text.Json prend en charge la sérialisation asynchrone et, par conséquent, le formateur basé sur System.Text.Json
n’effectue pas la mise en mémoire tampon. Envisagez d’utiliser ce formateur pour améliorer les performances.
Pour désactiver la mise en mémoire tampon, les applications peuvent configurer SuppressOutputFormatterBuffering au démarrage :
services.AddControllers(options => options.SuppressOutputFormatterBuffering = true)
Notez que cela peut entraîner la levée d’une exception de runtime par l’application si AllowSynchronousIO
n’est pas également configuré.
Dans ASP.NET Core 2.1, les contenus de Microsoft.AspNetCore.Server.Kestrel.Https.dll ont été déplacés dans Microsoft.AspNetCore.Server.Kestrel.Core.dll. Il s’agit d’une mise à jour non cassante à l’aide des attributs TypeForwardedTo
. Avec la version 3.0, l’assembly Microsoft.AspNetCore.Server.Kestrel.Https.dll et le package NuGet ont été supprimés.
Les bibliothèques faisant référence à Microsoft.AspNetCore.Server.Kestrel.Https doivent mettre à jour toutes les dépendances ASP.NET Core vers la version 2.1 ou ultérieure.
Les applications et les bibliothèques qui ciblent ASP.NET Core 2.1 ou version ultérieure doivent supprimer toutes les références directes au package Microsoft.AspNetCore.Server.Kestrel.Https.
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.
Installez le package NuGet Microsoft.AspNetCore.SignalR.Protocols.NewtonsoftJson.
Sur le client, chaînez un appel de méthode
AddNewtonsoftJsonProtocol
à l’instanceHubConnectionBuilder
:new HubConnectionBuilder() .WithUrl("/chathub") .AddNewtonsoftJsonProtocol(...) .Build();
Sur le serveur, chaînez un appel de méthode
AddNewtonsoftJsonProtocol
à l’appel de méthodeAddSignalR
dansStartup.ConfigureServices
:services.AddSignalR() .AddNewtonsoftJsonProtocol(...);
Installez le package
Microsoft.AspNetCore.Mvc.NewtonsoftJson
.Mettez à jour
Startup.ConfigureServices
pour appelerAddNewtonsoftJson
.services.AddMvc() .AddNewtonsoftJson();
AddNewtonsoftJson
est compatible avec les méthodes d’inscription du service MVC :AddRazorPages
AddControllersWithViews
AddControllers
services.AddControllers() .AddNewtonsoftJson();
Les paramètres
Newtonsoft.Json
peuvent être définis dans l’appel surAddNewtonsoftJson
: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 packageMicrosoft.AspNetCore.Mvc.NewtonsoftJson
. Une erreur courante consiste à installer le package Newtonsoft.Json au lieu du packageMicrosoft.AspNetCore.Mvc.NewtonsoftJson
.
Pour plus d’informations, consultez la section Ajouter la prise en charge du format JSON basé sur Newtonsoft.Json.
ASP.NET Core 3.0 ajoute de nouvelles options pour inscrire les scénarios MVC dans Startup.ConfigureServices
.
Trois nouvelles méthodes d’extension de niveau supérieur dédiées aux scénarios MVC sur IServiceCollection
sont disponibles. Les modèles utilisent ces nouvelles méthodes au lieu d’AddMvc
. Toutefois, AddMvc
continue de se comporter comme dans les versions précédentes.
L’exemple suivant ajoute la prise en charge des contrôleurs et des fonctionnalités liées à l’API, mais pas celle des vues ou des pages. Le modèle d’API utilise ce code :
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
}
L’exemple suivant ajoute la prise en charge des contrôleurs, des fonctionnalités liées à l’API, et des vues, mais pas celle des pages. Le modèle d’application web (MVC) utilise ce code :
public void ConfigureServices(IServiceCollection services)
{
services.AddControllersWithViews();
}
L’exemple suivant ajoute la prise en charge de Razor Pages et la prise en charge minimale du contrôleur. Le modèle d’application web utilise ce code :
public void ConfigureServices(IServiceCollection services)
{
services.AddRazorPages();
}
Les nouvelles méthodes peuvent également être combinées. L’exemple suivant équivaut à appeler AddMvc
dans ASP.NET Core 2.2 :
public void ConfigureServices(IServiceCollection services)
{
services.AddControllersWithViews();
services.AddRazorPages();
}
Si une application appelle UseMvc
ou UseSignalR
, migrez l’application vers le routage des points de terminaison si possible. Pour améliorer la compatibilité du routage des points de terminaison avec les versions précédentes de MVC, nous avons rétabli certaines des modifications apportées à la génération d’URL introduites dans ASP.NET Core 2.2. Si vous avez rencontré des problèmes lors de l’utilisation du routage des points de terminaison avec la version 2.2, vous devriez enregistrer des améliorations dans ASP.NET Core 3.0 avec les exceptions suivantes :
- Si l’application implémente
IRouter
ou hérite deRoute
, 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.
Conseil d’ordre général :
Ajoutez
UseRouting
.Si l’application appelle
UseStaticFiles
, placezUseStaticFiles
avantUseRouting
.Si l’application utilise des fonctionnalités d’authentification/autorisation (comme
AuthorizePage
ou[Authorize]
), passez l’appel àUseAuthentication
etUseAuthorization
aprèsUseRouting
etUseCors
, mais avantUseEndpoints
:public void Configure(IApplicationBuilder app) { ... app.UseStaticFiles(); app.UseRouting(); app.UseCors(); app.UseAuthentication(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); });
Remplacez
UseMvc
ouUseSignalR
parUseEndpoints
.Si l’application utilise des scénarios CORS (comme
[EnableCors]
), passez l’appel àUseCors
avant tout autre intergiciel utilisant CORS (par exemple, passezUseCors
avantUseAuthentication
,UseAuthorization
etUseEndpoints
).Remplacez
IHostingEnvironment
parIWebHostEnvironment
et ajoutez une instructionusing
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
, UseAuthorization
et UseCors
doivent apparaître entre les appels à UseRouting
et UseEndpoints
.
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.
La prise en charge de l’autorisation et de CORS est unifiée autour de l’approche par intergiciel. Cela permet d’utiliser les mêmes intergiciels et les mêmes fonctionnalités dans ces scénarios. Cette version fournit un intergiciel d’autorisation mis à jour. L’intergiciel CORS a été amélioré pour comprendre les attributs utilisés par les contrôleurs MVC.
Auparavant, CORS pouvait être difficile à configurer. L’intergiciel était fourni pour certains cas d’usage, alors que les filtres MVC étaient destinés à être utilisés sans intergiciel dans les autres cas d’usage. Avec ASP.NET Core 3.0, nous recommandons que toutes les applications qui ont besoin de CORS utilisent l’intergiciel CORS en tandem avec le routage des points de terminaison. UseCors
peut être fourni avec une stratégie par défaut. Si nécessaire, les attributs [EnableCors]
et [DisableCors]
peuvent être utilisés pour remplacer la stratégie par défaut.
Dans l’exemple suivant :
- CORS est activé pour tous les points de terminaison avec la stratégie nommée
default
. - La classe
MyController
désactive CORS avec l’attribut[DisableCors]
.
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseCors("default");
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
});
}
[DisableCors]
public class MyController : ControllerBase
{
...
}
Dans les versions antérieures d’ASP.NET Core, la prise en charge des autorisations était assurée avec l’attribut [Authorize]
. L’intergiciel d’autorisation n’était pas disponible. Dans ASP.NET Core 3.0, l’intergiciel d’autorisation est requis. Nous vous recommandons de placer l’intergiciel d’autorisation ASP.NET Core (UseAuthorization
) immédiatement après UseAuthentication
. Le middleware d’autorisation peut également être configuré avec une stratégie par défaut qui peut être remplacée.
Dans ASP.NET Core 3.0 ou version ultérieure, UseAuthorization
est appelé dans Startup.Configure
, et le HomeController
suivant exige un utilisateur connecté :
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
});
}
public class HomeController : Controller
{
[Authorize]
public IActionResult BuyWidgets()
{
...
}
}
Lorsque vous utilisez le routage des points de terminaison, nous recommandons de ne pas configurer AuthorizeFilter, mais de s’appuyer sur l’intergiciel d’autorisation. Si l’application utilise un AuthorizeFilter
comme filtre global dans MVC, nous recommandons de refactoriser le code pour fournir une stratégie dans l’appel à AddAuthorization
.
DefaultPolicy
étant initialement configurée pour exiger une authentification, aucune configuration supplémentaire n’est requise. Dans l’exemple suivant, les points de terminaison MVC sont marqués comme RequireAuthorization
, de sorte que toutes les requêtes doivent être autorisées en fonction de DefaultPolicy
. Toutefois, le HomeController
autorise l’accès sans que l’utilisateur se connecte à l’application en raison de [AllowAnonymous]
:
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute().RequireAuthorization();
});
}
[AllowAnonymous]
public class HomeController : Controller
{
...
}
L’autorisation peut également être configurée pour des classes spécifiques de points de terminaison. Le code suivant est un exemple de conversion d’une application MVC qui a configuré une application globale AuthorizeFilter
en une application dotée d’une stratégie spécifique qui exige une autorisation :
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
static readonly string _RequireAuthenticatedUserPolicy =
"RequireAuthenticatedUserPolicy";
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("DefaultConnection")));
services.AddDefaultIdentity<IdentityUser>(
options => options.SignIn.RequireConfirmedAccount = true)
.AddEntityFrameworkStores<ApplicationDbContext>();
// Pre 3.0:
// services.AddMvc(options => options.Filters.Add(new AuthorizeFilter(...));
services.AddControllersWithViews();
services.AddRazorPages();
services.AddAuthorization(o => o.AddPolicy(_RequireAuthenticatedUserPolicy,
builder => builder.RequireAuthenticatedUser()));
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute()
.RequireAuthorization(_RequireAuthenticatedUserPolicy);
endpoints.MapRazorPages();
});
}
}
Les stratégies peuvent également être personnalisées. DefaultPolicy
est configurée pour exiger l’authentification :
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("DefaultConnection")));
services.AddDefaultIdentity<IdentityUser>(
options => options.SignIn.RequireConfirmedAccount = true)
.AddEntityFrameworkStores<ApplicationDbContext>();
services.AddControllersWithViews();
services.AddRazorPages();
services.AddAuthorization(options =>
{
options.DefaultPolicy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
});
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute().RequireAuthorization();
endpoints.MapRazorPages();
});
}
}
[AllowAnonymous]
public class HomeController : Controller
{
Vous pouvez également configurer tous les points de terminaison pour exiger une autorisation sans [Authorize]
ou RequireAuthorization
, en configurant une FallbackPolicy
. FallbackPolicy
est différente de DefaultPolicy
. DefaultPolicy
est déclenchée par [Authorize]
ou RequireAuthorization
, tandis que FallbackPolicy
est déclenchée lorsqu’aucune autre stratégie n’est définie. FallbackPolicy
est initialement configurée pour autoriser les requêtes sans autorisation.
L’exemple suivant est identique à l’exemple DefaultPolicy
précédent, mais utilise FallbackPolicy
pour toujours exiger l’authentification sur tous les points de terminaison, sauf quand [AllowAnonymous]
est spécifié :
public void ConfigureServices(IServiceCollection services)
{
...
services.AddAuthorization(options =>
{
options.FallbackPolicy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
});
}
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
});
}
[AllowAnonymous]
public class HomeController : Controller
{
...
}
L’autorisation par intergiciel fonctionne sans que l’infrastructure ait une connaissance spécifique de l’autorisation. Par instance, les contrôles d’intégrité n’ont aucune connaissance spécifique de l’autorisation. En revanche, les contrôles d’intégrité peuvent avoir une stratégie d’autorisation configurable appliquée par un intergiciel.
En outre, chaque point de terminaison peut personnaliser ses propres exigences d’autorisation. Dans l’exemple suivant, UseAuthorization
traite l’autorisation avec DefaultPolicy
mais le point de terminaison de contrôle d’intégrité /healthz
exige un utilisateur admin
:
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints
.MapHealthChecks("/healthz")
.RequireAuthorization(new AuthorizeAttribute(){ Roles = "admin", });
});
}
La protection est implémentée pour certains scénarios. Endpoints Middleware lève une exception si une autorisation ou une stratégie CORS est ignorée en raison d’un intergiciel manquant. La prise en charge de l’analyseur pour fournir des commentaires supplémentaires sur une configuration incorrecte est en cours.
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.
Le mappage des hubs SignalR se déroule désormais dans UseEndpoints
.
Mappez chaque hub avec MapHub
. Comme avec les versions précédentes, chaque hub est explicitement répertorié.
Dans l’exemple suivant, la prise en charge du hub SignalRChatHub
a été ajoutée :
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>();
});
}
Une nouvelle option permet decontrôler les limites de taille des messages à partir des clients. Par exemple, dans Startup.ConfigureServices
:
services.AddSignalR(hubOptions =>
{
hubOptions.MaximumReceiveMessageSize = 32768;
});
Dans ASP.NET Core 2.2, vous pouviez définir TransportMaxBufferSize
qui contrôlait efficacement la taille maximale des messages. Dans ASP.NET Core 3.0, cette option contrôle désormais uniquement la taille maximale avant l’observation de la contre-pression.
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.
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
avecMapControllerRoute
MapAreaRoute
avecMapAreaControllerRoute
É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?}");
});
}
Dans ASP.NET Core 3.0, ASP.NET Core MVC supprime le suffixe Async
dans le nom des actions des contrôleurs. Cette nouvelle valeur par défaut affecte le routage et la génération de liens. Par exemple :
public class ProductsController : Controller
{
public async Task<IActionResult> ListAsync()
{
var model = await _dbContext.Products.ToListAsync();
return View(model);
}
}
Avant ASP.NET Core 3.0 :
L’action précédente était accessible avec la route Products/ListAsync.
La génération de liens exigeait de définir le suffixe
Async
. Par exemple :<a asp-controller="Products" asp-action="ListAsync">List</a>
Avec ASP.NET Core 3.0 :
L’action précédente peut être accessible avec la route Products/List.
La génération de liens n’exige pas de spécifier le suffixe
Async
. Par exemple :<a asp-controller="Products" asp-action="List">List</a>
Ce changement n’affecte pas les noms spécifiés à l’aide de l’attribut [ActionName]
. Le comportement par défaut est désactivé avec le code suivant dans Startup.ConfigureServices
:
services.AddMvc(options =>
options.SuppressAsyncSuffixInActionNames = false);
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.
Le mappage de Razor Pages se déroule désormais dans UseEndpoints
.
Ajoutez MapRazorPages
si l’application utilise Razor Pages. Étant donné que le routage des points de terminaison inclut la prise en charge de nombreuses infrastructures, l’ajout de Razor Pages est maintenant une option à activer.
Dans la méthode Startup.Configure
suivante, MapRazorPages
ajoute la prise en charge de Razor Pages :
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
L’utilisation de MVC avec UseMvc
ou UseMvcWithDefaultRoute
dans ASP.NET Core 3.0 exige une activation explicite dans Startup.ConfigureServices
. Cela est obligatoire, car MVC doit savoir s’il peut s’appuyer sur l’intergiciel d’autorisation et CORS lors de l’initialisation. Un analyseur fourni avertit si l’application tente d’utiliser une configuration non prise en charge.
Si l’application nécessite une prise en charge IRouter
héritée, désactivez EnableEndpointRouting
avec l’une des approches suivantes dans Startup.ConfigureServices
:
services.AddMvc(options => options.EnableEndpointRouting = false);
services.AddControllers(options => options.EnableEndpointRouting = false);
services.AddControllersWithViews(options => options.EnableEndpointRouting = false);
services.AddRazorPages().AddMvcOptions(options => options.EnableEndpointRouting = false);
Les contrôles d’intégrité peuvent être utilisés comme router-ware avec le routage des points de terminaison.
Ajoutez MapHealthChecks
pour utiliser les contrôles d’intégrité avec le routage des points de terminaison. La méthode MapHealthChecks
accepte des arguments similaires à UseHealthChecks
. Utiliser MapHealthChecks
plutôt qu’UseHealthChecks
permet d’appliquer l’autorisation et d’avoir un contrôle plus précis sur la stratégie de correspondance.
Dans l’exemple suivant, MapHealthChecks
est appelé pour un point de terminaison de contrôle d’intégrité à l’adresse /healthz
:
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/healthz", new HealthCheckOptions() { });
});
}
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 d’injection de dépendances (DI) de HostBuilder
:
- permettent de générer le conteneur de DI une seule fois.
- éliminent les problèmes de durée de vie des objets qui en résultent (comme la résolution de plusieurs instances de singleton).
Pour plus d’informations, consultez l’article Éviter l’injection de services de démarrage dans ASP.NET Core 3 (seulement disponible en anglais).
Les méthodes AddAuthorization
d’ASP.NET Core 2.2 ou version antérieure dans Microsoft.AspNetCore.Authorization.dll :
- ont été renommées
AddAuthorizationCore
. - ont été déplacées vers Microsoft.AspNetCore.Authorization.Policy.dll.
Les applications qui utilisent à la fois Microsoft.AspNetCore.Authorization.dll et Microsoft.AspNetCore.Authorization.Policy.dll ne sont pas affectées.
Les applications qui n’utilisent pas Microsoft.AspNetCore.Authorization.Policy.dll doivent effectuer l’une des opérations suivantes :
- Ajouter une référence à Microsoft.AspNetCore.Authorization.Policy.dll. Cette approche fonctionne pour la plupart des applications et constitue la seule action requise.
- Basculer vers l’utilisation de
AddAuthorizationCore
Pour plus d’informations, consultez l’article Un changement cassant dans une surcharge AddAuthorization(o =>
) se trouve dans un autre assembly #386 (seulement disponible en anglais).
Identity met à jour l’interface utilisateur pour ASP.NET Core 3.0 :
- Il ajoute une référence de package vers Microsoft.AspNetCore.Identity.UI.
- Les applications qui n’utilisent pas Razor Pages doivent appeler
MapRazorPages
. Consultez la section Razor Pages du présent document. - Bootstrap 4 est l’infrastructure d’interface utilisateur par défaut. Définissez une propriété de projet
IdentityUIFrameworkVersion
pour modifier la valeur par défaut. Pour plus d’informations, consultez cette annonce GitHub (seulement disponible en anglais).
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 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();
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.
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.
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 :
Installez le package NuGet Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.
Mettez à jour
Startup.ConfigureServices
pour appelerAddRazorRuntimeCompilation
:Pour ASP.NET Core MVC, utilisez le code suivant :
services.AddControllersWithViews() .AddRazorRuntimeCompilation(...);
Pour ASP.NET Core Razor Pages, utilisez le code suivant :
services.AddRazorPages() .AddRazorRuntimeCompilation(...);
L’exemple à l’adresse https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation représente l’activation conditionnelle de la compilation au runtime en environnements de développement.
Pour plus d’informations sur la compilation des fichiers Razor, consultez l’article Compilation des fichiers Razor dans ASP.NET Core.
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.
Par défaut, le système de validation de .NET Core 3.0 traite les paramètres non-nullables et les propriétés liées comme s’ils avaient un attribut [Required]
. Pour plus d’informations, consultez la section Attribut [Required].
Supprimez les dossiers bin et obj dans le répertoire du projet.
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);
}
Examinez les changements cassants :
- Liste complète des changements cassants apportés à ASP.NET Core 3.0 (seulement disponible en anglais).
- Changements cassants d’API Antiforgery, CORS, Diagnostics, MVC et Routing (seulement disponible en anglais). Cette liste inclut les changements cassants pour les commutateurs de compatibilité.
- Passez en revue les changements cassants entre la version 2.2 et la version 3.0 de .NET Core, d’ASP.NET Core et d’Entity Framework Core. Pour cela, consultez l’article sur les changements cassants de la migration de la version 2.2 à la version 3.0.
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.
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.
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.
Commentaires sur ASP.NET Core
ASP.NET Core est un projet open source. Sélectionnez un lien pour fournir des commentaires :