Modes de rendu ASP.NET Core Blazor

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.

† 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 :

• AddInteractiveServerComponents ajoute des services pour prendre en charge le rendu des composants de serveur interactif.
• AddInteractiveWebAssemblyComponents ajoute des services pour prendre en charge le rendu des composants WebAssembly interactifs.

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 :

• AddInteractiveServerRenderMode configure le rendu côté serveur interactif (SSR interactif) pour l’application.
• AddInteractiveWebAssemblyRenderMode configure le mode de rendu WebAssembly interactif pour l’application.

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" />

@using static Microsoft.AspNetCore.Components.Web.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.

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.

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.

<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;
        }
    }
}

@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>
}

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 :

• Contenu non autorisé (<NotAuthorized>...</NotAuthorized>) (NotAuthorized) : les Blazor Web App traitent généralement les demandes non autorisées sur le serveur en personnalisant le comportement du middleware d’autorisation.

• Contenu introuvable (<NotFound>...</NotFound>) (NotFound) : les Blazor Web App traitent généralement les demandes d’URL incorrectes sur le serveur en affichant l’interface utilisateur intégrée 404 du navigateur ou en retournant une page 404 personnalisée (ou une autre réponse) via le middleware ASP.NET Core (par exemple, UseStatusCodePagesWithRedirects / documentation de l’API ).

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 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-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.

@attribute [ExcludeFromInteractiveRouting]

<!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;
}

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

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

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

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

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

<Routes @rendermode="RenderModeForPage" />

...

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

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

@inherits LayoutComponentBase
@layout MainLayout
@inject NavigationManager NavigationManager

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

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

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

<Routes @rendermode="RenderModeForPage" />

...

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

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

@layout BlazorSample.Components.Layout.StaticSsrLayout

@rendermode {INTERACTIVE RENDER MODE}

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