Partager via

Modes de rendu ASP.NET Core Blazor

  • Article

Cet article explique le contrôle du rendu des composants Razor dans les Blazor Web App, au moment de la compilation ou du runtime.

Cette aide ne s’applique pas aux applications Blazor WebAssembly autonomes. Les applications Blazor WebAssembly s’affichent sur le client seulement via un runtime WebAssembly côté client et n’ont pas de concept de mode d’affichage. Si un mode d’affichage est appliqué à un composant dans une application Blazor WebAssembly, la désignation du mode d’affichage n’a pas d’influence sur l’affichage du composant.

Modes de rendu

Chaque composant d’une Blazor Web App adopte un mode de rendu pour déterminer le modèle d’hébergement qu’il utilise, l’endroit où il est affiché et s’il est interactif ou non.

Le tableau suivant présente les modes de rendu disponibles pour le rendu des composants Razor dans une Blazor Web App. Pour appliquer un mode de rendu à un composant, utilisez la directive @rendermode sur l'instance du composant ou sur la définition du composant. Plus loin dans cet article, des exemples sont présentés pour chaque scénario de mode de rendu.

Nom Description Emplacement du rendu Interactive
Serveur statique Rendu statique côté serveur (SSR statique) Serveur
Serveur interactif Rendu côté serveur interactif (SSR interactif) à l’aide de Blazor Server. Serveur
WebAssembly interactif Rendu côté client (CSR) à l’aide de Blazor WebAssembly†. Client
Voiture interactive SSR interactif à l’aide de Blazor Server dans un premier temps, puis CSR lors des visites ultérieures après le téléchargement de l’offre groupée Blazor. Serveur, puis client

† Le rendu côté client (CSR) est supposé être interactif. Le « rendu interactif côté client » et « CSR interactif » ne sont pas utilisés par le secteur ou dans la documentation Blazor.

Le pré-rendu est activé par défaut pour les composants interactifs. Des conseils sur le contrôle du pré-rendu sont fournis plus loin dans cet article. Pour connaître la terminologie générale du secteur sur les concepts de rendu du client et du serveur, consultez Notions de base d’ASP.NET Blazor.

Les exemples suivants illustrent la définition du mode de rendu du composant avec quelques fonctionnalités de composant Razor de base.

Pour tester les comportements du mode de rendu localement, vous pouvez placer les composants suivants dans une application créée à partir du modèle de projet de l’Blazor Web App. Lorsque vous créez l’application, sélectionnez les options dans les menus déroulants (Visual Studio) ou appliquez les options CLI (interface CLI .NET) pour activer l’interactivité côté serveur et côté client. Pour obtenir des conseils sur la création d’une Blazor Web App, consultez Outils pour ASP.NET Core Blazor.

Activez la prise en charge des modes de rendu interactifs

Une Blazor Web App doit être configurée pour prendre en charge les modes de rendu interactifs. Les extensions suivantes sont automatiquement appliquées aux applications créées à partir du modèle de projet d’Blazor Web App lors de la création de l’application. Les composants individuels doivent toujours déclarer leur mode de rendu conformément à la section Modes de rendu après la configuration des services et points de terminaison des composants dans le fichier Program de l’application.

Les services pour les composants Razor sont ajoutés en appelant AddRazorComponents.

Extensions du générateur de composants :

MapRazorComponents découvre les composants disponibles et spécifie le composant racine de l’application (le premier composant chargé), qui est par défaut le composant App (App.razor).

Extensions du générateur de conventions de point de terminaison :

Remarque

Pour obtenir des indications sur le placement de l’API dans les exemples suivants, examinez le fichier Program d’une application générée à partir du modèle de projet Blazor Web App. Pour obtenir des conseils sur la création d’une Blazor Web App, consultez Outils pour ASP.NET Core Blazor.

Exemple 1 : l’API de fichier Program suivante ajoute des services et une configuration pour activer SSR interactif :

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

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

Exemple 2 : l’API de fichier Program suivante ajoute des services et une configuration pour activer le mode de rendu WebAssembly interactif :

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

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

Exemple 3 : l’API de fichier Program suivante ajoute des services et une configuration pour activer les modes de rendu Serveur interactif, WebAssembly interactif et Auto interactif :

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

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

Blazor utilise le modèle d’hébergement Blazor WebAssembly pour télécharger et exécuter des composants qui utilisent le mode de rendu WebAssembly interactif. Un projet client distinct est requis pour configurer l’hébergement Blazor WebAssembly de ces composants. Le projet client contient le code de démarrage de l’hôte Blazor WebAssembly et configure le runtime .NET pour qu’il s’exécute dans un navigateur. Le modèle Blazor Web App ajoute ce projet client pour vous lorsque vous sélectionnez l’option permettant d’activer l’interactivité WebAssembly. Tous les composants utilisant le mode de rendu WebAssembly doivent être générés à partir du projet client. Ils sont donc inclus dans l’ensemble d’applications téléchargé.

Appliquez un mode de rendu à une instance de composant

Pour appliquer un mode de rendu à une instance de composant, utilisez l’attribut de directive @rendermodeRazor où le composant est utilisé.

Dans l’exemple suivant, le rendu côté serveur interactif (SSR interactif) est appliqué à l’instance de composant Dialog :

<Dialog @rendermode="InteractiveServer" />

Remarque

Les modèles Blazor incluent une directive statique using pour RenderMode dans le fichier _Imports de l’application (Components/_Imports.razor) pour une syntaxe de @rendermode plus courte :

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

Sans la directive précédente, les composants doivent spécifier la classe statique RenderMode dans la syntaxe @rendermode :

<Dialog @rendermode="RenderMode.InteractiveServer" />

Vous pouvez référencer des instances en mode de rendu personnalisé instanciées directement avec une configuration personnalisée. Pour plus d’informations, consultez la section Modes de rendu abrégé personnalisés plus loin dans cet article.

Appliquez un mode de rendu à une définition de composant

Pour spécifier le mode de rendu d’un composant dans le cadre de sa définition, utilisez la directive @rendermodeRazor et l’attribut de mode de rendu correspondant.

@page "..."
@rendermode InteractiveServer

L’application d’un mode de rendu à une définition de composant est couramment utilisée lors de l’application d’un mode de rendu à une page spécifique. Les pages routables utilisent le même mode de rendu que le composant Router qui a effectué le rendu de la page.

Techniquement, @rendermode est à la fois une Razordirective et un Razorattribut de directive. La sémantique est similaire, mais il existe des différences. La directive @rendermode se trouve sur la définition du composant, donc l'instance du mode de rendu référencée doit être statique. L'attribut directive @rendermode peut prendre n'importe quelle instance de mode de rendu.

Remarque

Les auteurs de composants doivent éviter le couplage de l’implémentation d’un composant à un mode de rendu spécifique. Au lieu de cela, les auteurs de composants doivent généralement concevoir des composants permettant de prendre en charge tout mode de rendu ou modèle d’hébergement. L’implémentation d’un composant doit éviter les hypothèses sur l’emplacement où il est en cours d’exécution (serveur ou client) et doit se dégrader correctement lorsqu’il est affiché de manière statique. La spécification du mode de rendu dans la définition du composant peut être nécessaire si le composant n’est pas instancié directement (par exemple, avec un composant de page routable) ou pour spécifier un mode de rendu pour toutes les instances de composant.

Appliquer un mode de rendu à l’ensemble de l’application

Pour définir le mode de rendu pour l’ensemble de l’application, indiquez le mode de rendu au composant interactif de niveau le plus élevé dans la hiérarchie des composants de l’application qui n’est pas un composant racine.

Remarque

Rendre un composant racine interactif, comme le composant App, n’est pas pris en charge. Par conséquent, le mode de rendu de l’application entière ne peut pas être défini directement par le composant App.

Pour les applications basées sur le modèle de projet Blazor Web App, un mode de rendu affecté à l’ensemble de l’application est généralement spécifié, où le composant Routes est utilisé dans le composant App (Components/App.razor) :

<Routes @rendermode="InteractiveServer" />

Le composant Router propage son mode de rendu aux pages qu’il achemine.

Vous devez également définir le même mode de rendu interactif sur le composant HeadOutlet, qui se trouve également dans le composant App d’une Blazor Web App générée à partir du modèle de projet :

<HeadOutlet @rendermode="InteractiveServer" />

Pour les applications qui adoptent un mode de rendu côté client interactif (WebAssembly ou Auto) et qui activent le mode de rendu pour l’ensemble de l’application via le composant Routes :

  • Placez ou déplacez les fichiers de mise en page et de navigation du dossier Components/Layout de l’application serveur dans le dossier .Client du projet Layout. S’il n’existe pas déjà, créez un dossier Layout dans le projet .Client.
  • Placez ou déplacez les composants du dossier Components/Pages de l’application serveur dans le dossier .Client du projet Pages. S’il n’existe pas déjà, créez un dossier Pages dans le projet .Client.
  • Placez ou déplacez les composants Routes du dossier Components de l’application serveur dans le dossier racine du projet .Client.

Pour activer l’interactivité globale lors de la création d’une Blazor Web App :

  • Visual Studio : définissez la liste déroulante Emplacement d'interactivité sur Global.
  • CLI .NET : utilisez l’option -ai|--all-interactive.

Pour plus d’informations, consultez Outils pour ASP.NET Core Blazor.

Appliquer un mode de rendu programmatiquement

Les propriétés et les champs peuvent affecter un mode de rendu.

La deuxième approche décrite dans cette section, la définition du mode de rendu par instance de composant est particulièrement utile lorsque la spécification de votre application appelle un ou plusieurs composants pour adopter la SSR statique dans une application interactive globale. Ce scénario est abordé dans la section Pages Static SSR dans une application interactive globale plus loin dans cet article.

Définir le mode de rendu par définition de composant

Une définition de composant peut définir un mode de rendu via un champ privé :

@rendermode pageRenderMode

...

@code {
    private static IComponentRenderMode pageRenderMode = InteractiveServer;
}

Définir le mode de rendu par instance de composant

L’exemple suivant applique le rendu interactif côté serveur (SSR interactif) à tout requête.

<Routes @rendermode="PageRenderMode" />

...

@code {
    private IComponentRenderMode? PageRenderMode => InteractiveServer;
}

Des informations supplémentaires sur la propagation du mode de rendu sont fournies dans la section Propagation du mode de rendu plus loin dans cet article. La section Pages Static SSR dans une application interactive globale montrent comment utiliser l’approche précédente pour adopter la SSR statique dans une application interactive globale.

Détecter l’emplacement de rendu, l’interactivité et le mode de rendu affecté au moment de l’exécution

Les propriétés ComponentBase.RendererInfo et ComponentBase.AssignedRenderMode permettent à l’application de détecter des informations sur l’emplacement, l’interactivité et le mode de rendu affecté d’un composant :

  • RendererInfo.Name retourne l’emplacement d’exécution du composant :
    • Static : sur le serveur (SSR) et ne peut pas communiquer.
    • Server : sur le serveur (SSR) et peut communiquer après un prérendu.
    • WebAssembly : sur le client (CSR) et peut communiquer après un prérendu.
    • WebView : sur l’appareil natif et peut communiquer après un prérendu.
  • RendererInfo.IsInteractive indique si le composant prend en charge l’interactivité au moment du rendu. La valeur est true lors d’un rendu de manière interactive ou false lors d’un prérendu ou pour un SSR statique (Platform.Name en Static).
  • ComponentBase.AssignedRenderMode expose le mode de rendu affecté du composant :
    • InteractiveServer pour Serveur interactif.
    • InteractiveAuto pour Auto interactif.
    • InteractiveWebAssembly pour WebAssembly interactif.

Les composants utilisent ces propriétés pour rendre du contenu en fonction de leur emplacement ou état d’interactivité. Par exemple, un formulaire peut être désactivé pendant le prérendu et activé lorsque le composant devient interactif :

<EditForm Model="Movie" ...>
    <fieldset disabled="@disabled">

        ...

        <button type="submit" >Save</button>
    </fieldset>
</EditForm>

@code {
    private bool disabled = true;

    [SupplyParameterFromForm]
    private Movie? Movie { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Movie ??= await ...;

        if (RendererInfo.IsInteractive)
        {
            disabled = false;
        }
    }
}

L’exemple suivant illustre comment rendre un balisage pour prendre en charge la réalisation d’une action HTML régulière si le composant est statiquement rendu :

@if (AssignedRenderMode is null)
{
    // The render mode is Static Server
    <form action="/movies">
        <input type="text" name="titleFilter" />
        <input type="submit" value="Search" />
    </form>
}
else
{
    // The render mode is Interactive Server, WebAssembly, or Auto
    <input @bind="titleFilter" />
    <button @onclick="FilterMovies">Search</button>
}

Dans l’exemple précédent :

  • Lorsque la valeur de AssignedRenderMode est null, le composant adopte un SSR statique. La gestion d’événements Blazor n’est pas fonctionnelle dans un navigateur avec un SSR statique. Le composant envoie donc un formulaire (requête GET) avec une chaîne de requête titleFilter définie sur la valeur <input> de l’utilisateur. Le composant Movie (/movie) peut lire la chaîne de requête et traiter la valeur de titleFilter pour rendre le composant avec les résultats filtrés.
  • Sinon, le mode de rendu correspondant à tout InteractiveServer, InteractiveWebAssembly ou InteractiveAuto. Le composant est capable d’utiliser un délégué de gestionnaire d’événements (FilterMovies) et la valeur liée à l’élément <input> (titleFilter) pour filtrer des films de manière interactive sur la connexion SignalR en arrière-plan.

Exemples de documentation Blazor pour les Blazor Web App

Lors de l’utilisation d’une Blazor Web App, la plupart des composants de l’exemple de documentation Blazornécessitent une interactivité pour fonctionner et démontrer les concepts couverts par les articles. Lorsque vous testez un composant d’exemple fourni par un article, assurez-vous que l’application adopte une interactivité globale ou que le composant adopte un mode de rendu interactif.

Prérendu

Le prérendu est le processus de rendu initial du contenu d’une page sur le serveur sans activation des gestionnaires d’événements pour les contrôles rendus. Le serveur génère l’interface utilisateur HTML de la page dès que possible en réponse à la demande initiale, ce qui rend l’application plus réactive pour les utilisateurs. Le prérendu peut aussi améliorer l’optimisation du référencement d’un site auprès d’un moteur de recherche (SEO) en rendant le contenu de la réponse HTTP initiale qui est utilisée par les moteurs de recherche pour calculer le rang de la page.

Le pré-rendu est activé par défaut pour les composants interactifs.

La navigation interne pour le routage interactif n’implique pas de demander le nouveau contenu de la page auprès du serveur. Par conséquent, un prérendu n’est pas effectué pour les demandes de pages internes, notamment pour la navigation améliorée. Pour en savoir plus, consultez Routage statique contre routage interactif, Routage interactif et prérendu et Navigation et gestion des formulaires améliorées.

La désactivation du prérendu à l’aide des techniques suivantes ne prend effet que pour les modes de rendu de premier niveau. Si un composant parent spécifie un mode de rendu, les paramètres de prérendu de ses enfants sont ignorés. Ce comportement est en cours d’examen en vue de modifications éventuelles avec la mise en production de .NET 10 en novembre 2025.

Pour désactiver le prérendu pour une instance de composant, transmettez l'indicateur prerender avec une valeur de false au mode de rendu :

  • <... @rendermode="new InteractiveServerRenderMode(prerender: false)" />
  • <... @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />
  • <... @rendermode="new InteractiveAutoRenderMode(prerender: false)" />

Pour désactiver le prérendu dans une définition de composant :

  • @rendermode @(new InteractiveServerRenderMode(prerender: false))
  • @rendermode @(new InteractiveWebAssemblyRenderMode(prerender: false))
  • @rendermode @(new InteractiveAutoRenderMode(prerender: false))

Pour désactiver le prérendu pour l’ensemble de l’application, indiquez le mode de rendu au composant interactif de niveau le plus élevé dans la hiérarchie des composants de l’application qui n’est pas un composant racine.

Pour les applications basées sur le modèle de projet d’Blazor Web App, un mode de rendu affecté à l’ensemble de l’application est spécifié, où le composant Routes est utilisé dans le composant App (Components/App.razor). L’exemple suivant montre comment définir le mode de rendu de l’application sur Interactive Server avec désactivation du prérendu :

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

Désactivez également le prérendu pour le composant HeadOutlet du composant App :

<HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: false)" />

Le fait de rendre un composant racine, tel que le composant App, interactif avec la directive @rendermode en haut du fichier de définition du composant racine (.razor) n’est pas pris en charge. Par conséquent, le prérendu ne peut pas être désactivé directement par le composant App.

Rendu statique côté serveur (SSR statique)

Les composants utilisent le rendu côté serveur statique (SSR statique). Le composant s’affiche dans le flux de réponses et l’interactivité n’est pas activé.

Dans l’exemple suivant, il n’existe aucune désignation pour le mode de rendu du composant, donc le composant hérite du mode de rendu de son parent. Étant donné qu’aucun composant ancêtre ne spécifie un mode de rendu, le composant suivant est rendu de façon statique sur le serveur. Le bouton n’est pas interactif et n’appelle pas la méthode UpdateMessage lorsqu’il est sélectionné. La valeur de message ne change pas et le composant n’est pas affiché à nouveau en réponse aux événements d’interface utilisateur.

RenderMode1.razor:

@page "/render-mode-1"

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Si vous utilisez le composant précédent localement dans une Blazor Web App, placez le composant dans le dossier Components/Pages du projet serveur. Le projet serveur est le projet de la solution avec un nom qui ne se termine pas par .Client. Lorsque l’application est en cours d’exécution, accédez à /render-mode-1 dans la barre d’adresse du navigateur.

Au cours du rendu côté serveur statique, les demandes de page de composants Razor sont prises en charge par le traitement des demandes de pipeline de middleware ASP.NET Core côté serveur pour le routage et l’autorisation. Les fonctionnalités Blazor dédiées pour le routage et l’autorisation ne sont pas opérationnelles, car les composants Razor ne sont pas rendus pendant le traitement des demandes côté serveur. Les fonctionnalités de routeur Blazor du composant Routes qui ne sont pas disponibles pendant le rendu côté client statique incluent l’affichage :

Si l’application présente une interactivité au niveau racine, le traitement des demandes ASP.NET Core côté serveur n’est pas impliqué après le rendu côté serveur statique initial, ce qui signifie que les fonctionnalités Blazor précédentes fonctionnent normalement.

La navigation améliorée avec SSR statique nécessite une attention particulière lors du chargement de JavaScript. Pour plus d’informations, consultez JavaScript Blazor ASP.NET Core avec rendu côté serveur statique (SSR statique).

Rendu côté serveur interactif (SSR interactif)

Le rendu côté serveur interactif (SSR interactif) affiche le composant de manière interactive à partir du serveur en utilisant Blazor Server. Les interactions avec l’utilisateur sont gérées via une connexion en temps réel avec le navigateur. La connexion de circuit est établie lorsque le composant Serveur est affiché.

Dans l’exemple suivant, le mode de rendu est défini sur SSR interactif en ajoutant @rendermode InteractiveServer à la définition du composant. Le bouton appelle la méthode UpdateMessage lorsqu’il est sélectionné. La valeur message est modifiée et le composant est affiché à nouveau pour mettre à jour le message dans l’interface utilisateur.

RenderMode2.razor:

@page "/render-mode-2"
@rendermode InteractiveServer

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Si vous utilisez le composant précédent dans un Blazor Web App, placez le composant dans le dossier du projet de Components/Pages serveur. Le projet serveur est le projet de la solution avec un nom qui ne se termine pas par .Client. Lorsque l’application est en cours d’exécution, accédez à /render-mode-2 dans la barre d’adresse du navigateur.

Rendu côté client (CSR)

Le rendu côté client (CSR) affiche le composant de manière interactive sur le client en utilisant Blazor WebAssembly. Le runtime .NET et l’ensemble d'applications sont téléchargés et mis en cache lorsque le composant WebAssembly est initialement affiché. Les composants utilisant CSR doivent être générés à partir d’un projet client distinct qui configure l’hôte Blazor WebAssembly.

Dans l’exemple suivant, le mode de rendu est défini sur CSR avec @rendermode InteractiveWebAssembly. Le bouton appelle la méthode UpdateMessage lorsqu’il est sélectionné. La valeur message est modifiée et le composant est affiché à nouveau pour mettre à jour le message dans l’interface utilisateur.

RenderMode3.razor:

@page "/render-mode-3"
@rendermode InteractiveWebAssembly

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Si vous utilisez le composant précédent localement dans une Blazor Web App, placez le composant dans le dossier Pages du projet client. Le projet client est le projet de la solution dont le nom se termine par .Client. Lorsque l’application est en cours d’exécution, accédez à /render-mode-3 dans la barre d’adresse du navigateur.

Rendu automatique (Auto)

Le rendu automatique (Auto) détermine comment afficher le composant au moment de l’exécution. Le composant est initialement affiché avec le rendu côté serveur interactif (SSR interactif) en utilisant le modèle d’hébergement Blazor Server. Le runtime .NET et l’ensemble d'applications sont téléchargés sur le client en arrière-plan et mis en cache afin de pouvoir être utilisés lors de visites ultérieures.

Le mode de rendu automatique ne modifie jamais dynamiquement le mode de rendu d’un composant déjà sur la page. Le mode de rendu automatique prend une décision initiale sur le type d’interactivité à utiliser pour un composant, puis le composant conserve ce type d’interactivité tant qu’il se trouve sur la page. L’un des facteurs de cette décision initiale consiste à déterminer si les composants existent déjà sur la page avec l’interactivité WebAssembly/Server. Le mode automatique préfère sélectionner un mode de rendu qui correspond au mode de rendu des composants interactifs existants. La raison pour laquelle le mode automatique préfère utiliser un mode d’interactivité existant consiste à éviter d’introduire un nouveau runtime interactif qui ne partage pas l’état avec le runtime existant.

Les composants utilisant le mode de rendu Auto doivent être générés à partir d’un projet client distinct qui configure l’hôte Blazor WebAssembly.

Dans l’exemple suivant, le composant est interactif tout au long du processus. Le bouton appelle la méthode UpdateMessage lorsqu’il est sélectionné. La valeur message est modifiée et le composant est affiché à nouveau pour mettre à jour le message dans l’interface utilisateur. Initialement, le composant est affiché de manière interactive à partir du serveur, mais lors des visites suivantes, il est affiché à partir du client après que le runtime .NET et l’ensemble d’applications ont été téléchargés et mis en cache.

RenderMode4.razor:

@page "/render-mode-4"
@rendermode InteractiveAuto

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Si vous utilisez le composant précédent localement dans une Blazor Web App, placez le composant dans le dossier Pages du projet client. Le projet client est le projet de la solution dont le nom se termine par .Client. Lorsque l’application est en cours d’exécution, accédez à /render-mode-4 dans la barre d’adresse du navigateur.

Propagation du mode de rendu

Les modes de rendu se propagent dans la hiérarchie des composants.

Règles d’application des modes de rendu :

  • Le mode de rendu par défaut est Statique.
  • Les modes de rendu Serveur interactif (InteractiveServer), WebAssembly interactif (InteractiveWebAssembly) et Auto interactif (InteractiveAuto) peuvent être utilisés à partir d’un composant, notamment en utilisant des modes de rendu différents pour les composants frères.
  • Vous ne pouvez pas basculer vers un autre mode de rendu interactif dans un composant enfant. Par exemple, un composant Serveur ne peut pas être un enfant d’un composant WebAssembly.
  • Les paramètres transmis à un composant enfant interactif à partir d’un parent statique doivent être sérialisables en JSON. Cela signifie que vous ne pouvez pas transmettre de fragments de rendu ou de contenu enfant d’un composant parent statique à un composant enfant interactif.

Les exemples suivants utilisent un composant SharedMessage non routable et non page. Le composant SharedMessage indépendant du mode de rendu n’applique pas de mode de rendu avec une directive @attribute. Si vous testez ces scénarios avec une Blazor Web App, placez le composant suivant dans le dossier Components de l’application.

SharedMessage.razor:

<p>@Greeting</p>

<button @onclick="UpdateMessage">Click me</button> @message

<p>@ChildContent</p>

@code {
    private string message = "Not updated yet.";

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    [Parameter]
    public string Greeting { get; set; } = "Hello!";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Héritage du mode de rendu

Si le composant SharedMessage est placé dans un composant parent rendu statiquement, le composant SharedMessage est également affiché de manière statique et n’est pas interactif. Le bouton n’appelle pas UpdateMessage et le message n’est pas mis à jour.

RenderMode5.razor:

@page "/render-mode-5"

<SharedMessage />

Si le composant SharedMessage est placé dans un composant qui définit le mode de rendu, il hérite du mode de rendu appliqué.

Dans l’exemple suivant, le composant SharedMessage est interactif via une connexion SignalR au client. Le bouton appelle UpdateMessageet le message est mis à jour.

RenderMode6.razor:

@page "/render-mode-6"
@rendermode InteractiveServer

<SharedMessage />

Composants enfants avec différents modes de rendu

Dans l’exemple suivant, les deux composants SharedMessage sont prérendus et apparaissent lorsque la page s’affiche dans le navigateur.

  • Le premier composant SharedMessage avec rendu côté serveur interactif (SSR interactif) est interactif une fois le circuit SignalR établi.
  • Le deuxième composant SharedMessage avec rendu côté client (CSR) est interactif une fois l’ensemble d’applications Blazor téléchargé et le runtime .NET actif sur le client.

RenderMode7.razor:

@page "/render-mode-7"

<SharedMessage @rendermode="InteractiveServer" />
<SharedMessage @rendermode="InteractiveWebAssembly" />

Composant enfant avec un paramètre sérialisable

L’exemple suivant illustre un composant enfant interactif qui prend un paramètre. Les paramètres doivent être sérialisables.

RenderMode8.razor:

@page "/render-mode-8"

<SharedMessage @rendermode="InteractiveServer" Greeting="Welcome!" />

Les paramètres de composants non sérialisables, tels que du contenu enfant ou un fragment de rendu, ne sont pas pris en charge. Dans l’exemple suivant, le passage du contenu enfant au composant SharedMessage entraîne une erreur de runtime.

RenderMode9.razor:

@page "/render-mode-9"

<SharedMessage @rendermode="InteractiveServer">
    Child content
</SharedMessage>

Erreur :

System.InvalidOperationException : impossible de transmettre le paramètre « ChildContent » au composant « SharedMessage » avec le mode de rendu « InteractiveServerRenderMode ». Cela est dû au fait que le paramètre est de type délégué « Microsoft.AspNetCore.Components.RenderFragment », qui est un code arbitraire et ne peut pas être sérialisé.

Pour contourner la limitation précédente, enveloppez le composant enfant dans un autre composant qui n’a pas le paramètre. Il s’agit de l’approche adoptée dans le modèle de projet Blazor Web App avec le composant Routes (Components/Routes.razor) pour envelopper le composant Router.

WrapperComponent.razor:

<SharedMessage>
    Child content
</SharedMessage>

RenderMode10.razor:

@page "/render-mode-10"

<WrapperComponent @rendermode="InteractiveServer" />

Dans l'exemple précédent :

  • Le contenu enfant est transmis au composant SharedMessage sans générer d’erreur de runtime.
  • Le composant SharedMessage s’affiche de manière interactive sur le serveur.

Composant enfant avec un mode de rendu différent de son parent

N’essayez pas d’appliquer à un composant enfant un mode de rendu interactif différent de celui de son parent.

Le composant suivant génère une erreur de runtime lorsque le composant est rendu :

RenderMode11.razor:

@page "/render-mode-11"
@rendermode InteractiveServer

<SharedMessage @rendermode="InteractiveWebAssembly" />

Erreur :

Cannot create a component of type 'BlazorSample.Components.SharedMessage' because its render mode 'Microsoft.AspNetCore.Components.Web.InteractiveWebAssemblyRenderMode' is not supported by Interactive Server rendering.

Pages SSR statiques dans une application interactive globale

Dans certains cas, les spécifications de l’application prévoient que les composants adoptent un rendu statique côté serveur (SSR statique) et ne s’exécutent que sur le serveur, tandis que le rest de l’application utilise un mode de rendu interactif.

Cette approche n’est utile que lorsque l’application a des pages spécifiques qui ne peuvent pas fonctionner avec le rendu interactif server ou WebAssembly. Par exemple, adoptez cette approche pour les pages qui dépendent de la lecture/l’écriture de cookies HTTP et peuvent uniquement fonctionner dans un cycle de requête/réponse au lieu d’un rendu interactif. Pour les pages qui fonctionnent avec le rendu interactif, vous ne devez pas les forcer à utiliser le rendu SSR statique, car il est moins efficace et moins réactif pour l’utilisateur final.

Marquez n’importe quelle page de composant Razor avec l’attribut [ExcludeFromInteractiveRouting] affecté à la directive @attributeRazor :

@attribute [ExcludeFromInteractiveRouting]

L’application de l’attribut entraîne la sortie de la navigation vers la page du routage interactif. La navigation entrante est forcée d’effectuer un rechargement complet de la page au lieu de résoudre la page via routage interactif. Le rechargement complet de la page force le composant racine de niveau supérieur, généralement le composant App (App.razor), à effectuer un nouveau rendu à partir du serveur, ce qui permet à l’application de basculer vers un autre mode de rendu de niveau supérieur.

La méthode d’extension HttpContext.AcceptsInteractiveRouting permet au composant de détecter si [ExcludeFromInteractiveRouting] est appliqué à la page active.

Dans le composant App, utilisez le modèle dans l’exemple suivant :

  • Les pages dépourvues de l’annotation [ExcludeFromInteractiveRouting] présentent par défaut le mode de rendu InteractiveServer avec interactivité globale. Vous pouvez remplacer InteractiveServer par InteractiveWebAssembly ou InteractiveAuto pour spécifier un autre mode de rendu global par défaut.
  • Les pages dotées de l’annotation [ExcludeFromInteractiveRouting] adoptent le SSR statique (null est affecté à PageRenderMode).
<!DOCTYPE html>
<html>
<head>
    ...
    <HeadOutlet @rendermode="@PageRenderMode" />
</head>
<body>
    <Routes @rendermode="@PageRenderMode" />
    ...
</body>
</html>

@code {
    [CascadingParameter]
    private HttpContext HttpContext { get; set; } = default!;

    private IComponentRenderMode? PageRenderMode
        => HttpContext.AcceptsInteractiveRouting() ? InteractiveServer : null;
}

Une alternative à l’utilisation de la méthode d’extension HttpContext.AcceptsInteractiveRouting consiste à lire manuellement les métadonnées de point de terminaison à l’aide de HttpContext.GetEndpoint()?.Metadata.

Deux approches peuvent être adoptées pour le contrôle fin des modes de rendu, chacune d’entre elles étant décrite dans les sous-sections suivantes :

  • Zone (dossier) des composants SSR statiques : vous disposez d’une zone (dossier) de l’application avec des composants qui doivent adopter le SSR statique et partager le même préfixe de chemin d’accès d’itinéraire. L’application contrôle le mode de rendu globalement en définissant le mode de rendu sur le Routes composant dans le App composant en fonction du chemin d’accès au dossier.

  • Composants SSR statiques répartis sur l’application : vous avez des composants répartis dans l’application à différents emplacements qui doivent adopter le SSR statique et s’exécuter uniquement sur le serveur. Les composants statiques du SSR ne se trouvent pas dans un dossier unique et ne partagent pas le même préfixe de chemin d’accès. L’application contrôle le mode de rendu par composant en définissant le mode de rendu avec la directive dans les @rendermode instances de composant. La réflexion est utilisée dans le Appcomposant pour définir le mode de rendu du Routes composant.

Dans les deux cas, le composant qui doit adopter le SSR statique doit également forcer un rechargement de page complète.

Les exemples suivants utilisent le HttpContext paramètre en cascade pour déterminer si la page est rendue statiquement. Un null HttpContext indique que le composant a un rendu interactif, ce qui est utile comme signal dans le code de l’application pour déclencher un rechargement complet de la page.

Zone (dossier) des composants SSR statiques

L’approche décrite dans cette sous-section est utilisée par le modèle de projet Blazor Web App avec authentification individuelle et interactivité globale.

Une zone (dossier) de l’application contient les composants qui doivent adopter un SSR statique et ne s’exécuter que sur le serveur. Les composants du dossier partagent le même préfixe de chemin d’accès. Par exemple, les composants IdentityRazor du modèle de projet Blazor Web App se trouvent dans le dossier Components/Account/Pages et partagent le préfixe du chemin d’accès racine /Account.

Le dossier contient également un fichier _Imports.razor, qui applique un layout de compte personnalisé aux composants du dossier :

@using BlazorSample.Components.Account.Shared
@layout AccountLayout

Le dossier Shared gère le composant de layout AccountLayout. Le composant utilise HttpContext pour déterminer si le composant a adopté le SSR statique. Les composants Identity doivent être rendus sur le serveur via un SSR statique, car ils définissent les cookies Identity. Si la valeur est HttpContext null, le composant est rendu de manière interactive et un rechargement de page complète est effectué en appelant NavigationManager.Refresh avec forceLoad la valeur définie sur true. Cela force une nouvelle version complète de la page à l’aide de la fonction SSR statique.

Components/Account/Shared/AccountLayout.razor:

@inherits LayoutComponentBase
@layout BlazorSample.Components.Layout.MainLayout
@inject NavigationManager Navigation

@if (HttpContext is null)
{
    <p>Loading...</p>
}
else
{
    @Body
}

@code {
    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override void OnParametersSet()
    {
        if (HttpContext is null)
        {
            Navigation.Refresh(forceReload: true);
        }
    }
}

Remarque

Dans le modèle de projet Blazor Web App, il existe un deuxième fichier de layout (ManageLayout.razor dans le dossier Components/Account/Shared) pour les composants Identity du dossier Components/Account/Pages/Manage. Le Manage dossier possède son propre _Imports.razor fichier à appliquer aux ManageLayout composants du dossier. Dans vos propres applications, l’utilisation de fichiers imbriqués _Imports.razor est une approche utile pour appliquer des layouts personnalisés à des groupes de pages.

Dans le App composant, toute requête d’un composant dans le Account dossier applique un null mode de rendu, qui applique la SSR statique. D’autres demandes de composant reçoivent une application globale du mode de rendu SSR interactif (InteractiveServer).

Important

L’application d’un null mode de rendu n’applique pas toujours la SSR statique. Il arrive simplement de se comporter de cette façon à l’aide de l’approche présentée dans cette section.

Un null mode de rendu est effectivement identique à ne pas spécifier de mode de rendu, ce qui entraîne l’héritage du mode de rendu de son parent. Dans ce cas, le App composant est rendu à l’aide du SSR statique. Par conséquent, un null mode de rendu entraîne l’héritage Routes du SSR statique du App composant. Si un mode de rendu nul est spécifié pour un composant enfant dont le parent utilise un mode de rendu interactif, l’enfant hérite du même mode de rendu interactif.

Components/App.razor:

<Routes @rendermode="RenderModeForPage" />

...

@code {
    [CascadingParameter]
    private HttpContext HttpContext { get; set; } = default!;

    private IComponentRenderMode? RenderModeForPage => 
        HttpContext.Request.Path.StartsWithSegments("/Account")
            ? null
            : {INTERACTIVE RENDER MODE};
}

Dans le code précédent, remplacez l’espace réservé {INTERACTIVE RENDER MODE} par la valeur appropriée, si le rest de l’application doit adopter le rendu global InteractiveServer, InteractiveWebAssembly, ou le rendu InteractiveAuto.

Les composants qui doivent adopter le SSR statique dans le dossier Account ne sont pas nécessaires pour définir la mise en page, qui est appliquée via le fichier _Imports.razor. Les composants ne définissent pas de mode de rendu, car leur rendu doit être effectué avec le SSR statique. Rien d’autre ne doit être effectué pour les composants du Account dossier afin d’appliquer la SSR statique.

Composants SSR statiques répartis dans l’application

Dans la sous-section précédente, l’application contrôle le mode de rendu des composants en définissant le mode de rendu globalement dans le composant App. App Le composant peut également adopter des modes de rendu par composant pour définir le mode de rendu, ce qui permet aux composants répartis autour de l’application d’appliquer l’adoption de la SSR statique. Cette sous-section décrit l’approche.

L’application a un layout personnalisé qui peut être appliqué aux composants autour de l’application. En règle générale, un composant partagé pour l’application est placé dans le dossier Components/Layout. Le composant utilise HttpContext pour déterminer si le composant a adopté le SSR statique. Si la valeur est HttpContext null, le composant est rendu de manière interactive et un rechargement de page complète est effectué en appelant NavigationManager.Refresh avec forceLoad la valeur définie sur true. Cela déclenche une requête au serveur pour le composant.

Components/Layout/StaticSsrLayout.razor:

@inherits LayoutComponentBase
@layout MainLayout
@inject NavigationManager Navigation

@if (HttpContext is null)
{
    <p>Loading...</p>
}
else
{
    @Body
}

@code {
    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override void OnParametersSet()
    {
        if (HttpContext is null)
        {
            Navigation.Refresh(forceReload: true);
        }
    }
}

Dans le composant App, la réflexion est utilisée pour définir le mode de rendu. Quel que soit le mode de rendu affecté au fichier de définition de composant individuel, il est appliqué au composant Routes.

Components/App.razor:

<Routes @rendermode="RenderModeForPage" />

...

@code {
    [CascadingParameter]
    private HttpContext HttpContext { get; set; } = default!;

    private IComponentRenderMode? RenderModeForPage =>
        HttpContext.GetEndpoint()?.Metadata.GetMetadata<RenderModeAttribute>()?
            .Mode;
}

Chaque composant qui doit adopter le SSR statique définit la mise en page personnalisée et ne spécifie pas de mode de rendu. L’absence de spécification d’un mode de rendu entraîne une null valeur du RenderModeAttribute.Mode dans le composant App, ce qui n’entraîne aucun mode de rendu affecté à l’instance du composant Routes et à l’application de la SSR statique.

Important

L’application d’un null mode de rendu n’applique pas toujours la SSR statique. Il arrive simplement de se comporter de cette façon à l’aide de l’approche présentée dans cette section.

Un null mode de rendu est effectivement identique à ne pas spécifier de mode de rendu, ce qui entraîne l’héritage du mode de rendu de son parent. Dans ce cas, le App composant est rendu à l’aide du SSR statique. Par conséquent, un null mode de rendu entraîne l’héritage Routes du SSR statique du App composant. Si un mode de rendu nul est spécifié pour un composant enfant dont le parent utilise un mode de rendu interactif, l’enfant hérite du même mode de rendu interactif.

Pour que les composants appliquent le rendu côté client statique, il ne reste qu’à appliquer la disposition personnalisée sans définir de mode de rendu interactif :

@layout BlazorSample.Components.Layout.StaticSsrLayout

Les composants interactifs autour de l’application évitent d’appliquer la disposition de rendu côté client statique personnalisée et définissent uniquement un mode de rendu interactif approprié, qui, après réflexion dans le composant App, est appliqué au composant Routes :

@rendermode {INTERACTIVE RENDER MODE}

Dans le code précédent, remplacez l’espace réservé {INTERACTIVE RENDER MODE} par la valeur appropriée, selon que le reste de l’application doit adopter le rendu global InteractiveServer, InteractiveWebAssemblyou le rendu InteractiveAuto.

Les services côté client ne parviennent pas à être résolus lors du prérendu

En supposant que le prérendu n’est pas désactivé pour un composant ou pour l’application, un composant du projet .Client est prérendu sur le serveur. Le serveur n’ayant pas accès aux services Blazor côté client inscrits, il n’est pas possible d’injecter ces services dans un composant sans recevoir d’erreur indiquant que le service n’a pas pu être trouvé lors du prérendu.

Par exemple, considérez le composant Home suivant dans le projet .Client d’une Blazor Web App avec rendu global WebAssembly interactif ou Auto interactif. Le composant tente d’injecter IWebAssemblyHostEnvironment pour obtenir le nom de l’environnement.

@page "/"
@inject IWebAssemblyHostEnvironment Environment

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<p>
    Environment: @Environment.Environment
</p>

Aucune erreur de temps de compilation ne se produit, mais une erreur de runtime se produit pendant le prérendu :

Impossible de fournir une valeur pour la propriété « Environment » sur le type « BlazorSample.Client.Pages.Home ». Il n’existe aucun service inscrit de type « Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment ».

Cette erreur se produit, car le composant doit compiler et s’exécuter sur le serveur pendant le prérendu, mais IWebAssemblyHostEnvironment n’est pas un service inscrit sur le serveur.

Si l’application n’a pas besoin de la valeur pendant le prérendu, ce problème peut être résolu en injectant IServiceProvider pour obtenir le service au lieu du type de service lui-même :

@page "/"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IServiceProvider Services

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<p>
    <b>Environment:</b> @environmentName
</p>

@code {
    private string? environmentName;

    protected override void OnInitialized()
    {
        if (Services.GetService<IWebAssemblyHostEnvironment>() is { } env)
        {
            environmentName = env.Environment;
        }
    }
}

Toutefois, l’approche précédente n’est pas utile si votre logique nécessite une valeur pendant le prérendu.

Vous pouvez également éviter le problème si vous désactivez le prérendu pour le composant, mais c’est une mesure extrême à prendre dans de nombreux cas qui peuvent ne pas répondre aux spécifications de votre composant.

Il existe trois approches que vous pouvez prendre pour aborder ce scénario. Les éléments suivants sont listés du plus recommandé au moins recommandé :

  • Recommandé pour les services de framework partagé : pour les services de framework partagé qui ne sont simplement pas inscrits côté serveur dans le projet principal, inscrivez les services dans le projet principal, ce qui les rend disponibles lors de la préversion. Pour obtenir un exemple de ce scénario, consultez les conseils pour les services HttpClient dans Appeler une API web à partir d’une application Blazor ASP.NET Core.

  • Recommandé pour les services en dehors du cadre partagé : créez une implémentation de service personnalisé pour le service sur le serveur. Utilisez normalement le service dans les composants interactifs du projet .Client. Pour une démonstration de cette approche, consultez ASP.NET Core Blazor environnements.

  • Créez une abstraction de service et créez des implémentations pour le service dans les projets .Client et serveur. Inscrivez les services dans chaque projet. Injectez le service personnalisé dans le composant.

  • Vous pouvez peut-être ajouter une référence de package de projet .Client à un package côté serveur et revenir à l’utilisation de l’API côté serveur pendant le prérendu sur le serveur.

Découvrir des composants d’assemblys supplémentaires

Des assemblys supplémentaires doivent être divulgués à l’infrastructure Blazor pour découvrir les composants Razor routables dans les projets référencés. Pour plus d’informations, consultez Routage et navigation ASP.NET Core Blazor.

Fermeture des circuits quand il ne reste plus de composants de serveur interactif

Les composants de serveur interactif gèrent les événements de l’interface utilisateur web en utilisant une connexion en temps réel avec le navigateur, appelée un circuit. Un circuit et son état associé sont créés quand un composant de serveur interactif racine est rendu. Le circuit est fermé quand il ne reste plus de composants de serveur interactif sur la page, ce qui libère des ressources du serveur.

Modes de rendu abrégés personnalisés

La directive @rendermode prend un seul paramètre qui est une instance statique de type IComponentRenderMode. L'attribut directive @rendermode peut prendre n'importe quelle instance de mode de rendu, statique ou non. Le framework Blazor fournit à la classe statique RenderMode avec certains modes de rendu prédéfinis pour plus de commodité, mais vous pouvez créer les vôtres.

Normalement, un composant utilise la directive @rendermode suivante pour désactiver le prérendu :

@rendermode @(new InteractiveServerRenderMode(prerender: false))

Toutefois, considérez l’exemple suivant qui crée un mode de rendu côté serveur interactif abrégé sans prérendu via le fichier _Imports de l’application (Components/_Imports.razor) :

public static IComponentRenderMode InteractiveServerWithoutPrerendering { get; } = 
    new InteractiveServerRenderMode(prerender: false);

Utilisez le mode de rendu abrégé dans les composants dans tout le dossier Components :

@rendermode InteractiveServerWithoutPrerendering

Une instance à composant unique peut également définir un mode de rendu personnalisé via un champ privé :

@rendermode interactiveServerWithoutPrerendering

...

@code {
    private static IComponentRenderMode interactiveServerWithoutPrerendering = 
        new InteractiveServerRenderMode(prerender: false);
}

Pour le moment, l'approche du mode de rendu abrégé n'est probablement utile que pour réduire la verbosité de la spécification de l'indicateur prerender. L'approche abrégée pourrait être plus utile à l'avenir si des indicateurs supplémentaires deviennent disponibles pour le rendu interactif et si vous souhaitez créer des modes de rendu abrégés avec différentes combinaisons d'indicateurs.

Injection de service via un fichier d’importation de niveau supérieur (_Imports.razor)

Cette section s’applique uniquement aux Blazor Web App.

Un fichier d’importation de niveau supérieur dans le dossier Components (Components/_Imports.razor) injecte ses références dans tous les composants de la hiérarchie de dossiers, qui inclut le composant App (App.razor). Le composant App est toujours rendu statiquement, même si le prérendu d’un composant de page est désactivé. Par conséquent, l’injection de services via le fichier d’importation de niveau supérieur entraîne la résolution de deux instances du service dans les composants de page.

Pour résoudre ce scénario, injectez le service dans un nouveau fichier d’importation placé dans le dossier Pages (Components/Pages/_Imports.razor). À partir de cet emplacement, le service est résolu une seule fois dans les composants de page.

Ressources supplémentaires