Migrer de ASP.NET Core dans .NET 7 vers .NET 8

  • Article

Cet article explique comment mettre à jour un projet ASP.NET Core 7.0 existant vers ASP.NET Core 8.0.

Prérequis

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

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

{
  "sdk": {
-    "version": "7.0.100"
+    "version": "8.0.100"
  }
}

Mettre à jour le framework cible

Mettez à jour le moniker de framework cible (TFM) du fichier projet vers net8.0 :

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

  <PropertyGroup>
-    <TargetFramework>net7.0</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

</Project>

Mettre à jour les références de package

Dans le fichier projet, mettez à jour chaque attribut de référence de package Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.* et System.Net.Http.JsonVersion vers la version 8.00 ou ultérieure. Par exemple :

<ItemGroup>
-   <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="7.0.12" />
-   <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.12" />
-   <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="7.0.0" />
-   <PackageReference Include="System.Net.Http.Json" Version="7.0.1" />
+   <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="8.0.0" />
+   <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="8.0.0" />
+   <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="8.0.0" />
+   <PackageReference Include="System.Net.Http.Json" Version="8.0.0" />
</ItemGroup>

Blazor

Les scénarios de migration suivant sont pris en charge :

Pour obtenir des conseils sur l’ajout Blazor de la prise en charge à une application ASP.NET Core, consultez Intégrer des composants ASP.NET Core dans des applicationsRazor ASP.NET Core.

Mettre à jour une Blazor Server application

Nous vous recommandons d’utiliser Blazor Web Apps dans .NET 8, mais Blazor Server il est pris en charge. Pour continuer à utiliser Blazor Server avec .NET 8, suivez les conseils des trois premières sections de cet article :

Les nouvelles fonctionnalités Blazor introduites pour Web Apps ne sont pas disponibles pour Blazor une Blazor Server application mise à jour pour s’exécuter sous .NET 8. Si vous souhaitez adopter les nouvelles fonctionnalités .NET 8 Blazor, suivez les instructions de l’une des sections suivantes :

Adopter toutes les conventions d’application webBlazor

Pour adopter éventuellement toutes les nouvelles Blazor conventions d’application web, nous vous recommandons le processus suivant :

  • Créez une application à partir du modèle de Blazor projet Web App. Pour plus d’informations, consultez Outils pour ASP.NET Core Blazor.
  • Déplacez vos composants et le code de l’application vers la nouvelle application web Blazor en apportant des modifications pour adopter les nouvelles fonctionnalités.
  • Mettez à jour la disposition et les styles de l’application Blazor web.

Les nouvelles fonctionnalités de .NET 8 sont abordées dans What’s new in ASP.NET Core 8.0. Lors de la mise à jour d’une application à partir de .NET 6 ou version antérieure, consultez les notes de migration et de publication (nouveautés) pour les versions intermédiaires.

Convertir une application Blazor Server en application web Blazor

Les applications Blazor Server sont prises en charge dans .NET 8 sans aucune modification de code. Utilisez les instructions suivantes pour convertir une Blazor Server application en une application web .NET 8 Blazor équivalente, ce qui rend toutes les nouvelles fonctionnalités .NET 8 disponibles.

Important

Cette section se concentre sur les modifications minimales requises pour convertir une application .NET 7 Blazor Server en application web .NET 8 Blazor. Pour adopter toutes les nouvelles conventions d’application web Blazor, suivez les instructions de la section Adopter toutesBlazor les conventions application web .

  1. Suivez l’aide des trois premières sections suivantes de cet article :

  2. Déplacez le contenu du App composant (App.razor) vers un nouveau Routes fichier de composant (Routes.razor) ajouté au dossier racine du projet. Laissez le fichier vide App.razor dans l’application dans le dossier racine du projet.

  3. Ajoutez une entrée au _Imports.razor fichier pour rendre les modes de rendu abrégés disponibles pour l’application :

    @using static Microsoft.AspNetCore.Components.Web.RenderMode

  4. Déplacez le contenu de la _Host page (Pages/_Host.cshtml) vers le fichier vide App.razor. Passez aux modifications suivantes pour le App composant.

    Remarque

    Dans l’exemple suivant, l’espace de noms du projet est BlazorServerApp. Ajustez l’espace de noms pour qu’il corresponde à votre projet.

    Supprimez les lignes suivantes à partir de la partie supérieure du fichier :

    - @page "/"
- @using Microsoft.AspNetCore.Components.Web
- @namespace BlazorServerApp.Pages
- @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

    Remplacez les lignes précédentes par une ligne qui injecte une instance IHostEnvironment :

    @inject IHostEnvironment Env

    Supprimez le tilde (~) de la href<base> balise et remplacez par le chemin d’accès de base de votre application :

    - <base href="~/" />
+ <base href="/" />

    Supprimez le Tag Helper de composant pour le composant HeadOutlet et remplacez-le par le composant HeadOutlet.

    Supprimez la ligne suivante :

    - <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

    Remplacez la ligne précédente par ce qui suit :

    <HeadOutlet @rendermode="InteractiveServer" />

    Supprimez le Tag Helper de composant pour le composant App et remplacez-le par le composant Routes.

    Supprimez la ligne suivante :

    - <component type="typeof(App)" render-mode="ServerPrerendered" />

    Remplacez la ligne précédente par ce qui suit :

    <Routes @rendermode="InteractiveServer" />

    Remarque

    La configuration précédente suppose que les composants de l’application adoptent le rendu interactif du serveur. Pour plus d’informations, notamment sur l’adoption du rendu statique côté serveur, consultez modes de rendu Blazor ASP.NET Core.

    Supprimez les Tag Helpers d’environnement pour l’interface utilisateur d’erreur et remplacez-les par la balise Razor suivante.

    Supprimez les lignes suivantes :

    - <environment include="Staging,Production">
-     An error has occurred. This application may no longer respond until reloaded.
- </environment>
- <environment include="Development">
-     An unhandled exception has occurred. See browser dev tools for details.
- </environment>

    Remplacez les lignes précédentes par ce qui suit :

    @if (Env.IsDevelopment())
{
    <text>
        An unhandled exception has occurred. See browser dev tools for details.
    </text>
}
else
{
    <text>
        An error has occurred. This app may no longer respond until reloaded.
    </text>
}

    Modifiez le script Blazor de blazor.server.js à blazor.web.js :

    - <script src="_framework/blazor.server.js"></script>
+ <script src="_framework/blazor.web.js"></script>

  5. Supprimez le fichier Pages/_Host.cshtml.

  6. Mettez à jour Program.cs :

    Remarque

    Dans l’exemple suivant, l’espace de noms du projet est BlazorServerApp. Ajustez l’espace de noms pour qu’il corresponde à votre projet.

    Ajoutez une instruction using en haut du fichier pour l’espace de noms du projet :

    using BlazorServerApp;

    Remplacez AddServerSideBlazor par AddRazorComponents et un appel en chaîne à AddInteractiveServerComponents.

    Supprimez la ligne suivante :

    - builder.Services.AddServerSideBlazor();

    Remplacez la ligne précédente par le composant Razor et les services de composant de serveur interactifs. L’appel de AddRazorComponents ajoute des services antiforgery (AddAntiforgery) par défaut.

    builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

    Supprimez la ligne suivante :

    - app.MapBlazorHub();

    Remplacez la ligne précédente par un appel à MapRazorComponents, en fournissant le composant App comme type de composant racine et en ajoutant un appel chaîné à AddInteractiveServerRenderMode :

    app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

    Supprimez la ligne suivante :

    - app.MapFallbackToPage("/_Host");

    Ajoutez middleware Antiforgery au pipeline de traitement des demandes après l’appel à app.UseRouting. S’il y a des appels vers app.UseRouting et app.UseEndpoints, l’appel vers app.UseAntiforgery doit passer entre eux. Un appel à app.UseAntiforgery doit être placer après les appels à app.UseAuthentication et app.UseAuthorization. Il n’est pas nécessaire d’ajouter des services antiforgery (builder.Services.AddAntiforgery()), car ils sont ajoutés automatiquement par AddRazorComponents, qui a été couvert précédemment.

    app.UseAntiforgery();

  7. Si l’application Blazor Server a été configurée pour désactiver le pré-rendering, vous pouvez continuer à désactiver le pré-rendering pour l’application mise à jour. Dans le composant App, modifiez la valeur affectée aux @rendermodeRazor attributs de directive pour les composants et HeadOutlet les Routes composants.

    Modifiez la valeur de l’attribut de directive @rendermode pour que les composants HeadOutlet et Routes désactivent le pré-rendu :

    - @rendermode="InteractiveServer"
+ @rendermode="new InteractiveServerRenderMode(prerender: false)"

    Pour plus d’informations, consultez Modes de rendu ASP.NET Core Blazor.

Mettre à jour une application Blazor WebAssembly

Suivez l’aide des trois premières sections suivantes de cet article :

Convertir une application hébergée Blazor WebAssembly en application web Blazor

Les applications Blazor WebAssembly sont prises en charge dans .NET 8 sans aucune modification de code. Utilisez les instructions suivantes pour convertir une application hébergé par ASP.NET Core Blazor WebAssembly en une application web .NET 8 Blazor équivalente, ce qui rend toutes les nouvelles fonctionnalités .NET 8 disponibles.

Important

Cette section se concentre sur les modifications minimales requises pour convertir une application .NET 7 Blazor WebAssembly en application web .NET 8 Blazor. Pour adopter toutes les nouvelles conventions d’application web Blazor, suivez les instructions de la section Adopter toutesBlazor les conventions application web .

  1. Suivez l’aide des trois premières sections suivantes de cet article :

    Important

    À l’aide des instructions précédentes, mettez à jour les projets de la solution Client, Server et Shared.

  2. Dans le fichier projet .Client (.csproj), ajoutez les propriétés MS Build suivantes :

    <NoDefaultLaunchSettingsFile>true</NoDefaultLaunchSettingsFile>
<StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode>

  3. En outre, dans le fichier projet .Client, supprimez la référence du package Microsoft.AspNetCore.Components.WebAssembly.DevServer :

    - <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer"... />

  4. Déplacez le contenu du fichier Client/wwwroot/index.html vers un nouveau fichier de composant App (App.razor) créé à la racine du projet Server. Après avoir déplacé le contenu du fichier, supprimez le fichier index.html.

  5. Renommez App.razor dans le projet .Client en Routes.razor.

  6. Dans Routes.razor, mettez à jour la valeur de l’attribut AppAssembly sur typeof(Program).Assembly.

  7. Ajoutez une entrée au _Imports.razor fichier pour rendre les modes de rendu abrégés disponibles pour l’application :

    @using static Microsoft.AspNetCore.Components.Web.RenderMode

  8. Effectuez une copie du fichier _Imports.razor et ajoutez-le au projet Server.

  9. Apportez les modifications suivantes au fichier App.razor :

    Remplacez la balise <title> par les composants HeadOutlet et PageTitle. Commencez par supprimer la balise <title>. Notez le titre, à utiliser ultérieurement, avant de supprimer la balise :

    - <title>...</title>

    Modifiez le regroupement de styles CSS :

    - <link href="{CLIENT PROJECT ASSEMBLY NAME}.styles.css" rel="stylesheet">
+ <link href="{SERVER PROJECT ASSEMBLY NAME}.styles.css" rel="stylesheet">

    Espaces réservés dans le code précédent :

    • {CLIENT PROJECT ASSEMBLY NAME} : nom d’assembly du projet client. Exemple : BlazorSample.Client
    • {SERVER PROJECT ASSEMBLY NAME} : nom d’assembly du projet serveur. Exemple : BlazorSample

    Ajoutez le composant HeadOutlet à la fin du contenu de <head> avec le mode de rendu WebAssembly interactif (prérendu désactivé). Ajoutez également le composant PageTitle avec le titre de l’application :

    <HeadOutlet @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />
<PageTitle>...</PageTitle>

    Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core Blazor.

    Recherchez le balisage HTML <div>...</div> suivant :

    - <div id="app">
-     ...
- </div>

    Remplacez la balise <div>...</div>qui précède par le composant Routes utilisant le mode de rendu WebAssembly interactif (prérendu désactivé) :

    <Routes @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />

    Mettez à jour le script blazor.webassembly.js sur blazor.web.js :

    - <script src="_framework/blazor.webassembly.js"></script>
+ <script src="_framework/blazor.web.js"></script>

  10. Supprimez les lignes suivantes de Client/Program.cs :

    - builder.RootComponents.Add<App>("#app");
- builder.RootComponents.Add<HeadOutlet>("head::after");

  11. Mettez à jour Server/Program.cs :

    Ajoutez des services de composants Razor WebAssembly interactifs et de composant WebAssembly au projet. Appel AddRazorComponents avec un appel chaîné à AddInteractiveWebAssemblyComponents. L’appel de AddRazorComponents ajoute des services antiforgery (AddAntiforgery) par défaut.

    builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

    AjoutezAntiforgery Middleware au pipeline de traitement des requêtes.

    Placez le code suivant :

    • Après l’appel à app.UseRouting.
    • S’il y a des appels vers app.UseRouting et app.UseEndpoints, l’appel vers app.UseAntiforgery doit passer entre eux.
    • L’appel à app.UseAntiforgery doit être placé après un appel à app.UseAuthorization, le cas échéant.
    • Il n’est pas nécessaire d’ajouter des services antiforgery (builder.Services.AddAntiforgery()), car ils sont ajoutés automatiquement par AddRazorComponents, qui a été couvert précédemment.
    app.UseAntiforgery();

    Supprimez la ligne suivante :

    - app.UseBlazorFrameworkFiles();

    Supprimez la ligne suivante :

    - app.MapFallbackToFile("index.html");

    Remplacez la ligne précédente par un appel à MapRazorComponents, en fournissant le composant App comme type de composant racine et en ajoutant des appels chaînés à AddInteractiveWebAssemblyRenderMode et AddAdditionalAssemblies :

    app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof({CLIENT APP NAMESPACE}._Imports).Assembly);

    Dans l’exemple précédent, l’espace {CLIENT APP NAMESPACE} réservé est l’espace de noms du projet .Client (par exemple, HostedBlazorApp.Client). Remplacez l’espace réservé .Client par l’espace de noms du projet.

  12. Exécutez la solution depuis le projet Server :

    Pour Visual Studio, vérifiez que le projet Server est sélectionné dans Explorateur de solutions lors de l’exécution de l’application.

    Si vous utilisez l’interface CLI .NET, exécutez le projet à partir du dossier du projet Server.

Mettre à jour la configuration des options de service et de point de terminaison

Avec la publication de Web Apps Blazor dans .NET 8, la configuration des options du service Blazor et de point de terminaison est mise à jour avec l’introduction de la nouvelle API pour les services de composants interactifs et la configuration du point de terminaison de composant.

Les instructions de configuration mises à jour s’affichent aux emplacements suivants :

Déposer Blazor Server avec la solution de contournement du routage Yarp

Si vous avez précédemment suivi les instructions de l’option Activer ASP.NET Core Blazor Server avec Yarp pour la migration incrémentielle d’une Blazor Server application avec Yarp vers .NET 6 ou .NET 7, vous pouvez inverser les étapes de contournement que vous avez effectuées lors de la suite des instructions de l’article. Le routage et le lien profond pour Blazor Server avec Yarp fonctionnent correctement dans .NET 8.

Migrer des composants CascadingValue dans les composants de disposition

Les paramètres en cascade ne transmettent pas de données au-delà des limites du mode de rendu, et les dispositions sont rendues statiquement dans les applications interactives. Par conséquent, les applications qui cherchent à utiliser des paramètres en cascade dans des composants rendus de façon interactive ne pourront pas faire descendre en cascade les valeurs d’une disposition.

Les deux approches de migration sont les suivantes :

  • (Recommandé) Transmettez l’état en tant que valeur en cascade au niveau racine. Pour plus d’informations, consultez Valeurs en cascade au niveau racine.
  • Habillez le routeur dans le composant Routes avec le composant CascadingValue et effectuez un rendu du composant Routes de manière interactive. Pour obtenir un exemple, consultez Composant CascadingValue.

Pour plus d’informations, consultez Valeurs/Paramètres en cascade et limites du mode de rendu.

Migrer la propriété BlazorEnableCompression MSBuild

Pour les applications Blazor WebAssembly qui désactivent la compression et ciblent .NET 7 ou une version antérieure, mais qui sont générées avec le kit de développement logiciel (SDK) .NET 8, la propriété MSBuild BlazorEnableCompression a changé pour CompressionEnabled :

<PropertyGroup>
-   <BlazorEnableCompression>false</BlazorEnableCompression>
+   <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

Lorsque vous utilisez la commande de publication CLI .NET, utilisez la nouvelle propriété :

dotnet publish -p:CompressionEnabled=false

Pour plus d’informations, consultez les ressources suivantes :

Migrer le composant <CascadingAuthenticationState> vers les services d’état d’authentification en cascade

Dans .NET 7 ou version antérieure, le composant CascadingAuthenticationState est enveloppé autour d’une partie de l’arborescence de l’interface utilisateur, par exemple autour du routeur Blazor, pour fournir l’état d’authentification en cascade :

<CascadingAuthenticationState>
    <Router ...>
        ...
    </Router>
</CascadingAuthenticationState>

Dans .NET 8, n’utilisez pas le composant CascadingAuthenticationState :

- <CascadingAuthenticationState>
      <Router ...>
          ...
      </Router>
- </CascadingAuthenticationState>

Ajoutez plutôt des services d’état d’authentification en cascade à la collection de services en appelant AddCascadingAuthenticationState dans le fichier Program :

builder.Services.AddCascadingAuthenticationState();

Pour plus d’informations, consultez les ressources suivantes :

Nouvel article sur les problèmes de mise en cache HTTP

Nous avons ajouté un nouvel article qui aborde certains des problèmes courants de mise en cache HTTP qui peuvent se produire lors de la mise à niveau d’applications Blazor dans des versions principales et qui explique comment résoudre des problèmes de mise en cache HTTP.

Si vous souhaitez obtenir plus d’informations, consultez Éviter les problèmes de mise en cache HTTP lors de la mise à niveau d’applications Blazor ASP.NET Core.

Nouvel article sur les bibliothèques de classes avec rendu statique côté serveur (SSR statique)

Nous avons ajouté un nouvel article qui aborde la création d’une bibliothèque de composants dans des bibliothèques de classes (RCL) Razor avec le rendu statique côté serveur (SSR statique).

Pour obtenir plus d’informations, consultez Bibliothèques de classe (RCL) Razor ASP.NET Core avec rendu statique côté serveur (SSR statique).

Découvrir des composants d’assemblys supplémentaires

Quand vous migrez depuis une application Blazor Server vers une application web Blazor, consultez les instructions de Routage et navigation d’ASP.NET Core Blazor si l’application utilise des composants routables provenant d’assemblys supplémentaires, comme des bibliothèques de classes de composants.

Supprimer l’attribut [Parameter] quand le paramètre est fourni depuis une chaîne de requête

L’attribut [Parameter] n’est plus nécessaire quand un paramètre est fourni depuis la chaîne de requête :

- [Parameter]
  [SupplyParameterFromQuery]

Autorisation de stratégie de secours du script Blazor Server

Dans .NET 7, le script Blazor Server (blazor.server.js) est servi par l’Intergiciel (middleware) de fichiers statiques. Un placement de l’appel pour l’Intergiciel (middleware) de fichiers statiques (UseStaticFiles) dans le pipeline de traitement de la requête avant l’appel à l’Intergiciel (middleware) d’autorisation (UseAuthorization) est suffisant dans les applications .NET 7 pour servir le script Blazor aux utilisateurs anonymes.

Dans .NET 8, le script Blazor Server est servi par son propre point de terminaison en utilisant le routage de point de terminaison. Ce changement est introduit par Résolution de bogue : passage d’options aux pauses UseStaticFiles Blazor Server (dotnet/aspnetcore #45897).

Considérez un scénario multilocataire dans lequel :

  • Les stratégies par défaut et de secours sont définies de manière identique.
  • Le tenant est résolu en utilisant le premier segment du chemin d’accès de la requête (par exemple, tld.com/tenant-name/...).
  • Les requêtes aux points de terminaison de tenant sont authentifiées par un schéma d’authentification supplémentaire qui ajoute une autre identité au principal de requête.
  • La stratégie d’autorisation de secours a des exigences qui vérifient les revendications via l’autre identité.

Les requêtes pour le fichier de script Blazor (blazor.server.js) sont servies à /_framework/blazor.server.js qui est codé en dur dans l’infrastructure. Les requêtes pour le fichier ne sont pas authentifiées par l’autre schéma d’authentification pour les tenants, mais sont toujours contestées par la stratégie de secours, ce qui entraîne le retour d’un résultat non autorisé.

Ce problème est en voie d’évaluation pour une nouvelle fonctionnalité d’infrastructure dans Composants rompus avec FallbackPolicy RequireAuthenticatedUser sur MappageRazor (dotnet/aspnetcore51836) qui est actuellement prévue pour la version de .NET 9 en novembre 2024. Jusqu’à cette date, vous pouvez contourner ce problème en utilisant l’une des trois approches suivantes :

  • N’utilisez pas de stratégie de secours. Appliquez l’attribut [Authorize] dans le fichier _Imports.razor pour l’appliquer à tous les composants de l’application. Pour les points de terminaison non-Blazor, utilisez explicitement [Authorize] ou RequireAuthorization.

  • Ajoutez [AllowAnonymous] au point de terminaison /_framework/blazor.server.js dans le fichier Program :

    app.MapBlazorHub().Add(endpointBuilder =>
{
    if (endpointBuilder is 
        RouteEndpointBuilder
        { 
            RoutePattern: { RawText: "/_framework/blazor.server.js" }
        })
    {
        endpointBuilder.Metadata.Add(new AllowAnonymousAttribute());
    }
});

  • Inscrivez un AuthorizationHandler personnalisé qui vérifie le HttpContext pour autoriser le passage du fichier /_framework/blazor.server.js.

Docker

Mettre à jour les images Docker

Pour les applications utilisant Docker, mettez à jour les instructions et scripts DockerfileFROM. Utilisez une image de base qui inclut le runtime ASP.NET Core 8.0. Considérez la différence de commande docker pull suivante entre ASP.NET Core 7.0 et 8.0 :

- docker pull mcr.microsoft.com/dotnet/aspnet:7.0
+ docker pull mcr.microsoft.com/dotnet/aspnet:8.0

Mettre à jour le port Docker

Le port ASP.NET Core par défaut configuré dans les images conteneur .NET a été mis à jour du port 80 vers le port 8080.

La nouvelle variable d’environnement ASPNETCORE_HTTP_PORTS a été ajoutée comme alternative plus simple à ASPNETCORE_URLS.

Pour plus d’informations, consultez l’article suivant :

Examiner les changements avec rupture

Pour les changements cassants de .NET Core .NET 7.0 à 8.0, consultez Changements cassants dans .NET 8, qui inclut des sections ASP.NET Core et Entity Framework Core.