Prérendu et intégration des composants Razor d’ASP.NET Core

Cet article explique les scénarios d’intégration de composants Razor pour les applications Blazor, y compris le prérendu des composants Razor sur le serveur.

Important

Les modifications apportées à l’infrastructure dans les versions ASP.NET Core ont donné lieu à différents ensembles d’instructions dans cet article. Avant d’utiliser les instructions de cet article, vérifiez que le sélecteur de version de document en haut de cet article correspond à la version de ASP.NET Core que vous envisagez d’utiliser pour votre application.

Les composants Razor peuvent être intégrés dans des applications Razor Pages et MVC dans une solution Blazor WebAssembly hébergée. Lorsque la page ou la vue est affichée, les composants peuvent être prérendus en même temps.

Le prérendu peut améliorer l’optimisation du référencement d’un site auprès d’un moteur de recherche (SEO) en affichant le contenu de la réponse HTTP initiale utilisée par les moteurs de recherche peuvent utiliser pour calculer l’ordre de priorité de la page.

Configuration de la solution

Configuration de du prérendu

Pour configurer le prérendu d’une application Blazor WebAssembly hébergée :

1. Hébergez l’application Blazor WebAssembly dans une application ASP.NET Core. Vous pouvez ajouter une application Blazor WebAssembly autonome à une solution ASP.NET Core ou utiliser une application Blazor WebAssembly hébergée créée à partir du modèle de projet Blazor WebAssembly avec l’option hébergée :

   • Visual Studio : cochez la case ASP.NET Core Hébergé dans la boîte de dialogue Informations supplémentaires lors de la création de l’applicationBlazor WebAssembly. Dans les exemples présentés dans cet article, la solution est nommée BlazorHosted.
   • Interpréteur de commandes CLI Visual Studio Code/.NET : dotnet new blazorwasm -ho (utilisez l’option -ho|--hosted). Utilisez l’option -o|--output {LOCATION} pour créer un dossier pour la solution et définir les espaces de noms du projet de la solution. Dans les exemples présentés dans cet article, la solution est nommée BlazorHosted (dotnet new blazorwasm -ho -o BlazorHosted).

   Pour les exemples présentés dans cet article, le nom de la solution hébergée (nom de l’assembly) est BlazorHosted. L’espace de noms du projet client est BlazorHosted.Client et l’espace de noms du projet serveur est BlazorHosted.Server.

2. Supprimez le fichier wwwroot/index.html du projet Blazor WebAssemblyClient.

3. Dans le projet Client, supprimez les lignes suivantes dans Program.cs :

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

4. Ajoutez un fichier _Host.cshtml au dossier Pages du projet Server. Vous pouvez obtenir les fichiers depuis un projet créé à partir du modèle Blazor Server à l’aide de Visual Studio ou de l’interface CLI .NET avec la commande dotnet new blazorserver -o BlazorServer dans un interpréteur de commandes (l’option -o BlazorServer crée un dossier pour le projet). Après avoir placé les fichiers dans le dossier Pages du projet Server, faites les modifications suivantes aux fichiers.

   Apportez les modifications suivantes au fichier _Host.cshtml :

   • Mettez à jour l’espace de noms Pages en haut du fichier pour le faire correspondre à l’espace de noms des pages de l’application Server. L’espace réservé {APP NAMESPACE} dans l’exemple suivant représente l’espace de noms des pages de l’application donatrice qui ont fourni le fichier _Host.cshtml :

     Supprimer :

     - @namespace {APP NAMESPACE}.Pages
     

     Ajouter :

     @namespace BlazorHosted.Server.Pages
     

   • Ajoutez une directive @using pour le projet Client en haut du fichier :

     @using BlazorHosted.Client
     

   • Mettez à jour les liens de la feuille de style pour qu’ils pointent vers les feuilles de style du projet WebAssembly. Dans l’exemple suivant, l’espace de noms du projet client est BlazorHosted.Client. L’espace réservé {APP NAMESPACE} représente l’espace de noms de l’application donatrice qui a fourni le fichier _Host.cshtml. Mettez à jour l’assistance des balises de composant (balise <component>) pour le composant HeadOutlet pour le prérendu du composant.

     Supprimer :

     - <link href="css/site.css" rel="stylesheet" />
     - <link href="{APP NAMESPACE}.styles.css" rel="stylesheet" />
     - <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
     

     Ajouter :

     <link href="css/app.css" rel="stylesheet" />
     <link href="BlazorHosted.Client.styles.css" rel="stylesheet" />
     <component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />
     

     Remarque

     Garder l’élément <link> qui demande la feuille de style Bootstrap (css/bootstrap/bootstrap.min.css) en place.

   • Mettez à jour la source de script Blazor pour utiliser le script Blazor WebAssembly côté client :

     Supprimer :

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

     Ajouter :

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

   • Mettez à jour le render-mode de l’assistance des balises de composant pour donner le prérendu la racine du composant App avec WebAssemblyPrerendered :

     Supprimer :

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

     Ajouter :

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

     Important

     Le prérendu (« prerendering » en anglais) n’est pas pris en charge pour les points de terminaison d’authentification (segment de chemin /authentication/). Pour plus d’informations, consultez Autres scénarios de sécurité ASP.NET Core Blazor WebAssembly.

5. Dans le fichier Program.cs du projet Server, remplacez le point de terminaison de secours du fichier index.html par la page _Host.cshtml :

   Supprimer :

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

   Ajouter :

   app.MapFallbackToPage("/_Host");
   

6. Si les projets Client et Server utilisent un ou plusieurs services courants pendant le prérendu, factorisez les inscriptions de service dans une méthode qui peut être appelée à partir des deux projets. Pour plus d’informations, consultez Injection de dépendances Blazor ASP.NET Core.

7. Exécutez le projet Server. L’application Blazor WebAssembly hébergée est prérendue par le projet Server pour les clients.

Configuration pour l’incorporation des composants Razor dans des pages et des vues

Les sections et exemples suivants pour l’incorporation de composants Razor de l’application ClientBlazor WebAssembly dans des pages et des vues de l’application serveur nécessitent une configuration supplémentaire.

Le projet Server doit contenir les fichiers et dossiers suivants.

Razor Pages :

• Pages/Shared/_Layout.cshtml
• Pages/Shared/_Layout.cshtml.css
• Pages/_ViewImports.cshtml
• Pages/_ViewStart.cshtml

MVC :

• Views/Shared/_Layout.cshtml
• Views/Shared/_Layout.cshtml.css
• Views/_ViewImports.cshtml
• Views/_ViewStart.cshtml

Les fichiers précédents peuvent être obtenus par la génération d’une application à partir des modèles de projet ASP.NET Core à l’aide des éléments suivants :

• Les nouveaux outils de création de projet de Visual Studio.
• L’ouverture d’un interpréteur de commandes et l’exécution de dotnet new webapp -o {PROJECT NAME} (Razor Pages) ou de dotnet new mvc -o {PROJECT NAME} (MVC). L’option -o|--output ayant une valeur pour l’espace réservé {PROJECT NAME} fournit un nom pour l’application et lui crée un dossier.

Mettez à jour les espaces de noms dans le fichier _ViewImports.cshtml importé pour les faire correspondre aux espaces de noms utilisés par le projet Server destinataire des fichiers.

Pages/_ViewImports.cshtml (Razor Pages) :

@using BlazorHosted.Server
@namespace BlazorHosted.Server.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Views/_ViewImports.cshtml (MVC) :

@using BlazorHosted.Server
@using BlazorHosted.Server.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Mettez à jour le fichier de disposition importé, qui est Pages/Shared/_Layout.cshtml pour Razor Pages ou Views/Shared/_Layout.cshtml pour MVC.

Commencez par supprimer le titre et la feuille de style du projet donateur, qui est RPDonor.styles.css dans l’exemple suivant. L’espace réservé {PROJECT NAME} représente le nom de l’application du projet donateur.

- <title>@ViewData["Title"] - {PROJECT NAME}</title>
- <link rel="stylesheet" href="~/RPDonor.styles.css" asp-append-version="true" />

Incluez les styles du projet Client dans le fichier de disposition. Dans l’exemple suivant, l’espace de noms du projet Client est BlazorHosted.Client. L’élément <title> peut être mis à jour simultanément.

Placez les lignes suivantes dans le contenu <head> du fichier de disposition :

<title>@ViewData["Title"] - BlazorHosted</title>
<link href="css/app.css" rel="stylesheet" />
<link rel="stylesheet" href="BlazorHosted.Client.styles.css" asp-append-version="true" />
<component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />

La disposition importée contient deux liens de navigation Home (Index page) et Privacy. Pour que les liens Home pointent vers l’application Blazor WebAssembly hébergée, modifiez les liens hypertexte :

- <a class="navbar-brand" asp-area="" asp-page="/Index">{PROJECT NAME}</a>
+ <a class="navbar-brand" href="/">BlazorHosted</a>

- <a class="nav-link text-dark" asp-area="" asp-page="/Index">Home</a>
+ <a class="nav-link text-dark" href="/">Home</a>

Dans un fichier de disposition MVC :

- <a class="navbar-brand" asp-area="" asp-controller="Home" 
-     asp-action="Index">{PROJECT NAME}</a>
+ <a class="navbar-brand" href="/">BlazorHosted</a>

- <a class="nav-link text-dark" asp-area="" asp-controller="Home" 
-     asp-action="Index">Home</a>
+ <a class="nav-link text-dark" href="/">Home</a>

Mettez à jour le nom de l’application de l’élément <footer>. L’exemple suivant utilise le nom d’application BlazorHosted :

- &copy; {DATE} - {DONOR NAME} - <a asp-area="" asp-page="/Privacy">Privacy</a>
+ &copy; {DATE} - BlazorHosted - <a asp-area="" asp-page="/Privacy">Privacy</a>

Dans l’exemple précédent, l’espace réservé {DATE} représente la date de copyright dans une application générée à partir du modèle de projet Razor Pages ou MVC.

Pour que le lien Privacy dirige vers une page privacy (Razor Pages), ajoutez une page privacy au projet Server.

Pages/Privacy.cshtml dans le projet Server :

@page
@model PrivacyModel
@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p>Use this page to detail your site's privacy policy.</p>

Pour une vue privacy basée sur MVC, créez une vue privacy dans le projet Server.

View/Home/Privacy.cshtml dans le projet Server :

@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p>Use this page to detail your site's privacy policy.</p>

Dans le contrôleur Home de l’application MVC, retournez la vue.

Ajoutez le code suivant à Controllers/HomeController.cs :

public IActionResult Privacy()
{
    return View();
}

Si vous importez des fichiers à partir d’une application donatrice, veillez à mettre à jour tous les espaces de noms des fichiers pour les faire correspondre à ceux du projet Server (par exemple, BlazorHosted.Server).

Importez des ressources statiques dans le projet Server à partir du dossier wwwroot du projet donateur :

• Dossier et contenus wwwroot/css
• Dossier et contenus wwwroot/js
• Dossier et contenus wwwroot/lib

Si le projet donateur est créé à partir d’un modèle de projet ASP.NET Core et que les fichiers ne sont pas modifiés, vous pouvez copier le dossier wwwroot dans son intégralité depuis le projet donateur dans le projet Server et supprimer le fichier d’icônes favicon.

Warning

Évitez de placer la ressource statique à la fois dans les dossiers Client et Server wwwroot. Si le même fichier est présent dans les deux dossiers, une exception est levée parce que les ressources statiques partagent le même chemin racine web. Par conséquent, hébergez une ressource statique dans l’un des dossiers wwwroot, et non dans les deux.

Après avoir adopté la configuration précédente, incorporez des composants Razor dans des pages ou des vues du projet Server. Utilisez l’aide des sections suivantes de cet article :

• Afficher des composants dans une page ou une vue avec l’outil d’assistance des balises de composant
• Afficher les composants dans une page ou une vue à l’aide d’un sélecteur CSS

Afficher des composants dans une page ou une vue avec l’outil d’assistance des balises de composant

Après avoir configuré la solution, y compris la configuration supplémentaire, l’assistance des balises de composant prend en charge deux modes de rendu pour le rendu d’un composant à partir d’une application Blazor WebAssembly dans une page ou une vue :

• WebAssembly
• WebAssemblyPrerendered

Dans l’exemple Razor Pages suivant, le composant Counter est affiché dans une page. Pour que le composant devienne interactif, le script Blazor WebAssembly est inclus dans la section de rendu de la page. Pour éviter d’utiliser l’espace de noms complet du composant Counter avec l’assistance des balises de composant ({ASSEMBLY NAME}.Pages.Counter), ajoutez une directive @using pour l’espace de noms Pages du projet client. Dans l’exemple suivant, l’espace de noms du projet Client est BlazorHosted.Client.

Dans le projet Server, Pages/RazorPagesCounter1.cshtml :

@page
@using BlazorHosted.Client.Pages

<component type="typeof(Counter)" render-mode="WebAssemblyPrerendered" />

@section Scripts {
    <script src="_framework/blazor.webassembly.js"></script>
}

Exécutez le projet Server. Accédez à la page Razor sur /razorpagescounter1. Le composant Counter prérendu est incorporé dans la page.

RenderMode configure si le composant :

• est prérendu dans la page.
• est rendu en tant que code HTML statique sur la page ou s’il inclut les informations nécessaires pour démarrer une application Blazor à partir de l’agent utilisateur.

Pour plus d’informations sur l’assistant de balise de composant, y compris la transmission des paramètres et la configuration RenderMode, consultez Assistance des balises de composant dans ASP.NET Core.

Un travail supplémentaire peut être nécessaire en fonction des ressources statiques utilisées par les composants et de l’organisation des pages de disposition dans une application. En général, des scripts sont ajoutés à la section de rendu Scripts d’une page ou d’une vie et des feuilles de style sont ajoutées au contenu d’un élément <head> d’une disposition.

Définir du contenu enfant par le biais d’un fragment de rendu

L’assistance des balises de composant ne prend pas en charge la réception d’un délégué RenderFragment pour le contenu enfant (par exemple, param-ChildContent="..."). Nous recommandons la création d’un composant Razor (.razor) qui fait référence au composant que vous souhaitez afficher avec le contenu enfant que vous souhaitez transmettre, puis d’appeler le composant Razor à partir de la page ou de la vue.

Veiller à ce que les composants prérendus de niveau supérieur ne soient pas supprimés lors de la publication

Si une assistance des balises de composant fait directement référence à un composant d’une bibliothèque soumise à la suppression lors de la publication, le composant peut être supprimé pendant la publication car aucune référence n’est faite à celui-ci à partir du code d’application côté client. Par conséquent, le composant n’est pas prérendu, ce qui laisse un emplacement vide dans la sortie. Si cela se produit, demandez au découpage de conserver le composant de bibliothèque en ajoutant un attribut DynamicDependency à n’importe quelle classe de l’application côté client. Pour conserver un composant appelé SomeLibraryComponentToBePreserved, ajoutez ce qui suit à n’importe quel composant :

@using System.Diagnostics.CodeAnalysis
@attribute [DynamicDependency(DynamicallyAccessedMemberTypes.All, 
    typeof(SomeLibraryComponentToBePreserved))]

L’approche précédente n’est généralement pas nécessaire, car dans la plupart des cas, l’application effectue un prérendu de ses composants (ceux qui ne sont pas supprimés), faisant référence à des composants à partir de bibliothèques (qui ne sont par conséquent pas supprimés non plus). Utilisez seulement DynamicDependency explicitement pour le prérendu d’un composant de bibliothèque directement lorsque la bibliothèque est soumise à la découpe.

Afficher les composants dans une page ou une vue à l’aide d’un sélecteur CSS

Après avoir configuré la solution, y compris la configuration supplémentaire, ajoutez des composants racines au projet Client d’une solution Blazor WebAssembly hébergée dans le fichier Program.cs. Dans l’exemple suivant, le composant Counter est déclaré en tant que composant racine avec un sélecteur CSS qui sélectionne l’élément avec le id correspondant à counter-component. Dans l’exemple suivant, l’espace de noms du projet Client est BlazorHosted.Client.

Dans le fichier Program.cs du projet Client, ajoutez l’espace de noms des composants Razor du projet en haut du fichier :

using BlazorHosted.Client.Pages;

Une fois que builder est établi dans Program.cs, ajoutez le composant Counter en tant que composant racine :

builder.RootComponents.Add<Counter>("#counter-component");

Dans l’exemple Razor Pages suivant, le composant Counter est affiché dans une page. Pour que le composant devienne interactif, le script Blazor WebAssembly est inclus dans la section de rendu de la page.

Dans le projet Server, Pages/RazorPagesCounter2.cshtml :

@page

<div id="counter-component">Loading...</div>

@section Scripts {
    <script src="_framework/blazor.webassembly.js"></script>
}

Exécutez le projet Server. Accédez à la page Razor sur /razorpagescounter2. Le composant Counter prérendu est incorporé dans la page.

Un travail supplémentaire peut être nécessaire en fonction des ressources statiques utilisées par les composants et de l’organisation des pages de disposition dans une application. En général, des scripts sont ajoutés à la section de rendu Scripts d’une page ou d’une vie et des feuilles de style sont ajoutées au contenu d’un élément <head> d’une disposition.

Remarque

L’exemple précédent lève un JSException si une application Blazor WebAssembly est prérendue et intégrée à une application Razor Pages ou MVC simultanément avec l’utilisation d’un sélecteur CSS. La navigation vers l’un des composants Razor du projet Client ou la navigation vers une page ou une vue de Server avec un composant incorporé lève une ou plusieurs JSException.

Il s’agit d’un comportement normal, car le prérendu et l’intégration d’une application Blazor WebAssembly avec des composants Razor routables sont incompatibles avec l’utilisation des sélecteurs CSS.

Si vous avez travaillé avec les exemples des sections précédentes et que vous souhaitez simplement voir le sélecteur CSS fonctionner dans votre exemple d’application, mettez en commentaire la spécification du composant racine App du Client fichier du projet Program.cs :

- builder.RootComponents.Add<App>("#app");
+ //builder.RootComponents.Add<App>("#app");

Accédez à la page ou à la vue comportant le composant Razor intégré qui utilise un sélecteur CSS (par exemple, le /razorpagescounter2 de l’exemple précédent). La page ou la vue se charge avec le composant incorporé et celui-ci fonctionne comme prévu.

Les composants Razor peuvent être intégrés dans les applications Razor Pages et MVC. Lorsque la page ou la vue est affichée, les composants peuvent être prérendus en même temps.

Le prérendu peut améliorer l’optimisation du référencement d’un site auprès d’un moteur de recherche (SEO) en affichant le contenu de la réponse HTTP initiale utilisée par les moteurs de recherche peuvent utiliser pour calculer l’ordre de priorité de la page.

Après avoir configuré le projet, suivez l’aide dans les sections suivantes en fonction des exigences du projet :

• Pour les composants directement routables à partir des requêtes utilisateur. Suivez cette aide lorsque les visiteurs doivent être en mesure d’envoyer une requête HTTP dans leur navigateur pour un composant avec une directive @page.
  • Utiliser des composants routables dans une application Razor Pages
  • Utiliser des composants routables dans une application MVC
• Pour les composants qui ne sont pas routables directement à partir des requêtes utilisateur, consultez la section Afficher des composants à partir d’une page ou d’une vue. Suivez cette aide quand l’application intègre des composants dans les pages et vues existantes à l’aide de l’assistance des balises de composant.

Configuration

Utilisez l’aide suivante pour intégrer des composants Razor dans des pages et des vues d’une application Razor Pages ou MVC existante.

1. Ajoutez un fichier d’importation au dossier racine du projet avec le contenu suivant. Remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms du projet.

   _Imports.razor:

   @using System.Net.Http
   @using Microsoft.AspNetCore.Authorization
   @using Microsoft.AspNetCore.Components.Authorization
   @using Microsoft.AspNetCore.Components.Forms
   @using Microsoft.AspNetCore.Components.Routing
   @using Microsoft.AspNetCore.Components.Web
   @using Microsoft.AspNetCore.Components.Web.Virtualization
   @using Microsoft.JSInterop
   @using {APP NAMESPACE}
   

2. Dans le fichier de disposition du projet (Pages/Shared/_Layout.cshtml dans les applications Razor Pages ou Views/Shared/_Layout.cshtml dans les applications MVC) :

   • Ajoutez la balise <base> et l’assistance des balises de composant HeadOutlet suivantes à l’élément <head> :

     <base href="~/" />
     <component type="typeof(Microsoft.AspNetCore.Components.Web.HeadOutlet)" 
         render-mode="ServerPrerendered" />
     

     La valeur href (le chemin d’accès de base de l’application) de l’exemple précédent suppose que l’application réside dans le chemin d’accès de l’URL racine (/). Si l’application est une sous-application, suivez l’aide de la section Chemin d’accès de base de l’application de l’article Héberger et déployer ASP.NET CoreBlazor.

     Le composant HeadOutlet est utilisé pour afficher le contenu de l’en-tête (<head>) pour les titres de page (composant PageTitle) et d’autres éléments de l’en-tête (composant HeadContent) définis par les composants Razor. Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core Blazor.

   • Ajoutez une balise <script> au script blazor.server.js immédiatement avant la section de rendu Scripts (@await RenderSectionAsync(...)) :

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

     L’infrastructure ajoute le script blazor.server.js à l’application. Il n’est pas nécessaire d’ajouter manuellement un fichier de script blazor.server.js à l’application.

   Remarque

   En général, la disposition se charge via un fichier _ViewStart.cshtml.

3. Enregistrez les services Blazor Server dans le Program.cs où les services sont enregistrés :

   builder.Services.AddServerSideBlazor();
   

4. Ajoutez le point de terminaison du hub Blazor aux points de terminaison de Program.cs où les itinéraires sont mappés. Placez la ligne suivante après l’appel à MapRazorPages (Razor Pages) ou MapControllerRoute (MVC) :

   app.MapBlazorHub();
   

5. Intégrez des composants à n’importe quelle page ou vue. Par exemple, ajoutez un composant Counter au dossier du projet Shared.

   Pages/Shared/Counter.razor (Razor Pages) ou Views/Shared/Counter.razor (MVC) :

   <h1>Counter</h1>
   
   <p>Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

   Razor Pages :

   Dans la page Index du projet d’une application Razor Pages, ajoutez l’espace de noms du composant Counter et incorporez le composant dans la page. Quand la page Index se charge, le composant Counter est prérendu dans la page. Dans l’exemple suivant, remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms du projet.

   Pages/Index.cshtml:

   @page
   @using {APP NAMESPACE}.Pages.Shared
   @model IndexModel
   @{
       ViewData["Title"] = "Home page";
   }
   
   <component type="typeof(Counter)" render-mode="ServerPrerendered" />
   

   MVC :

   Dans la vue Index du projet d’une application MVC, ajoutez l’espace de noms du composant Counter et incorporez le composant dans la vue. Quand la vue Index se charge, le composant Counter est prérendu dans la page. Dans l’exemple suivant, remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms du projet.

   Views/Home/Index.cshtml:

   @using {APP NAMESPACE}.Views.Shared
   @{
       ViewData["Title"] = "Home Page";
   }
   
   <component type="typeof(Counter)" render-mode="ServerPrerendered" />
   

Pour plus d’informations, consultez la section Afficher des composants d’une page ou d’une vue.

Utiliser des composants routables dans une application Razor Pages

Cette section concerne l’ajout de composants directement routables à partir des requêtes utilisateur.

Pour prendre en charge les composants Razor routables dans les applications Razor Pages :

1. Suivez l’aide de la section Configuration.

2. Ajoutez un composant App à la racine du projet avec le contenu suivant.

   App.razor:

   @using Microsoft.AspNetCore.Components.Routing
   
   <Router AppAssembly="typeof(App).Assembly">
       <Found Context="routeData">
           <RouteView RouteData="routeData" />
       </Found>
       <NotFound>
           <PageTitle>Not found</PageTitle>
           <p role="alert">Sorry, there's nothing at this address.</p>
       </NotFound>
   </Router>
   

3. Ajoutez une page _Host au projet avec le contenu suivant. Remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms de l’application.

   Pages/_Host.cshtml:

   @page
   @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
   
   <component type="typeof(App)" render-mode="ServerPrerendered" />
   

   Remarque

   L’exemple précédent suppose que le composant HeadOutlet et le script Blazor (_framework/blazor.server.js) sont rendus par la disposition de l’application. Pour plus d’informations, consultez la section Configuration.

   RenderMode configure si le composant App :

   • est prérendu dans la page.
   • est rendu en tant que code HTML statique sur la page ou s’il inclut les informations nécessaires pour démarrer une application Blazor à partir de l’agent utilisateur.

   Pour plus d’informations sur l’assistant de balise de composant, y compris la transmission des paramètres et la configuration RenderMode, consultez Assistance des balises de composant dans ASP.NET Core.

4. Dans les points de terminaison Program.cs, ajoutez un itinéraire de faible priorité pour la page _Host comme dernier point de terminaison :

   app.MapFallbackToPage("/_Host");
   

5. Ajoutez des composants routables au projet. L’exemple suivant est un composant RoutableCounter basé sur le composant Counter des modèles de projet Blazor.

   Pages/RoutableCounter.razor:

   @page "/routable-counter"
   
   <PageTitle>Routable Counter</PageTitle>
   
   <h1>Routable Counter</h1>
   
   <p>Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

6. Exécutez le projet et accédez au composant RoutableCounter routable sur /routable-counter.

Pour plus d’informations sur les espaces de noms, consultez la section Espaces de noms de composant.

Utiliser des composants routables dans une application MVC

Cette section concerne l’ajout de composants directement routables à partir des requêtes utilisateur.

Pour prendre en charge les composants Razor routables dans les applications MVC :

1. Suivez l’aide de la section Configuration.

2. Ajoutez un composant App à la racine du projet avec le contenu suivant.

   App.razor:

   @using Microsoft.AspNetCore.Components.Routing
   
   <Router AppAssembly="typeof(App).Assembly">
       <Found Context="routeData">
           <RouteView RouteData="routeData" />
       </Found>
       <NotFound>
           <PageTitle>Not found</PageTitle>
           <p role="alert">Sorry, there's nothing at this address.</p>
       </NotFound>
   </Router>
   

3. Ajoutez une vue _Host au projet avec le contenu suivant. Remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms de l’application.

   Views/Home/_Host.cshtml:

   @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
   
   <component type="typeof(App)" render-mode="ServerPrerendered" />
   

   Remarque

   L’exemple précédent suppose que le composant HeadOutlet et le script Blazor (_framework/blazor.server.js) sont rendus par la disposition de l’application. Pour plus d’informations, consultez la section Configuration.

   RenderMode configure si le composant App :

   • est prérendu dans la page.
   • est rendu en tant que code HTML statique sur la page ou s’il inclut les informations nécessaires pour démarrer une application Blazor à partir de l’agent utilisateur.

   Pour plus d’informations sur l’assistant de balise de composant, y compris la transmission des paramètres et la configuration RenderMode, consultez Assistance des balises de composant dans ASP.NET Core.

4. Ajoutez une action au contrôleur Home.

   Controllers/HomeController.cs:

   public IActionResult Blazor()
   {
      return View("_Host");
   }
   

5. Dans les points de terminaison Program.cs, ajoutez un itinéraire de faible priorité pour l’action du contrôleur qui retourne la vue _Host :

   app.MapFallbackToController("Blazor", "Home");
   

6. Créez un dossier Pages dans l’application MVC et ajoutez des composants routables. L’exemple suivant est un composant RoutableCounter basé sur le composant Counter des modèles de projet Blazor.

   Pages/RoutableCounter.razor:

   @page "/routable-counter"
   
   <PageTitle>Routable Counter</PageTitle>
   
   <h1>Routable Counter</h1>
   
   <p>Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

7. Exécutez le projet et accédez au composant RoutableCounter routable sur /routable-counter.

Pour plus d’informations sur les espaces de noms, consultez la section Espaces de noms de composant.

Afficher des composants à partir d’une page ou d’une vue

Cette section concerne l’ajout de composants à des pages ou des vues, où les composants ne sont pas routables directement à partir des requêtes utilisateurs.

Pour afficher un composant à partir d’une page ou d’une vue, utilisez l’assistance des balises de composant.

Afficher des composants interactifs avec état

Des composants interactifs avec état peuvent être ajoutés à une page ou à une vue Razor.

Lorsque la page ou la vue s’affiche :

• Le composant est prérendu avec la page ou la vue.
• L’état initial du composant utilisé pour le prérendu est perdu.
• Un nouvel état de composant est créé lorsque la connexion SignalR est établie.

La page Razor suivante affiche un composant Counter :

<h1>Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Pour plus d’informations, consultez assistance des balises de composant dans ASP.NET Core.

Afficher des composants non interactifs

Dans la page Razor suivante, le composant Counter est affiché de manière statique avec une valeur initiale spécifiée à l’aide d’un formulaire. Comme le composant est affiché de manière statique, il n’est pas interactif :

<h1>Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Pour plus d’informations, consultez assistance des balises de composant dans ASP.NET Core.

Espaces de noms de composant

Lors de l’utilisation d’un dossier personnalisé pour contenir les composants Razor du projet, ajoutez l’espace de noms représentant le dossier à la page/vue ou au fichier _ViewImports.cshtml. Dans l’exemple suivant :

• Les composants sont stockés dans le dossier Components du projet.
• L’espace réservé {APP NAMESPACE} est l’espace de noms du projet. Components représente le nom du dossier.

@using {APP NAMESPACE}.Components

Le fichier _ViewImports.cshtml se trouve dans le dossier Pages d’une application Razor Pages ou dans le dossier Views d’une application MVC.

Pour plus d’informations, consultez Composants ASP.NET Core Razor.

Conserver l’état prérendu

Si l’état utilisé durant le prérendu n’est pas conservé, il est perdu et doit être recréé lorsque l’application est entièrement chargée. Si un état est configuré de manière asynchrone, l’interface utilisateur peut scintiller, car l’interface utilisateur prérendue est remplacée par des espaces réservés temporaires avant d’être entièrement affichée.

Pour conserver l’état des composants prérendus, utilisez le Tag Helper Persist Component State (source de référence). Ajoutez la balise du Tag Helper, <persist-component-state />, à la balise fermante </body> de la page _Host dans une application qui affiche au préalable les composants.

Notes

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Dans Pages/_Host.cshtml des applications Blazor qui sont prérendues WebAssembly (WebAssemblyPrerendered) dans une application Blazor WebAssembly hébergée ou ServerPrerendered dans une application Blazor Server :

<body>
    ...

    <persist-component-state />
</body>

Déterminez l’état à conserver à l’aide du service PersistentComponentState. PersistentComponentState.RegisterOnPersisting enregistre un rappel pour conserver l’état du composant avant que l’application ne soit suspendue. L’état est récupéré lorsque l’application reprend.

Dans l’exemple suivant :

• L’espace réservé {TYPE} représente le type de données à conserver (par exemple WeatherForecast[]).
• L’espace réservé {TOKEN} est une chaîne de l’identificateur d’état (par exemple fetchdata).

@implements IDisposable
@inject PersistentComponentState ApplicationState

...

@code {
    private {TYPE} data;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistData);

        if (!ApplicationState.TryTakeFromJson<{TYPE}>(
            "{TOKEN}", out var restored))
        {
            data = await ...;
        }
        else
        {
            data = restored!;
        }
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson("{TOKEN}", data);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

L’exemple suivant est une version mise à jour du composant FetchData dans une application Blazor WebAssembly hébergée basée sur le modèle de projet Blazor. Le composant WeatherForecastPreserveState conserve l’état des prévisions météorologiques pendant le prérendu, puis récupère l’état pour initialiser le composant. L’assistance des balises d’état du composant persistant conserve l’état du composant après tous les appels de composant.

Pages/WeatherForecastPreserveState.razor:

@page "/weather-forecast-preserve-state"
@using BlazorSample.Shared
@implements IDisposable
@inject IWeatherForecastService WeatherForecastService
@inject PersistentComponentState ApplicationState

<PageTitle>Weather Forecast</PageTitle>

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from the server.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[] forecasts = Array.Empty<WeatherForecast>();
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistForecasts);

        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            "fetchdata", out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateOnly.FromDateTime(DateTime.Now));
        }
        else
        {
            forecasts = restored!;
        }
    }

    private Task PersistForecasts()
    {
        ApplicationState.PersistAsJson("fetchdata", forecasts);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

En initialisant des composants avec le même état que celui utilisé durant le prérendu, toutes les étapes d’initialisation coûteuses ne sont exécutées qu’une seule fois. L’interface utilisateur rendue correspond également à l’interface utilisateur prérendue, de sorte qu’aucun scintillement ne se produit dans le navigateur.

L’état préréenderé persistant est transféré au client, où il est utilisé pour restaurer l’état du composant. ASP.NET Core Data Protection garantit que les données sont transférées en toute sécurité dans les Blazor Server applications. Pour la préversion dans une application hébergée Blazor WebAssembly , les données sont exposées au navigateur et ne doivent pas contenir d’informations sensibles et privées.

Ressources Blazor WebAssembly supplémentaires

• Gestion de l’état : gérer le prérendu
• Prise en charge du prérendu avec chargement différé de l’assembly
• Sujets de cycle de vie des composants Razor qui se rapportent au prérendu
  • Initialisation des composants (OnInitialized{Async})
  • Après le rendu de composant (OnAfterRender{Async})
  • Reconnexion avec état après le prérendu : bien que le contenu de la section se concentre sur Blazor Server et la reconnexion SignalR avec état, le scénario de prérendu dans les applications Blazor WebAssembly hébergées (WebAssemblyPrerendered) implique des conditions et approches similaires pour empêcher l’exécution du code du développeur deux fois. Pour conserver l’état pendant l’exécution du code d’initialisation lors du prérendu, consultez Conserver l’état prérendu.
  • Prérendu avec l’interopérabilité JavaScript
• Sujets d’authentification et d’autorisation relatifs au prérendu
  • Aspects généraux
  • Prérendu avec authentification dans les applications hébergées Blazor WebAssembly
• Héberger et déployer : Blazor WebAssembly
• Gérer les erreurs : prérendu
• OnNavigateAsync est exécuté deux fois lors du prérendu : gérer les événements de navigation asynchrone avec OnNavigateAsync

Taille d’état prérendu et limite de taille du message SignalR

Une grande taille d’état prédéfini peut dépasser la limite de taille du message du circuit SignalR, ce qui entraîne les résultats suivants :

• Le circuit SignalR ne parvient pas à s’initialiser avec une erreur sur le client : Circuit host not initialized.
• L’interface utilisateur de reconnexion sur le client s’affiche lors de l’échec du circuit. La récupération n’est pas possible.

Pour résoudre le problème, utilisez l’une des approches suivantes :

• Réduisez la quantité de données que vous placez dans l’état prérendu.
• Augmentez la limite de taille des messages SignalR. AVERTISSEMENT : l’augmentation de la limite peut augmenter le risque d’attaques par déni de service (DoS).

Ressources Blazor Server supplémentaires

• Gestion de l’état : gérer le prérendu
• Sujets de cycle de vie des composants Razor qui se rapportent au prérendu
  • Initialisation des composants (OnInitialized{Async})
  • Après le rendu de composant (OnAfterRender{Async})
  • Reconnexion avec état après le prérendu
  • Prérendu avec l’interopérabilité JavaScript
• Authentification et autorisation : aspects généraux
• Gérer les erreurs : prérendu
• Héberger et déployer : Blazor Server
• Atténuation des menaces : scripting inter-sites (XSS)
• OnNavigateAsync est exécuté deux fois lors du prérendu : gérer les événements de navigation asynchrone avec OnNavigateAsync