Créez une interface utilisateur réutilisable à l’aide du projet de bibliothèque de classes Razor dans ASP.NET Core

Par Rick Anderson

Les vues Razor, pages, contrôleurs, modèles de page, composants Razor, composants de vue et modèles de données peuvent être intégrés à une bibliothèque de classes Razor (RCL). La RCL peut être empaquetée et réutilisée. Les applications peuvent inclure la RCL et remplacer les vues et les pages qu’elle contient. 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.

Pour plus d’informations sur l’intégration de npm et webpack dans le processus de génération d’une bibliothèque de classes Razor, consultez Générer des ressources web clientes pour votre bibliothèque de classes Razor.

Créer une bibliothèque de classes contenant l’interface utilisateur Razor

Visual Studio

• Dans Visual Studio, sélectionnez Créer un nouveau projet.
• Sélectionnez Bibliothèque de classesRazor>Suivant.
• Nommez la bibliothèque (par exemple, « RazorClassLib »), >Créer. 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.
• Sélectionnez Prendre en charge les pages et les vues si vous souhaitez que la bibliothèque contienne des pages ou des vues. Par défaut, seuls les composants Razor sont pris en charge. Sélectionnez Create (Créer).

Le modèle de bibliothèque de classes Razor (RCL) est défini par défaut sur le développement de composants Razor. L’option Prise en charge des pages et vues prend en charge les pages et les vues. Pour plus d'informations sur la prise en charge des RCL dans Blazor, consultez Consommer des composants Razor ASP.NET Core à partir d'une bibliothèque de classes Razor (RCL).

CLI .NET Core

À partir de la ligne de commande, exécutez dotnet new razorclasslib. Par exemple :

dotnet new razorclasslib -o RazorUIClassLib

Le modèle de bibliothèque de classes Razor (RCL) est défini par défaut sur le développement de composants Razor. Transmettez l’option --support-pages-and-views (dotnet new razorclasslib --support-pages-and-views) pour fournir une prise en charge des pages et des vues.

Pour plus d’informations, consultez dotnet new. 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.

Ajoutez des fichiers Razor à la RCL.

Les modèles ASP.NET Core supposent que le contenu de la RCL se trouve dans le dossier Areas. Consultez la disposition Pages RCL ci-dessous pour créer une RCL qui expose du contenu dans ~/Pages plutôt que dans ~/Areas/Pages.

Contenu de la RCL de référence

La RCL peut être référencée par :

• Un package NuGet. Consultez Création de packages NuGet, dotnet add package et Créer et publier un package NuGet.
• {ProjectName}.csproj. Consultez dotnet-add reference.

Substituer des vues, des vues partielles et des 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. Par exemple, ajouter WebApp1/Areas/MyFeature/Pages/Page1.cshtml à WebApp1 et Page1 dans WebApp1 est prioritaire sur Page1 dans la RCL.

Dans l’échantillon de téléchargement, renommez WebApp1/Areas/MyFeature2 en WebApp1/Areas/MyFeature pour tester la priorité.

Copiez l’affichage partiel RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml dans WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Mettez à jour le balisage pour indiquer le nouvel emplacement. Générez et exécutez l’application pour vérifier que la version de la vue partielle de l’application est utilisée.

Si la RCL utilise Pages Razor, activez les services et points de terminaison Pages Razor dans l’application d’hébergement :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Disposition de pages de la RCL

Pour référencer du contenu de la RCL comme s’il faisait partie du dossier de l’application web Pages, créez le projet RCL avec la structure de fichiers suivante :

• RazorUIClassLib/Pages
• RazorUIClassLib/Pages/Shared

Supposons que RazorUIClassLib/Pages/Shared contienne deux fichiers partiels : _Header.cshtml et _Footer.cshtml. Les balises <partial> peuvent être ajoutées au fichier _Layout.cshtml :

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

Ajoutez le fichier _ViewStart.cshtml au dossier Pages du projet RCL pour utiliser le fichier _Layout.cshtml de l’application web hôte :

@{
    Layout = "_Layout";
}

Créer une RCL avec des ressources statiques

Une RCL peut nécessiter des ressources statiques complémentaires qui peuvent être référencées par la RCL ou par l’application consommatrice de la RCL. ASP.NET Core permet de créer des listes de contrôle d’accès qui incluent des ressources statiques disponibles pour une application consommatrice.

Pour inclure des ressources complémentaires dans le cadre d’une RCL, créez un dossier wwwroot dans la bibliothèque de classes et incluez les fichiers requis dans ce dossier.

Lors de l’empaquetage d’une RCL, toutes les ressources complémentaires du dossier wwwroot sont automatiquement incluses dans le package.

Utilisez la commande dotnet pack plutôt que la version nuget pack NuGet.exe.

Ajouter des ressources web clientes au processus de génération

L’intégration de ressources web clientes au pipeline de build n’est pas un élément non dérivé. Pour plus d’informations, consultez Créer des ressources web clientes pour votre bibliothèque de classes Razor.

Exclure les ressources statiques

Pour exclure les ressources statiques, ajoutez le chemin d’accès d’exclusion souhaité au groupe de propriétés $(DefaultItemExcludes) dans le fichier projet. Séparez les entrées avec un point-virgule (;).

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 la RCL publiée :

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

Intégration de TypeScript

Pour inclure des fichiers TypeScript dans une RCL :

1. Référencez le package NuGet Microsoft.TypeScript.MSBuild dans le projet.

   Notes

   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.

2. Placez les fichiers TypeScript (.ts) en dehors du dossier wwwroot. Par exemple, placez les fichiers dans un dossier Client.

3. Configurez la sortie de la build TypeScript pour le dossier wwwroot. Définissez la propriété TypescriptOutDir à l’intérieur d’un PropertyGroup dans le fichier projet :

   <TypescriptOutDir>wwwroot</TypescriptOutDir>
   

4. Incluez la cible TypeScript en tant que dépendance de la cible PrepareForBuildDependsOn en ajoutant la cible suivante à l’intérieur d’un PropertyGroup dans le fichier projet :

   <PrepareForBuildDependsOn>
     CompileTypeScript;
     GetTypeScriptOutputForPublishing;$(PrepareForBuildDependsOn)
   </PrepareForBuildDependsOn>
   

Consommer du contenu à partir d’une RCL référencée

Les fichiers inclus dans le dossier wwwroot de la RCL sont exposés à la RCL ou à l’application consommatrice sous le préfixe _content/{PACKAGE ID}/. Par exemple, une bibliothèque avec un nom d’assembly de Razor.Class.Lib et sans <PackageId> spécifié dans son fichier projet génère un chemin d’accès au contenu statique à l’emplacement _content/Razor.Class.Lib/. Lorsque vous produisez un package NuGet et que le nom de l’assembly n’est pas identique à l’ID de package (<PackageId> dans le fichier projet de la bibliothèque), utilisez l’ID de package comme spécifié dans le fichier projet pour {PACKAGE ID}.

L’application consommatrice fait référence aux ressources statiques fournies par la bibliothèque avec <script>, <style>, <img>et d’autres balises HTML. La prise en charge des fichiers statiques de l’application consommatrice doit être activée dans :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.MapRazorPages();
app.Run();

Lors de l’exécution de l’application consommatrice à partir de la sortie de build (dotnet run), les ressources web statiques sont activées par défaut dans l’environnement de développement. Pour prendre en charge les ressources dans d’autres environnements lors de l’exécution à partir de la sortie de build, appelez UseStaticWebAssets le générateur d’hôte dans Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseWebRoot("wwwroot");
builder.WebHost.UseStaticWebAssets();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Appeler UseStaticWebAssets n’est pas obligatoire lors de l’exécution d’une application à partir d’une sortie publiée (dotnet publish).

Flux de développement multi-projets

Lorsque l’application consommatrice s’exécute :

• Les ressources de la RCL restent dans leurs dossiers d’origine. Les ressources ne sont pas déplacées vers l’application consommatrice.
• Toute modification dans le dossier RCL wwwroot est répercutée dans l’application consommatrice après la reconstruction de la RCL et sans regénérer l’application consommatrice.

Lorsque la RCL est générée, un manifeste l’est aussi, il décrit les emplacements des ressources web statiques. L’application consommatrice lit le manifeste au moment de l’exécution pour consommer les ressources des projets et packages référencés. Lorsqu’une nouvelle ressource est ajoutée à une RCL, la bibliothèque RCL doit être reconstruite pour mettre à jour son manifeste avant qu’une application consommatrice puisse accéder à la nouvelle ressource.

Publier

Lorsque l’application est publiée, les ressources complémentaires de tous les projets et packages référencés sont copiées dans le dossier wwwroot de l’application publiée sous _content/{PACKAGE ID}/. Lorsque vous produisez un package NuGet et que le nom de l’assembly n’est pas le même que l’ID de package (<PackageId> dans le fichier projet de la bibliothèque), utilisez l’ID de package comme spécifié dans le fichier projet pour {PACKAGE ID} lors de l’examen du dossier wwwroot des ressources publiées.

Ressources supplémentaires

• Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

• Consommer des composants Razor ASP.NET Core d’une bibliothèque de classes Razor (RCL)

• Isolation CSS Blazor ASP.NET Core