Partage via

Intégrer des composants Razor ASP.NET Core aux applications ASP.NET Core

  • Article

Cet article explique les scénarios Razor d’intégration des composants pour les applications ASP.NET Core.

Intégration de composants Razor

Les composants Razor peuvent être intégrés dans Razor Pages, MVC et d’autres types d’applications ASP.NET Core. Razorles composants peuvent également être intégrés à n’importe quelle application web, y compris les applications non basées sur ASP.NET Core, en tant qu’éléments HTML personnalisés.

Procédez ensuite comme expliqué dans les sections suivantes en fonction des exigences de l’application :

Utiliser des composants non routables dans des pages ou des vues

Utilisez l’aide suivante pour intégrer des composants Razor à des pages et des vues d’une application Pages ou MVC Razor existante à l’aide de l’assistance des balises de composant.

Remarque

Si votre application nécessite des composants routables directement (non incorporés dans des pages ou des vues), ignorez cette section et utilisez l’aide de la section Ajouter une prise en charge de Blazor à une application ASP.NET Core.

Lorsque le pré-rendu du serveur est utilisé et que 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.

Pour plus d’informations sur les modes de rendu, y compris le rendu de composants statiques non interactifs, consultez Tag Helper de composant dans ASP.NET Core. Pour enregistrer l’état des composants Razor prédéfinis, consultez Conserver le Tag Helper d’état du composant dans ASP.NET Core.

Ajoutez un dossier Components au dossier racine du projet.

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

Components/_Imports.razor :

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

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 le Tag Helper de composant suivants pour un composant HeadOutlet au balisage <head> :

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

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

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

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

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

    L’infrastructure Blazor ajoute le script blazor.web.js à l’application.

Remarque

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

Ajoutez un composant non opérationnel (no-op) App au projet.

Components/App.razor :

@* No-op App component *@

Lorsque les services sont inscrits, ajoutez des services pour les composants et services Razor pour prendre en charge le rendu interactif des composants de serveur.

En haut du fichier Program, ajoutez une instruction using pour les composants du projet :

using {APP NAMESPACE}.Components;

Dans la ligne précédente, remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms de l’application. Par exemple :

using BlazorSample.Components;

Dans le fichier Program avant la ligne qui génère l’application (builder.Build()) :

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

Pour plus d’informations sur l’ajout de la prise en charge des composants serveur interactif et WebAssembly, consultez Modes de rendu Blazor ASP.NET Core.

Dans le fichier Program, immédiatement après l’appel pour mapper les Razor Pages (MapRazorPages) dans une application Razor Pages ou pour mapper la route du contrôleur par défaut (MapControllerRoute) dans une application MVC, appelez MapRazorComponents pour découvrir les composants disponibles et spécifiez le composant racine de l’application (le premier composant chargé). Par défaut, le composant racine de l’application est le composant App (App.razor). Enchaînez un appel à AddInteractiveServerRenderMode pour configurer le rendu côté serveur interactif (SSR interactif) pour l’application :

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

Remarque

Si l’application n’a pas déjà été mise à jour pour inclure l’intergiciel Antiforgery, ajoutez la ligne suivante après l’appel de UseAuthorization :

app.UseAntiforgery();

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

Components/EmbeddedCounter.razor :

<h1>Embedded 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 EmbeddedCounter et incorporez le composant dans la page. Quand la page Index se charge, le composant EmbeddedCounter est prérendu dans la page. Dans l’exemple suivant, remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms du projet.

Pages/Index.cshtml :

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

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

MVC :

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

Views/Home/Index.cshtml :

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

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

Ajouter la prise en charge de Blazor à une application ASP.NET Core

Cette section traite de l’ajout de la prise en charge de Blazor à une application ASP.NET Core :

Remarque

Pour les exemples de cette section, le nom et l’espace de noms de l’exemple d’application est BlazorSample.

Ajouter un rendu statique côté serveur (SSR statique)

Ajoutez un dossier Components à l’application.

Ajoutez le fichier _Imports suivant pour les espaces de noms utilisés par les composants Razor.

Components/_Imports.razor :

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

Remplacez l’espace réservé ({APP NAMESPACE}) de l’espace de noms par l’espace de noms de l’application. Par exemple :

@using BlazorSample
@using BlazorSample.Components

Ajoutez le routeur Blazor (<Router>, Router) à l’application dans un composant Routes, qui est placé dans le dossier Components de l’application.

Components/Routes.razor :

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
        <FocusOnNavigate RouteData="routeData" Selector="h1" />
    </Found>
</Router>

Ajoutez un composant App à l’application, qui sert de composant racine, c’est-à-dire le premier composant que l’application charge.

Components/App.razor :

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <base href="/" />
    <link rel="stylesheet" href="@Assets["{ASSEMBLY NAME}.styles.css"]" />
    <HeadOutlet />
</head>

<body>
    <Routes />
    <script src="_framework/blazor.web.js"></script>
</body>

</html>

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <base href="/" />
    <link rel="stylesheet" href="{ASSEMBLY NAME}.styles.css" />
    <HeadOutlet />
</head>

<body>
    <Routes />
    <script src="_framework/blazor.web.js"></script>
</body>

</html>

L’espace réservé {ASSEMBLY NAME} est le nom de l’assembly de l’application. Par exemple, un projet avec le nom d’assembly ContosoApp utilise le nom du fichier de feuille de style ContosoApp.styles.css.

Ajoutez un dossier Pages au dossier Components pour contenir les composants Razor routables.

Ajoutez le composant Welcome suivant pour illustrer le SSR statique.

Components/Pages/Welcome.razor :

@page "/welcome"

<PageTitle>Welcome!</PageTitle>

<h1>Welcome to Blazor!</h1>

<p>@message</p>

@code {
    private string message = 
        "Hello from a Razor component and welcome to Blazor!";
}

Dans le fichier Program du projet ASP.NET Core :

  • Ajoutez une instruction using en haut du fichier pour les composants du projet :

    using {APP NAMESPACE}.Components;

    Dans la ligne précédente, remplacez l’espace réservé {APP NAMESPACE} par l’espace de noms de l’application. Par exemple :

    using BlazorSample.Components;

  • Ajoutez des services de composant Razor (AddRazorComponents), qui ajoutent également automatiquement des services antiforgery (AddAntiforgery). Ajoutez la ligne suivante avant celle qui appelle builder.Build() :

    builder.Services.AddRazorComponents();

  • AjoutezAntiforgery Middleware au pipeline de traitement des requêtes UseAntiforgery. UseAntiforgery est appelé après l’appel à UseRouting. S’il y a des appels vers UseRouting et UseEndpoints, l’appel vers UseAntiforgery doit passer entre eux. Un appel à UseAntiforgery doit être placer après les appels à UseAuthentication et UseAuthorization.

    app.UseAntiforgery();

  • Ajoutez MapRazorComponents au pipeline de traitement des requêtes de l’application avec le composant App (App.razor) spécifié comme composant racine par défaut (le premier composant chargé). Placez le code suivant avant la ligne qui appelle app.Run :

    app.MapRazorComponents<App>();

Lorsque l’application est exécutée, le composant Welcome est accessible au point de terminaison /welcome.

Activer le rendu interactif côté serveur (SSR interactif)

Suivez les instructions de la section Ajouter le rendu statique côté serveur (SSR statique) .

Dans le fichier Program de l’application, ajoutez un appel à AddInteractiveServerComponents là où les services de composant Razor sont ajoutés avec AddRazorComponents :

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

Ajoutez un appel à AddInteractiveServerRenderMode là où les composants Razor sont mappés avec MapRazorComponents :

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

Ajoutez le composant Counter suivant à l’application qui adopte le rendu interactif côté serveur (SSR interactif).

Components/Pages/Counter.razor :

@page "/counter"
@rendermode InteractiveServer

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Lorsque l’application est exécutée, le composant Counter est accessible à /counter.

Activer le rendu interactif (automatique) ou côté client (CSR)

Suivez les instructions de la section Ajouter le rendu statique côté serveur (SSR statique) .

Les composants, utilisant le mode d’affichage automatique interactif, se servent initialement du SSR interactif. 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. Les composants utilisant le mode de rendu WebAssembly interactif s’affichent uniquement de manière interactive sur le client une fois le bundle Blazor téléchargé et le runtime Blazor activé. N’oubliez pas que lorsque vous utilisez les modes de rendu automatique interactif ou WebAssembly interactif, le code de composant téléchargé vers le client n’est pas privé. Pour plus d’informations, consultez Modes de rendu ASP.NET Core Blazor.

Après avoir choisi le mode de rendu à adopter :

Ajoutez une référence de package pour le package NuGet Microsoft.AspNetCore.Components.WebAssembly.Server à l’application.

Remarque

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions du package sur NuGet.org.

Créez une application Blazor Web App donatrice pour fournir des ressources à l’application. Suivez les instructions de l’article Outils pour ASP.NET Core Blazor, en sélectionnant la prise en charge des fonctionnalités de modèle suivantes lors de la génération de l’application Blazor Web App.

Pour le nom de l’application, utilisez le même nom que l’application ASP.NET Core, afin que le balisage de nom d’application dans les composants et le balisage des espaces de noms dans le code correspondent. L’utilisation du même nom/espace de noms n’est pas strictement nécessaire, car les espaces de noms peuvent être ajustés une fois que les ressources ont été déplacées de l’application donatrice vers l’application ASP.NET Core. Toutefois, faire correspondre les espaces de noms dès le début permet de gagner du temps.

Visual Studio :

  • Pour Mode de rendu interactif, sélectionnez Automatique (Server et WebAssembly).
  • Pour Emplacement d’interactivité, sélectionnez Par page/composant.
  • Décochez la case Inclure des exemples de pages.

Interface CLI .NET :

  • Utilisez l'option -int Auto.
  • N’utilisez pas l’option -ai|--all-interactive.
  • Passez l’option -e|--empty.

À partir de l’application Blazor Web App donatrice, copiez l’intégralité du projet .Client dans le dossier solution de l’application ASP.NET Core.

Important

Ne copiez pas le dossier .Client dans le dossier du projet ASP.NET Core. La meilleure approche pour organiser des solutions .NET consiste à placer chaque projet de la solution dans son propre dossier à l’intérieur d’un dossier de solution de niveau supérieur. S’il n’existe pas de dossier de solution au-dessus du dossier du projet ASP.NET Core, créez-en un. Ensuite, copiez le dossier du projet .Client de l’application Blazor Web App donatrice et collez-le dans le dossier solution. La structure finale des dossiers de projets doit être la suivante :

  • BlazorSampleSolution (dossier de solution de niveau supérieur)
    • BlazorSample (projet ASP.NET Core d’origine)
    • BlazorSample.Client (dossier de projet .Client à partir de l’application Blazor Web App donatrice)

Vous pouvez laisser le fichier de solution ASP.NET Core dans le dossier du projet ASP.NET Core. Vous pouvez également déplacer le fichier de solution ou en créer un dans le dossier de solution de niveau supérieur tant que le projet référence correctement les fichiers projet (.csproj) des deux projets dans le dossier de solution.

Si, lorsque vous avez créé le projet donateur, vous avez donné à l’application Blazor Web App donatrice un nom identique à celui de l’application ASP.NET Core, les espaces de noms utilisés par les ressources données correspondent à ceux de l’application ASP.NET Core. Vous n’avez pas besoin d’effectuer d’autres étapes pour faire correspondre les espaces de noms. Si vous avez utilisé un autre espace de noms lors de la création du projet d’application Blazor Web App donneur, vous devez modifier les espaces de noms dans les ressources données afin qu’ils correspondent si vous souhaitez suivre le rest de ces instructions exactement comme elles sont présentées. Si les espaces de noms ne correspondent pas, vous devez soit les ajuster avant de continuer, soit les ajuster à mesure que vous suivez les instructions restantes de cette section.

Supprimez l’application Blazor Web App donatrice, car elle n’a plus aucune utilité dans ce processus.

Ajoutez le projet .Client à la solution :

  • Visual Studio : Cliquez avec le bouton droit sur la solution dans l’Explorateur de solutions et sélectionnez Ajouter>Projet existant. Accédez au dossier .Client et sélectionnez le fichier projet (.csproj).

  • Interface CLI .NET : Utilisez la commande dotnet sln add pour ajouter le projet .Client à la solution.

Ajoutez une référence de projet à partir du projet ASP.NET Core au projet client :

  • Visual Studio : Cliquez avec le bouton droit sur le projet ASP.NET Core et sélectionnez Ajouter>Référence de projet. Sélectionnez le projet .Client et sélectionnez OK.

  • Interface CLI .NET : À partir du dossier du projet ASP.NET Core, exécutez la commande suivante :

    dotnet add reference ../BlazorSample.Client/BlazorSample.Client.csproj

    La commande précédente part du principe que :

    • Le nom du fichier projet est BlazorSample.Client.csproj.
    • Le projet .Client se trouve dans un dossier BlazorSample.Client dans le dossier de la solution. Le dossier .Client est côte à côte avec le dossier du projet ASP.NET Core.

    Pour plus d’informations sur la commande dotnet add reference, consultez dotnet add reference (documentation .NET).

Apportez les modifications suivantes au fichier Program de l’application ASP.NET Core :

  • Ajoutez des services de composants WebAssembly interactifs avec AddInteractiveWebAssemblyComponents, où les services de composants Razor sont ajoutés avec AddRazorComponents.

    Pour le rendu Auto interactif :

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

    Pour le rendu WebAssembly interactif uniquement :

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

  • Ajoutez le mode de rendu WebAssembly interactif (AddInteractiveWebAssemblyRenderMode) et les assemblys supplémentaires pour le projet .Client où les composants Razor sont mappés avec MapRazorComponents.

    Pour le rendu automatique (Auto) interactif :

    app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);

    Pour le rendu WebAssembly interactif uniquement :

    app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);

    Dans les exemples précédents, changez BlazorSample.Client afin qu’il corresponde à l’espace de noms du projet .Client.

Ajoutez un dossier Pages au projet .Client.

Si le projet ASP.NET Core a un composant Counter existant :

  • Déplacez le composant vers le dossier Pages du projet .Client.
  • Supprimez la directive @rendermode en haut du fichier de composant.

Si l’application ASP.NET Core n’a pas de composant Counter, ajoutez le composant Counter suivant (Pages/Counter.razor) au projet .Client :

@page "/counter"
@rendermode InteractiveAuto

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Si l’application adopte uniquement le rendu WebAssembly interactif, supprimez la directive @rendermode et la valeur :

- @rendermode InteractiveAuto

Exécutez la solution à partir du projet d’application ASP.NET Core :

  • Visual Studio : Vérifiez que le projet ASP.NET Core est sélectionné dans l’Explorateur de solutions lors de l’exécution de l’application.

  • Interface CLI .NET : Exécutez le projet à partir du dossier du projet ASP.NET Core.

Pour charger le composant Counter, accédez à /counter.

Implémenter la disposition et les styles Blazor

Si vous le souhaitez, vous pouvez affecter un composant de disposition par défaut à l’aide du paramètre RouteView.DefaultLayout du composant RouteView.

Dans Routes.razor, l’exemple suivant utilise un composant MainLayout comme disposition par défaut :

<RouteView RouteData="routeData" DefaultLayout="typeof(MainLayout)" />

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

La disposition et les feuilles de style des modèles de projet Blazor sont disponibles à partir du référentiel GitHub dotnet/aspnetcore :

  • MainLayout.razor
  • MainLayout.razor.css
  • NavMenu.razor
  • NavMenu.razor.css

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

Selon la façon dont vous organisez vos fichiers de disposition dans l’application, vous devrez peut-être ajouter une instruction @using pour le dossier des fichiers de disposition dans le fichier _Imports.razor de l’application afin de les exposer à des fins d’utilisation dans les composants de l’application.

Il n’est pas nécessaire de référencer explicitement des feuilles de style lors de l’utilisation de l’isolation CSS. L’infrastructure Blazor regroupe automatiquement des feuilles de style de composants individuelles. La feuille de style groupée de l’application est déjà référencée dans le composant App de l’application ({ASSEMBLY NAME}.styles.css, où l’espace réservé {ASSEMBLY NAME} est le nom de l’assemblage de l’application).

Retourne RazorComponentResult à partir d’une action de contrôleur MVC

Une action de contrôleur MVC peut retourner un composant avec RazorComponentResult<TComponent>.

Components/Welcome.razor :

<PageTitle>Welcome!</PageTitle>

<h1>Welcome!</h1>

<p>@Message</p>

@code {
    [Parameter]
    public string? Message { get; set; }
}

Dans un contrôleur :

public IResult GetWelcomeComponent() => 
    new RazorComponentResult<Welcome>(new { Message = "Hello, world!" });

Seules les balises HTML du composant rendu sont retournées. Les dispositions et les balises de page HTML ne sont pas automatiquement rendues avec le composant. Pour produire une page HTML complète, l’application peut utiliser une disposition Blazor, qui fournit des balises HTML pour <html>, <head>, <body> et d’autres balises. Le composant inclut la disposition avec la directive @layoutRazor en haut du fichier de définition de composant, Welcome.razor pour l’exemple de cette section. L’exemple suivant part du principe que l’application a une disposition nommée RazorComponentResultLayout (Components/Layout/RazorComponentResultLayout.razor) :

@using BlazorSample.Components.Layout
@layout RazorComponentResultLayout

Vous pouvez éviter de placer l’instruction @using du dossier Layout dans des composants individuels en la déplaçant vers le fichier _Imports.razor de l’application.

Pour plus d’informations, consultez layouts 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

Par exemple :

@using BlazorSample.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.

Ressources supplémentaires

Prérendu des composants Razor ASP.NET Core