Partager via

Intégrer des composants Razor ASP.NET Core avec MVC ou Razor Pages

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 9 de cet article.

Avertissement

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la stratégie de support .NET et .NET Core. Pour la version actuelle, consultez la version .NET 9 de cet article.

Importante

Ces informations portent sur un produit en préversion, qui est susceptible d'être en grande partie modifié avant d'être commercialisé. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 9 de cet article.

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

Importante

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.

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 :

Paramétrage

Utilisez les instructions suivantes pour intégrer Razor les composants dans des pages ou 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'assistant de balise de composant HeadOutlet à 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, consultez ASP.NET chemin de base de l’application 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 mise en page 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 (Pages Razor) 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 la balise {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 la balise {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.

Remarque

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 ServerPrerendered dans une application Blazor Server :

<body>
    ...

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

Déterminez l’état à conserver à l’aide du service PersistentComponentState. L’attribut [SupplyParameterFromPersistentComponentState] appliqué à une propriété enregistre un rappel pour conserver l’état pendant le prérendu et le charge lorsque le composant est rendu de manière interactive ou que le service est instancié.

Dans l’exemple suivant, l’espace {TYPE} réservé représente le type de données à conserver (par exemple). WeatherForecast[]

@code {
    [SupplyParameterFromPersistentComponentState]
    public {TYPE} Data { get; set; }

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

Dans l’exemple suivant, le composant conserve l’état WeatherForecastPreserveState des prévisions météorologiques pendant la préversion, 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.

WeatherForecastPreserveState.razor :

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

<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 {
    [SupplyParameterFromPersistentComponentState]
    public WeatherForecast[]? Forecasts { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Forecasts ??= await WeatherForecastService.GetForecastAsync(
            DateOnly.FromDateTime(DateTime.Now));
    }
}

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. Effectuez l'appel à la fin du code d'initialisation afin d'éviter une condition de concurrence potentielle lors de l'arrêt de l'application.

Dans l’exemple suivant :

  • L’espace réservé {TYPE} représente le type de données à conserver (par exemple WeatherForecast[]).
  • Le placeholder {TOKEN} est une chaîne d'identification d'état (par exemple fetchdata).
@implements IDisposable
@inject PersistentComponentState ApplicationState

...

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

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

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

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

        return Task.CompletedTask;
    }

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

Dans l’exemple suivant, le composant conserve l’état WeatherForecastPreserveState des prévisions météorologiques pendant la préversion, 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()
    {
        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            nameof(forecasts), out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(
                    DateOnly.FromDateTime(DateTime.Now));
        }
        else
        {
            forecasts = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson(nameof(forecasts), 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.

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 Blazor de 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

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 :

Paramétrage

Utilisez les instructions suivantes pour intégrer Razor les composants dans des pages ou des vues d’une application Razor Pages ou MVC existante.

Importante

L’utilisation d’une page de disposition (_Layout.cshtml) avec une assistance des balises de composant pour un composant HeadOutlet est nécessaire pour contrôler le contenu <head>, tel que le titre de page (composant PageTitle) et d’autres éléments principaux (composant HeadContent). Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core Blazor.

  1. Dans le fichier de disposition du projet :

    • Ajoutez la balise <base> suivante et l’assistance des balises de composant HeadOutlet à l’élément <head> dans Pages/Shared/_Layout.cshtml (Razor Pages) ou Views/Shared/_Layout.cshtml (MVC) :

      <base href="~/" />
<component type="typeof(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, consultez ASP.NET chemin de base de l’application 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(...)) dans la disposition de l’application.

      Pages/Shared/_Layout.cshtml (Pages Razor) ou Views/Shared/_Layout.cshtml (MVC) :

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

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

  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 (Pages Razor) 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 la balise {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 la balise {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.

    Pages/_Host.cshtml :

    @page "/blazor"
@namespace {APP NAMESPACE}.Pages.Shared
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@{
    Layout = "_Layout";
}

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

    Dans ce scénario, les composants utilisent le fichier _Layout.cshtml partagé pour leur disposition.

    Importante

    L’utilisation d’une page de disposition (_Layout.cshtml) avec une assistance des balises de composant pour un composant HeadOutlet est nécessaire pour contrôler le contenu <head>, tel que le titre de page (composant PageTitle) et d’autres éléments principaux (composant HeadContent). Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core Blazor.

    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.

    Views/Home/_Host.cshtml :

    @namespace {APP NAMESPACE}.Views.Shared
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@{
    Layout = "_Layout";
}

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

    Les composants utilisent le fichier _Layout.cshtml partagé pour leur mise en page.

    Importante

    L’utilisation d’une page de disposition (_Layout.cshtml) avec une assistance des balises de composant pour un composant HeadOutlet est nécessaire pour contrôler le contenu <head>, tel que le titre de page (composant PageTitle) et d’autres éléments principaux (composant HeadContent). Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core Blazor.

    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.

Importante

L’utilisation d’une page de disposition (_Layout.cshtml) avec une assistance des balises de composant pour un composant HeadOutlet est nécessaire pour contrôler le contenu <head>, tel que le titre de page (composant PageTitle) et d’autres éléments principaux (composant HeadContent). Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core Blazor.

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.

Importante

L’utilisation d’une page de disposition (_Layout.cshtml) avec une assistance des balises de composant pour un composant HeadOutlet est nécessaire pour contrôler le contenu <head>, tel que le titre de page (composant PageTitle) et d’autres éléments principaux (composant HeadContent). Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core Blazor.

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 résoudre ces problèmes, Blazor prend en charge l’état persistant dans une page prérendue à l’aide de l’assistance des balises d’état de composant persistant. Ajoutez la balise <persist-component-state /> du Tag Helper à l'intérieur de la balise fermante </body>.

Pages/_Layout.cshtml :

<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. Effectuez l'appel à la fin du code d'initialisation afin d'éviter une condition de concurrence potentielle lors de l'arrêt de l'application.

Dans l’exemple suivant, le composant conserve l’état WeatherForecastPreserveState des prévisions météorologiques pendant la préversion, 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"
@implements IDisposable
@using BlazorSample.Shared
@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()
    {
        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            nameof(forecasts), out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateTime.Now);
        }
        else
        {
            forecasts = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson(nameof(forecasts), 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.

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 Blazor de 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

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 :

Paramétrage

Une application Pages ou MVC existante peut Razor intégrer des composants Razor dans des pages et des vues :

  1. Dans le fichier de disposition du projet :

    • Ajoutez la balise <base> suivante à l’élément <head> dans Pages/Shared/_Layout.cshtml (Razor Pages) ou Views/Shared/_Layout.cshtml (MVC) :

      <base href="~/" />

      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, consultez ASP.NET chemin de base de l’application CoreBlazor.

    • Ajoutez une balise <script> au script blazor.server.js immédiatement avant la section de rendu Scripts.

      Pages/Shared/_Layout.cshtml (Pages Razor) ou Views/Shared/_Layout.cshtml (MVC) :

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

    @await RenderSectionAsync("Scripts", required: false)
</body>

      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.

  2. 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.JSInterop
@using {APP NAMESPACE}

  3. Enregistrez le service Blazor Server dans Startup.ConfigureServices.

    Dans Startup.cs:

    services.AddServerSideBlazor();

  4. Ajoutez le point de terminaison du hub Blazor aux points de terminaison (app.UseEndpoints) de Startup.Configure.

    Startup.cs :

    endpoints.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 (Pages Razor) 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 la balise {APP NAMESPACE} par l’espace de noms du projet.

    Pages/Index.cshtml :

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

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

    Dans l’exemple précédent, remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms de l’application.

    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 la balise {APP NAMESPACE} par l’espace de noms du projet.

    Views/Home/Index.cshtml :

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

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

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(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

    Remarque

    Avec la version .NET 5.0.1 et pour toute version 5.x ultérieure, le composant Router inclut le paramètre PreferExactMatches défini sur @true. Pour plus d’informations, consultez Migrer de ASP.NET Core 3.1 vers .NET 5.

  3. Ajoutez une page _Host au projet avec le contenu suivant.

    Pages/_Host.cshtml :

    @page "/blazor"
@{
    Layout = "_Layout";
}

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

    Les composants utilisent le fichier _Layout.cshtml partagé pour leur mise en page.

    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 Startup.Configure de Startup.cs, ajoutez un itinéraire de faible priorité pour la page _Host comme dernier point de terminaison :

    endpoints.MapFallbackToPage("/_Host");

    L’exemple suivant présente la ligne ajoutée dans une configuration du point de terminaison d’une application standard :

    app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToPage("/_Host");
});

  5. Ajoutez des composants routables au projet.

    Pages/RoutableCounter.razor :

    @page "/routable-counter"

<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(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

    Remarque

    Avec la version .NET 5.0.1 et pour toute version 5.x ultérieure, le composant Router inclut le paramètre PreferExactMatches défini sur @true. Pour plus d’informations, consultez Migrer de ASP.NET Core 3.1 vers .NET 5.

  3. Ajoutez une vue _Host au projet avec le contenu suivant.

    Views/Home/_Host.cshtml :

    @{
    Layout = "_Layout";
}

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

    Les composants utilisent le fichier _Layout.cshtml partagé pour leur mise en page.

    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 Startup.Configure de Startup.cs, ajoutez un itinéraire de faible priorité à l’action du contrôleur qui retourne la vue _Host :

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

    L’exemple suivant présente la ligne ajoutée dans une configuration du point de terminaison d’une application standard :

    app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToController("Blazor", "Home");
});

  6. Ajoutez des composants routables au projet.

    Pages/RoutableCounter.razor :

    @page "/routable-counter"

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

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 Blazor de 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

Les composants Razor peuvent être intégrés dans les applications Razor Pages ou MVC. Lorsque la page ou la vue est affichée, les composants peuvent être rendus à l'avance 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 :

Paramétrage

Une application Pages ou MVC existante peut Razor intégrer des composants Razor dans des pages et des vues :

  1. Dans le fichier de disposition du projet :

    • Ajoutez la balise <base> suivante à l’élément <head> dans Pages/Shared/_Layout.cshtml (Razor Pages) ou Views/Shared/_Layout.cshtml (MVC) :

      + <base href="~/" />

      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, consultez ASP.NET chemin de base de l’application CoreBlazor.

    • Ajoutez une balise <script> au script blazor.server.js immédiatement avant la section de rendu Scripts.

      Pages/Shared/_Layout.cshtml (Pages Razor) ou Views/Shared/_Layout.cshtml (MVC) :

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

    @await RenderSectionAsync("Scripts", required: false)
</body>

      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.

  2. 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.JSInterop
@using {APP NAMESPACE}

  3. Enregistrez le service Blazor Server dans Startup.ConfigureServices.

    Startup.cs :

    services.AddServerSideBlazor();

  4. Ajoutez le point de terminaison du hub Blazor aux points de terminaison (app.UseEndpoints) de Startup.Configure.

    Startup.cs :

    endpoints.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 (Pages Razor) 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 la balise {APP NAMESPACE} par l’espace de noms du projet.

    Pages/Index.cshtml :

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

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

    Dans l’exemple précédent, remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms de l’application.

    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 la balise {APP NAMESPACE} par l’espace de noms du projet.

    Views/Home/Index.cshtml :

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

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

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(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

  3. Ajoutez une page _Host au projet avec le contenu suivant.

    Pages/_Host.cshtml :

    @page "/blazor"
@{
    Layout = "_Layout";
}

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

    Les composants utilisent le fichier _Layout.cshtml partagé pour leur mise en page.

    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 Startup.Configure de Startup.cs, ajoutez un itinéraire de faible priorité pour la page _Host comme dernier point de terminaison :

    endpoints.MapFallbackToPage("/_Host");

    L’exemple suivant présente la ligne ajoutée dans une configuration du point de terminaison d’une application standard :

    app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToPage("/_Host");
});

  5. Ajoutez des composants routables au projet.

    Pages/RoutableCounter.razor :

    @page "/routable-counter"

<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(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

  3. Ajoutez une vue _Host au projet avec le contenu suivant.

    Views/Home/_Host.cshtml :

    @{
    Layout = "_Layout";
}

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

    Les composants utilisent le fichier _Layout.cshtml partagé pour leur mise en page.

    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 Startup.Configure de Startup.cs, ajoutez un itinéraire de faible priorité à l’action du contrôleur qui retourne la vue _Host :

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

    L’exemple suivant présente la ligne ajoutée dans une configuration du point de terminaison d’une application standard :

    app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToController("Blazor", "Home");
});

  6. Ajoutez des composants routables au projet.

    Pages/RoutableCounter.razor :

    @page "/routable-counter"

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

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 Blazor de 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