Créer une interface utilisateur réutilisable à l’aide du projet de bibliothèque de classes Razor dans ASP.NET CoreCreate reusable UI using the Razor class library project in ASP.NET Core

Par Rick AndersonBy Rick Anderson

Les vues Razor, les pages, les contrôleurs, les modèles de page, les composants Razor, les composants de vueet les modèles de données peuvent être intégrés dans une bibliothèque de classes Razor (RCL).Razor views, pages, controllers, page models, Razor components, View components, and data models can be built into a Razor class library (RCL). La RCL peut être empaquetée et réutilisée.The RCL can be packaged and reused. Les applications peuvent inclure la RCL et remplacer les vues et les pages qu’elle contient.Applications can include the RCL and override the views and pages it contains. Quand une vue, une vue partielle ou une page Razor est présente dans l’application web et la RCL, le balisage Razor (fichier .cshtml) dans l’application web est prioritaire.When a view, partial view, or Razor Page is found in both the web app and the RCL, the Razor markup (.cshtml file) in the web app takes precedence.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Créer une bibliothèque de classes contenant l’interface utilisateur RazorCreate a class library containing Razor UI

  • Dans Visual Studio, dans le menu Fichier, sélectionnez Nouveau > Projet.From the Visual Studio File menu, select New > Project.
  • Sélectionnez Nouvelle application web ASP.NET Core.Select ASP.NET Core Web Application.
  • Nommez la bibliothèque (par exemple, « RazorClassLib ») > OK.Name the library (for example, "RazorClassLib") > OK. Pour éviter une collision de nom de fichier avec la bibliothèque de vues générée, vérifiez que le nom de la bibliothèque ne se termine pas par .Views.To avoid a file name collision with the generated view library, ensure the library name doesn't end in .Views.
  • Vérifiez ASP.NET Core 3,0 ou une version ultérieure est sélectionné.Verify ASP.NET Core 3.0 or later is selected.
  • Sélectionnez bibliothèque de classes Razor > OK.Select Razor Class Library > OK.

Le modèle de bibliothèque de classes Razor (RCL) est par défaut le développement de composants Razor par défaut.The Razor class library (RCL) template defaults to Razor component development by default. Une option de modèle dans Visual Studio fournit la prise en charge des modèles pour les pages et les vues.A template option in Visual Studio provides template support for pages and views.

Ajoutez des fichiers Razor à la RCL.Add Razor files to the RCL.

Les modèles ASP.NET Core supposent que le contenu RCL se trouve dans le zones dossier.The ASP.NET Core templates assume the RCL content is in the Areas folder. Consultez RCL pages layout pour créer un RCL qui expose du contenu dans ~/Pages plutôt que ~/Areas/Pages.See RCL Pages layout to create an RCL that exposes content in ~/Pages rather than ~/Areas/Pages.

Référencer le contenu RCLReference RCL content

La RCL peut être référencée par :The RCL can be referenced by:

Substituer des vues, des vues partielles et des pagesOverride views, partial views, and pages

Quand une vue, une vue partielle ou une page Razor est présente dans l’application web et la RCL, le balisage Razor (fichier .cshtml) dans l’application web est prioritaire.When a view, partial view, or Razor Page is found in both the web app and the RCL, the Razor markup (.cshtml file) in the web app takes precedence. Par exemple, ajoutez application Web 1/Areas/MyFeature/pages/Page1. cshtml à application Web 1, et Page1 dans le application Web 1 aura priorité sur Page1 dans le RCL.For example, add WebApp1/Areas/MyFeature/Pages/Page1.cshtml to WebApp1, and Page1 in the WebApp1 will take precedence over Page1 in the RCL.

Dans l’exemple proposé sous forme de téléchargement, renommez WebApp1/Areas/MyFeature2 en WebApp1/Areas/MyFeature pour tester la priorité.In the sample download, rename WebApp1/Areas/MyFeature2 to WebApp1/Areas/MyFeature to test precedence.

Copiez la vue partielle RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml dans WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml.Copy the RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml partial view to WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Mettez à jour le balisage pour indiquer le nouvel emplacement.Update the markup to indicate the new location. Générez et exécutez l’application pour vérifier que la version de la vue partielle de l’application est utilisée.Build and run the app to verify the app's version of the partial is being used.

Disposition des Pages de RCLRCL Pages layout

Pour référence RCL de contenu comme s’il faisait partie de l’application web Pages dossier, créez le projet RCL avec la structure de fichier suivante :To reference RCL content as though it is part of the web app's Pages folder, create the RCL project with the following file structure:

  • RazorUIClassLib/PagesRazorUIClassLib/Pages
  • RazorUIClassLib/Pages/SharedRazorUIClassLib/Pages/Shared

Supposons que RazorUIClassLib/Pages/Shared contient deux fichiers partielles : _Header.cshtml et _Footer.cshtml.Suppose RazorUIClassLib/Pages/Shared contains two partial files: _Header.cshtml and _Footer.cshtml. Le <partial> balises peut être ajoutés à _Layout.cshtml fichier :The <partial> tags could be added to _Layout.cshtml file:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

Créer un RCL avec des ressources statiquesCreate an RCL with static assets

Un RCL peut nécessiter des ressources statiques auxiliaires qui peuvent être référencées par l’application consommatrice de RCL.An RCL may require companion static assets that can be referenced by the consuming app of the RCL. ASP.NET Core permet de créer des RCLs qui incluent des ressources statiques disponibles pour une application consommatrice.ASP.NET Core allows creating RCLs that include static assets that are available to a consuming app.

Pour inclure des ressources d’accompagnement dans le cadre d’un RCL, créez un dossier wwwroot dans la bibliothèque de classes et incluez tous les fichiers nécessaires dans ce dossier.To include companion assets as part of an RCL, create a wwwroot folder in the class library and include any required files in that folder.

Lors de la compression d’un RCL, toutes les ressources associées dans le dossier wwwroot sont automatiquement incluses dans le package.When packing an RCL, all companion assets in the wwwroot folder are automatically included in the package.

Exclure des ressources statiquesExclude static assets

Pour exclure des ressources statiques, ajoutez le chemin d’exclusion souhaité au groupe de propriétés $(DefaultItemExcludes) dans le fichier projet.To exclude static assets, add the desired exclusion path to the $(DefaultItemExcludes) property group in the project file. Séparez les entrées par un point-virgule (;).Separate entries with a semicolon (;).

Dans l’exemple suivant, la feuille de style lib. CSS du dossier wwwroot n’est pas considérée comme une ressource statique et n’est pas incluse dans le RCL publié :In the following example, the lib.css stylesheet in the wwwroot folder isn't considered a static asset and isn't included in the published RCL:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Intégration de la machine à écrireTypescript integration

Pour inclure des fichiers de machine à écrire dans un RCL :To include TypeScript files in an RCL:

  1. Placez les fichiers de machine à écrire ( . TS) en dehors du dossier wwwroot .Place the TypeScript files (.ts) outside of the wwwroot folder. Par exemple, placez les fichiers dans un dossier client .For example, place the files in a Client folder.

  2. Configurez la sortie de génération de machine à écrire pour le dossier wwwroot .Configure the TypeScript build output for the wwwroot folder. Définissez la propriété TypescriptOutDir à l’intérieur d’une PropertyGroup dans le fichier projet :Set the TypescriptOutDir property inside of a PropertyGroup in the project file:

    <TypescriptOutDir>wwwroot</TypescriptOutDir>
    
  3. Incluez la cible de la machine à écrire en tant que dépendance de la cible ResolveCurrentProjectStaticWebAssets en ajoutant la cible suivante à l’intérieur d’une PropertyGroup dans le fichier projet :Include the TypeScript target as a dependency of the ResolveCurrentProjectStaticWebAssets target by adding the following target inside of a PropertyGroup in the project file:

CompileTypeScript; $(ResolveCurrentProjectStaticWebAssetsInputs) ```

Consommer du contenu à partir d’un RCL référencéConsume content from a referenced RCL

Les fichiers inclus dans le dossier wwwroot du RCL sont exposés à l’application consommatrice sous le préfixe _content/{LIBRARY NAME}/.The files included in the wwwroot folder of the RCL are exposed to the consuming app under the prefix _content/{LIBRARY NAME}/. Par exemple, une bibliothèque nommée Razor. class. lib génère un chemin d’accès au contenu statique à _content/Razor.Class.Lib/.For example, a library named Razor.Class.Lib results in a path to static content at _content/Razor.Class.Lib/.

L’application consommatrice fait référence aux ressources statiques fournies par la bibliothèque avec <script>, <style>, <img> et d’autres balises HTML.The consuming app references static assets provided by the library with <script>, <style>, <img>, and other HTML tags. L’application consommatrice doit avoir la prise en charge des fichiers statiques activée dans Startup.Configure :The consuming app must have static file support enabled in Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

    app.UseStaticFiles();

    ...
}

Lors de l’exécution de l’application consommatrice à partir de la sortie de génération (dotnet run), les ressources Web statiques sont activées par défaut dans l’environnement de développement.When running the consuming app from build output (dotnet run), static web assets are enabled by default in the Development environment. Pour prendre en charge les ressources dans d’autres environnements lors de l’exécution à partir de la sortie de génération, appelez UseStaticWebAssets sur le générateur d’ordinateur hôte dans Program.cs:To support assets in other environments when running from build output, call UseStaticWebAssets on the host builder in Program.cs:

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStaticWebAssets();
                webBuilder.UseStartup<Startup>();
            });
}

L’appel de UseStaticWebAssets n’est pas nécessaire lors de l’exécution d’une application à partir de la sortie publiée (dotnet publish).Calling UseStaticWebAssets isn't required when running an app from published output (dotnet publish).

Déroulement du développement de projets multiplesMulti-project development flow

Lorsque l’application consommatrice s’exécute :When the consuming app runs:

  • Les ressources du RCL restent dans leurs dossiers d’origine.The assets in the RCL stay in their original folders. Les ressources ne sont pas déplacées vers l’application consommatrice.The assets aren't moved to the consuming app.
  • Toute modification dans le dossier wwwroot de RCL est reflétée dans l’application consommatrice une fois que le RCL est reconstruit et sans régénérer l’application consommateur.Any change within the RCL's wwwroot folder is reflected in the consuming app after the RCL is rebuilt and without rebuilding the consuming app.

Lorsque le RCL est généré, un manifeste qui décrit les emplacements des ressources Web statiques est généré.When the RCL is built, a manifest is produced that describes the static web asset locations. L’application consommatrice lit le manifeste au moment de l’exécution pour consommer les ressources des packages et des projets référencés.The consuming app reads the manifest at runtime to consume the assets from referenced projects and packages. Lorsqu’un nouvel élément multimédia est ajouté à un RCL, le RCL doit être régénéré pour mettre à jour son manifeste avant qu’une application consommatrice puisse accéder au nouvel élément multimédia.When a new asset is added to an RCL, the RCL must be rebuilt to update its manifest before a consuming app can access the new asset.

PublierPublish

Lorsque l’application est publiée, les ressources d’accompagnement de tous les packages et projets référencés sont copiées dans le dossier wwwroot de l’application publiée sous _content/{LIBRARY NAME}/.When the app is published, the companion assets from all referenced projects and packages are copied into the wwwroot folder of the published app under _content/{LIBRARY NAME}/.

Les vues Razor, les pages, les contrôleurs, les modèles de page, les composants Razor, les composants de vueet les modèles de données peuvent être intégrés dans une bibliothèque de classes Razor (RCL).Razor views, pages, controllers, page models, Razor components, View components, and data models can be built into a Razor class library (RCL). La RCL peut être empaquetée et réutilisée.The RCL can be packaged and reused. Les applications peuvent inclure la RCL et remplacer les vues et les pages qu’elle contient.Applications can include the RCL and override the views and pages it contains. Quand une vue, une vue partielle ou une page Razor est présente dans l’application web et la RCL, le balisage Razor (fichier .cshtml) dans l’application web est prioritaire.When a view, partial view, or Razor Page is found in both the web app and the RCL, the Razor markup (.cshtml file) in the web app takes precedence.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Créer une bibliothèque de classes contenant l’interface utilisateur RazorCreate a class library containing Razor UI

  • Dans Visual Studio, dans le menu Fichier, sélectionnez Nouveau > Projet.From the Visual Studio File menu, select New > Project.
  • Sélectionnez Nouvelle application web ASP.NET Core.Select ASP.NET Core Web Application.
  • Nommez la bibliothèque (par exemple, « RazorClassLib ») > OK.Name the library (for example, "RazorClassLib") > OK. Pour éviter une collision de nom de fichier avec la bibliothèque de vues générée, vérifiez que le nom de la bibliothèque ne se termine pas par .Views.To avoid a file name collision with the generated view library, ensure the library name doesn't end in .Views.
  • Vérifiez que ASP.NET Core 2.1 ou ultérieur est sélectionné.Verify ASP.NET Core 2.1 or later is selected.
  • Sélectionnez bibliothèque de classes Razor > OK.Select Razor Class Library > OK.

Un RCL a le fichier projet suivant :An RCL has the following project file:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

Ajoutez des fichiers Razor à la RCL.Add Razor files to the RCL.

Les modèles ASP.NET Core supposent que le contenu RCL se trouve dans le zones dossier.The ASP.NET Core templates assume the RCL content is in the Areas folder. Consultez RCL pages layout pour créer un RCL qui expose du contenu dans ~/Pages plutôt que ~/Areas/Pages.See RCL Pages layout to create an RCL that exposes content in ~/Pages rather than ~/Areas/Pages.

Référencer le contenu RCLReference RCL content

La RCL peut être référencée par :The RCL can be referenced by:

Procédure pas à pas : Créer un projet RCL et l’utiliser à partir d’un projet Razor PagesWalkthrough: Create an RCL project and use from a Razor Pages project

Vous pouvez télécharger et tester le projet complet au lieu de le créer de toutes pièces.You can download the complete project and test it rather than creating it. L’exemple proposé sous forme de téléchargement contient du code et des liens supplémentaires qui facilitent le test du projet.The sample download contains additional code and links that make the project easy to test. Si vous souhaitez commenter le mode d’obtention des exemples (téléchargement ou création au moyen d’instructions détaillées), entrez vos commentaires dans ce problème GitHub.You can leave feedback in this GitHub issue with your comments on download samples versus step-by-step instructions.

Tester l’application téléchargéeTest the download app

Si vous n’avez pas téléchargé l’application complète et que vous souhaitez créer le projet pas à pas, passez à la section suivante.If you haven't downloaded the completed app and would rather create the walkthrough project, skip to the next section.

Ouvrez le fichier .sln dans Visual Studio.Open the .sln file in Visual Studio. Exécuter l’application.Run the app.

Suivez les instructions contenues dans Test WebApp1Follow the instructions in Test WebApp1

Créer un RCLCreate an RCL

Dans cette section, un RCL est créé.In this section, an RCL is created. Des fichiers Razor sont ajoutés à la RCL.Razor files are added to the RCL.

Créez le projet RCL :Create the RCL project:

  • Dans Visual Studio, dans le menu Fichier, sélectionnez Nouveau > Projet.From the Visual Studio File menu, select New > Project.
  • Sélectionnez Nouvelle application web ASP.NET Core.Select ASP.NET Core Web Application.
  • Nommez l’application RazorUIClassLib > OK.Name the app RazorUIClassLib > OK.
  • Vérifiez que ASP.NET Core 2.1 ou ultérieur est sélectionné.Verify ASP.NET Core 2.1 or later is selected.
  • Sélectionnez bibliothèque de classes Razor > OK.Select Razor Class Library > OK.
  • Ajoutez un fichier de vue partielle Razor nommé RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml.Add a Razor partial view file named RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml.

Ajouter les fichiers Razor et des dossiers au projetAdd Razor files and folders to the project

  • Remplacez le balisage dans RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml par le code suivant :Replace the markup in RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml with the following code:

    <h3>_Message.cshtml partial view.</h3>
    
    <p>RazorUIClassLib\Areas\MyFeature\Pages\Shared\_Message.cshtml</p>
    
  • Remplacez le balisage dans RazorUIClassLib/Areas/MyFeature/Pages/Page1.cshtml par le code suivant :Replace the markup in RazorUIClassLib/Areas/MyFeature/Pages/Page1.cshtml with the following code:

    @page
    @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
    
    <h2>Hello from a Razor UI class library!</h2>
    <p> From  RazorUIClassLib\Areas\MyFeature\Pages\Page1.cshtml</p>
    
    <partial name="_Message" />
    

    @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers est nécessaire pour utiliser la vue partielle (<partial name="_Message" />).@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers is required to use the partial view (<partial name="_Message" />). Au lieu d’inclure la directive @addTagHelper, vous pouvez ajouter un fichier _ViewImports.cshtml.Rather than including the @addTagHelper directive, you can add a _ViewImports.cshtml file. Exemple :For example:

    dotnet new viewimports -o RazorUIClassLib/Areas/MyFeature/Pages
    

    Pour plus d’informations sur _ViewImports.cshtml, consultez importation de Directives partagéesFor more information on _ViewImports.cshtml, see Importing Shared Directives

  • Générez la bibliothèque de classes pour vérifier l’absence d’erreurs de compilateur :Build the class library to verify there are no compiler errors:

    dotnet build RazorUIClassLib
    

La sortie de build contient RazorUIClassLib.dll et RazorUIClassLib.Views.dll.The build output contains RazorUIClassLib.dll and RazorUIClassLib.Views.dll. RazorUIClassLib.Views.dll contient le contenu Razor compilé.RazorUIClassLib.Views.dll contains the compiled Razor content.

Utiliser la bibliothèque de l’interface utilisateur Razor à partir d’un projet Razor PagesUse the Razor UI library from a Razor Pages project

Créez l’application web Razor Pages :Create the Razor Pages web app:

  • Dans Explorateur de solutions, cliquez avec le bouton droit sur la solution > Ajouter > nouveau projet.From Solution Explorer, right-click the solution > Add > New Project.

  • Sélectionnez Nouvelle application web ASP.NET Core.Select ASP.NET Core Web Application.

  • Nommez l’application WebApp1.Name the app WebApp1.

  • Vérifiez que ASP.NET Core 2.1 ou ultérieur est sélectionné.Verify ASP.NET Core 2.1 or later is selected.

  • Sélectionnez application Web > OK.Select Web Application > OK.

  • Dans l’Explorateur de solutions, cliquez avec le bouton droit sur WebApp1, puis sélectionnez Définir comme projet de démarrage.From Solution Explorer, right-click on WebApp1 and select Set as StartUp Project.

  • Dans Explorateur de solutions, cliquez avec le bouton droit sur application Web 1 et sélectionnez dépendances de build > dépendances de projet.From Solution Explorer, right-click on WebApp1 and select Build Dependencies > Project Dependencies.

  • Cochez RazorUIClassLib comme dépendance de WebApp1.Check RazorUIClassLib as a dependency of WebApp1.

  • Dans Explorateur de solutions, cliquez avec le bouton droit sur application Web 1 et sélectionnez Ajouter > référence.From Solution Explorer, right-click on WebApp1 and select Add > Reference.

  • Dans la boîte de dialogue Gestionnaire de références , activez la case à cocher RazorUIClassLib > OK.In the Reference Manager dialog, check RazorUIClassLib > OK.

Exécuter l’application.Run the app.

Tester WebApp1Test WebApp1

Accédez à /MyFeature/Page1 pour vérifier que la bibliothèque de classes de l’interface utilisateur Razor est en cours d’utilisation.Browse to /MyFeature/Page1 to verify that the Razor UI class library is in use.

Substituer des vues, des vues partielles et des pagesOverride views, partial views, and pages

Quand une vue, une vue partielle ou une page Razor est présente dans l’application web et la RCL, le balisage Razor (fichier .cshtml) dans l’application web est prioritaire.When a view, partial view, or Razor Page is found in both the web app and the RCL, the Razor markup (.cshtml file) in the web app takes precedence. Par exemple, ajoutez application Web 1/Areas/MyFeature/pages/Page1. cshtml à application Web 1, et Page1 dans le application Web 1 aura priorité sur Page1 dans le RCL.For example, add WebApp1/Areas/MyFeature/Pages/Page1.cshtml to WebApp1, and Page1 in the WebApp1 will take precedence over Page1 in the RCL.

Dans l’exemple proposé sous forme de téléchargement, renommez WebApp1/Areas/MyFeature2 en WebApp1/Areas/MyFeature pour tester la priorité.In the sample download, rename WebApp1/Areas/MyFeature2 to WebApp1/Areas/MyFeature to test precedence.

Copiez la vue partielle RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml dans WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml.Copy the RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml partial view to WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Mettez à jour le balisage pour indiquer le nouvel emplacement.Update the markup to indicate the new location. Générez et exécutez l’application pour vérifier que la version de la vue partielle de l’application est utilisée.Build and run the app to verify the app's version of the partial is being used.

Disposition des Pages de RCLRCL Pages layout

Pour référence RCL de contenu comme s’il faisait partie de l’application web Pages dossier, créez le projet RCL avec la structure de fichier suivante :To reference RCL content as though it is part of the web app's Pages folder, create the RCL project with the following file structure:

  • RazorUIClassLib/PagesRazorUIClassLib/Pages
  • RazorUIClassLib/Pages/SharedRazorUIClassLib/Pages/Shared

Supposons que RazorUIClassLib/Pages/Shared contient deux fichiers partielles : _Header.cshtml et _Footer.cshtml.Suppose RazorUIClassLib/Pages/Shared contains two partial files: _Header.cshtml and _Footer.cshtml. Le <partial> balises peut être ajoutés à _Layout.cshtml fichier :The <partial> tags could be added to _Layout.cshtml file:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>