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 RCL, 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
- 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 Créer.
Le modèle de bibliothèque de classes Razor 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).
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 :
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.
Placez les fichiers TypeScript (
.ts
) en dehors du dossierwwwroot
. Par exemple, placez les fichiers dans un dossierClient
.Configurez la sortie de la build TypeScript pour le dossier
wwwroot
. Définissez la propriétéTypescriptOutDir
à l’intérieur d’unPropertyGroup
dans le fichier projet :<TypescriptOutDir>wwwroot</TypescriptOutDir>
Incluez la cible TypeScript en tant que dépendance de la cible
PrepareForBuildDependsOn
en ajoutant la cible suivante à l’intérieur d’unPropertyGroup
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
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
- 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 Pages et vues de prise en charge si vous avez besoin de prendre en charge les vues. Par défaut, seules les classes Razor sont prises 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.
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.
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 :
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.
Placez les fichiers TypeScript (
.ts
) en dehors du dossierwwwroot
. Par exemple, placez les fichiers dans un dossierClient
.Configurez la sortie de la build TypeScript pour le dossier
wwwroot
. Définissez la propriétéTypescriptOutDir
à l’intérieur d’unPropertyGroup
dans le fichier projet :<TypescriptOutDir>wwwroot</TypescriptOutDir>
Incluez la cible TypeScript en tant que dépendance de la cible
PrepareForBuildDependsOn
en ajoutant la cible suivante à l’intérieur d’unPropertyGroup
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").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();
Remarque : .NET 6 nécessite uniquement l’appel builder.WebHost.UseWebRoot("wwwroot").UseStaticWebAssets
. Pour plus d’informations, consultez ce problème GitHub.
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
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.
Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
Créer une bibliothèque de classes contenant l’interface utilisateur Razor
- Dans Visual Studio, sélectionnez Créer un projet.
- Sélectionnez Bibliothèque de classesRazor>Suivant.
- Nommez la bibliothèque (par exemple, «Razor ClassLib »), >Créer>Suivant. 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 la version cible de .Net Framework. Consultez ☑ la prise en charge des pages et des vues pour prendre en charge les 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.
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 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.
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.
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 :
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.
Placez les fichiers TypeScript (
.ts
) en dehors du dossierwwwroot
. Par exemple, placez les fichiers dans un dossierClient
.Configurez la sortie de la build TypeScript pour le dossier
wwwroot
. Définissez la propriétéTypescriptOutDir
à l’intérieur d’unPropertyGroup
dans le fichier projet :<TypescriptOutDir>wwwroot</TypescriptOutDir>
Incluez la cible TypeScript en tant que dépendance de la cible
ResolveCurrentProjectStaticWebAssets
en ajoutant la cible suivante à l’intérieur d’unPropertyGroup
dans le fichier projet :<ResolveCurrentProjectStaticWebAssetsInputsDependsOn> CompileTypeScript; $(ResolveCurrentProjectStaticWebAssetsInputs) </ResolveCurrentProjectStaticWebAssetsInputsDependsOn>
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 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 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
:
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>();
});
}
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
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.
Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
Créer une bibliothèque de classes contenant l’interface utilisateur Razor
- Dans Visual Studio, dans le menu Fichier, sélectionnez Nouveau>Projet.
- Sélectionnez Application web ASP.NET Core.
- Nommez la bibliothèque (par exemple, « 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
. - Vérifiez que ASP.NET Core 2.1 ou ultérieur est sélectionné.
- Sélectionnez Razor bibliothèque de classes>OK.
Un RCL possède le fichier projet suivant :
<Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
<AddRazorSupportForMvc>true</AddRazorSupportForMvc>
</PropertyGroup>
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
</Project>
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 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.
Procédure pas à pas : créer un projet RCL et l’utiliser à partir d’un projet Pages Razor
Vous pouvez télécharger et tester le projet complet au lieu de le créer de toutes pièces. L’exemple proposé sous forme de téléchargement contient du code et des liens supplémentaires qui facilitent le test du projet. 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.
Tester l’application téléchargée
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.
Ouvrez le fichier .sln
dans Visual Studio. Exécutez l'application.
Suivez les instructions contenues dans Test WebApp1
Créer une RCL
Dans cette section, une RCL est créée. Des fichiers Razor sont ajoutés à la RCL.
Créez le projet RCL :
- Dans Visual Studio, dans le menu Fichier, sélectionnez Nouveau>Projet.
- Sélectionnez Application web ASP.NET Core.
- Nommez l’application RazorUIClassLib>OK.
- Vérifiez que ASP.NET Core 2.1 ou ultérieur est sélectionné.
- Sélectionnez Razor bibliothèque de classes>OK.
- Ajoutez un fichier d’affichage partiel Razor nommé
RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml
.
Ajouter des fichiers et des dossiers Razor au projet
Remplacez la balise dans
RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml
par le code suivant :<h3>_Message.cshtml partial view.</h3> <p>RazorUIClassLib\Areas\MyFeature\Pages\Shared\_Message.cshtml</p>
Remplacez la balise dans
RazorUIClassLib/Areas/MyFeature/Pages/Page1.cshtml
par le code suivant :@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" />
). Au lieu d’inclure la directive@addTagHelper
, vous pouvez ajouter un fichier_ViewImports.cshtml
. Par exemple :dotnet new viewimports -o RazorUIClassLib/Areas/MyFeature/Pages
Pour plus d’informations sur
_ViewImports.cshtml
, consultez Importation de directives partagéesGénérez la bibliothèque de classes pour vérifier l’absence d’erreurs de compilateur :
dotnet build RazorUIClassLib
La sortie de build contient RazorUIClassLib.dll
et RazorUIClassLib.Views.dll
. RazorUIClassLib.Views.dll
contient le contenu compilé Razor.
Utiliser la bibliothèque de l’interface utilisateur Razor à partir d’un projet Pages Razor
Créez l’application web Pages Razor :
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur la solution >Ajouter>Nouveau projet.
Sélectionnez Application web ASP.NET Core.
Nommez l’application WebApp1.
Vérifiez que ASP.NET Core 2.1 ou ultérieur est sélectionné.
Sélectionnez Application web>OK.
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur WebApp1, puis sélectionnez Définir comme projet de démarrage.
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur WebApp1, puis sélectionnez Dépendances de build>Dépendances du projet.
Cochez RazorUIClassLib comme dépendance de WebApp1.
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur WebApp1, puis sélectionnez Ajouter>Référence.
Dans la boîte de dialogue Gestionnaire de références, cochez RazorUIClassLib>OK.
Exécutez l'application.
Tester WebApp1
Accédez à /MyFeature/Page1
pour vérifier que la bibliothèque de classes d’interface utilisateur Razor est en cours d’utilisation.
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.
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>
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.
Affichez ou téléchargez l’exemple de code (procédure de téléchargement)
Créer une bibliothèque de classes contenant l’interface utilisateur Razor
- 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 Pages et vues de prise en charge si vous avez besoin de prendre en charge les vues. Par défaut, seules les classes Razor sont prises 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.
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 :
public void ConfigureServices(IServiceCollection services)
{
services.AddControllersWithViews();
services.AddRazorPages();
}
public void Configure(IApplicationBuilder app)
{
app.UseStaticFiles();
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
endpoints.MapRazorPages();
});
}
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.
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 :
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.
Placez les fichiers TypeScript (
.ts
) en dehors du dossierwwwroot
. Par exemple, placez les fichiers dans un dossierClient
.Configurez la sortie de la build TypeScript pour le dossier
wwwroot
. Définissez la propriétéTypescriptOutDir
à l’intérieur d’unPropertyGroup
dans le fichier projet :<TypescriptOutDir>wwwroot</TypescriptOutDir>
Incluez la cible TypeScript en tant que dépendance de la cible
ResolveCurrentProjectStaticWebAssets
en ajoutant la cible suivante à l’intérieur d’unPropertyGroup
dans le fichier projet :<ResolveCurrentProjectStaticWebAssetsInputsDependsOn> CompileTypeScript; $(ResolveCurrentProjectStaticWebAssetsInputs) </ResolveCurrentProjectStaticWebAssetsInputsDependsOn>
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 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 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
:
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>();
});
}
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.