Partage via


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 :

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

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 (RCL) Razor est défini par défaut sur 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 :

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 :

  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").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, « RazorClassLib »), >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 :

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 :

  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 ResolveCurrentProjectStaticWebAssets en ajoutant la cible suivante à l’intérieur d’un PropertyGroup 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 :

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ées

  • Gé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 :

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 :

  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 ResolveCurrentProjectStaticWebAssets en ajoutant la cible suivante à l’intérieur d’un PropertyGroup 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