Создание многоразового пользовательского интерфейса с помощью проекта библиотеки классов Razor в ASP.NET Core

Автор: Рик Андерсон (Rick Anderson)

В библиотеку классов Razor (RCL) можно встроить представления, страницы, контроллеры, модели страниц, компоненты , View-компоненты и модели данных Razor. RCL можно упаковать и использовать повторно. Приложения могут включать RCL и переопределять содержащиеся в нем представления и страницы. При обнаружении представления, частичного представления или страницы Razor как в веб-приложении, так и в RCL приоритетное значение имеет разметка Razor (файл .cshtml) в веб-приложении.

Сведения о том, как интегрировать npm и webpack в процесс сборки для RCL, см. в разделе "Сборка клиентских веб-ресурсов для Razor библиотеки классов".

Создание библиотеки классов с пользовательским интерфейсом Razor

Visual Studio

• В Visual Studio выберите Создать проект.
• Выберите RazorБиблиотека классов>Далее.
• Присвойте библиотеке имя (например, RazorClassLib), >create. Чтобы избежать конфликта имени файла с созданной библиотекой представлений, проверьте, что имя библиотеки не заканчивается на .Views.
• Выберите страницы поддержки и представления, если необходимо, чтобы библиотека содержала страницы или представления. По умолчанию поддерживаются только компоненты Razor. Нажмите кнопку создания.

Шаблон библиотеки классов Razor по умолчанию служит для разработки компонентов Razor. При выборе параметра Представления и страницы поддержки поддерживаются страницы и представления. Дополнительные сведения о поддержке RCL см. в Blazorстатье "Использование компонентов ASP.NET Core Razor из Razor библиотеки классов (RCL)".

CLI для .NET

Выполните из командной строки команду dotnet new razorclasslib. Например:

dotnet new razorclasslib -o RazorUIClassLib

Шаблон Razor библиотеки классов по умолчанию предназначен для разработки компонентов Razor. Передайте параметр --support-pages-and-views (dotnet new razorclasslib --support-pages-and-views) для поддержки страниц и представлений.

Дополнительные сведения см. в разделе dotnet new. Чтобы избежать конфликта имени файла с созданной библиотекой представлений, проверьте, что имя библиотеки не заканчивается на .Views.

Добавьте файлы Razor в библиотеку RCL.

В шаблонах ASP.NET Core предполагается, что содержимое RCL находится в папке Areas. См. раздел Макет страниц RCL ниже, чтобы создать библиотеку RCL, которая отображает содержимое в ~/Pages, а не в ~/Areas/Pages.

Ссылка на содержимое RCL

На RCL могут ссылаться:

• Пакет NuGet. См. Создание пакетов NuGet, dotnet add package и Создание и публикация пакета NuGet.
• {ProjectName}.csproj. См. dotnet-add reference.

Переопределение представлений, частичных представлений и страниц

При обнаружении представления, частичного представления или страницы Razor и в веб-приложении, и в RCL приоритет имеет разметка Razor (файл .cshtml) в веб-приложении. Например, если вы добавите WebApp1/Areas/MyFeature/Pages/Page1.cshtml в WebApp1, Page1 в WebApp1 будет иметь приоритет над Page1 в RCL.

В примере загрузки переименуйте WebApp1/Areas/MyFeature2 в WebApp1/Areas/MyFeature, чтобы задать приоритет теста.

Скопируйте частичное представление RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml в WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Обновите разметку, чтобы указать новое расположение. Скомпилируйте и запустите приложение, чтобы убедиться, что используется версия частичной реализации в приложении.

Если RCL использует Razor Pages, активируйте службы и конечные точки Razor Pages в хост-приложении.

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();

Макет страниц RCL

Чтобы ссылаться на содержимое RCL так, как будто оно находится в папке Pages веб-приложения, создайте проект RCL со следующей структурой файлов:

• RazorUIClassLib/Pages
• RazorUIClassLib/Pages/Shared

Предположим, что RazorUIClassLib/Pages/Shared содержит два частичных файла: _Header.cshtml и _Footer.cshtml. В файл <partial> можно добавить теги _Layout.cshtml:

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

Добавьте файл _ViewStart.cshtml в папку Pages проекта RCL, чтобы использовать файл _Layout.cshtml из ведущего веб-приложения:

@{
    Layout = "_Layout";
}

Создание библиотеки RCL со статическими ресурсами

Для библиотеки RCL могут быть необходимы сопутствующие статические элементы, на которые может ссылаться либо сама RCL-библиотека, либо приложение, использующее эту библиотеку. ASP.NET Core позволяет создавать библиотеки RCL со статическими ресурсами, которые доступны использующим библиотеки приложениям.

Чтобы включить сопутствующие ресурсы в библиотеку RCL, создайте папку wwwroot в библиотеке классов и добавьте в нее все необходимые файлы.

При упаковке RCL все сопутствующие ресурсы в папке wwwroot автоматически включаются в пакет.

Используйте команду dotnet pack, а не NuGet.exe версии nuget pack.

Добавьте клиентские веб-ресурсы в процесс сборки

Интеграция клиентских веб-ресурсов в конвейер сборки является нетривиальной. Дополнительные сведения см. статью «Создание клиентских веб-ресурсов для библиотеки Razor классов».

Исключение статических ресурсов

Чтобы исключить статические ресурсы, добавьте путь исключения в группу свойств $(DefaultItemExcludes) в файле проекта. Записи следует разделять точкой с запятой (;).

В следующем примере таблица стилей lib.css в папкеwwwroot не считается статическим ресурсом и не включается в опубликованную библиотеку RCL:

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

Интеграция с TypeScript

Чтобы включить файлы TypeScript в библиотеку RCL, выполните указанные ниже действия.

• Подключите пакет NuGet Microsoft.TypeScript.MSBuild в проекте.

  Примечание.

  Рекомендации по добавлению пакетов в приложения .NET см. в разделе Способы установки пакетов NuGet в статье Рабочий процесс использования пакета (документация по NuGet). Проверьте правильность версий пакета на сайте NuGet.org.

• Поместите файлы TypeScript (.ts) в папку, отличную от wwwroot. Например, их можно поместить в папку Client.

• Добавьте следующую разметку в файл проекта:

  • Настройте выходные данные сборки TypeScript для папки wwwroot с помощью свойства TypescriptOutDir.
  • Включите целевой объект TypeScript в качестве зависимости целевого объекта PrepareForBuildDependsOn.
  • Удалите вывод в wwwroot folder.

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

  <PropertyGroup>
    // Markup removed for brevity.
    <TypescriptOutDir>wwwroot</TypescriptOutDir>
    <PrepareForBuildDependsOn>
      CompileTypeScriptWithTSConfig;
      GetTypeScriptOutputForPublishing;$(PrepareForBuildDependsOn)
    </PrepareForBuildDependsOn>
  </PropertyGroup>

  <ItemGroup>
    <Content Remove="wwwroot\{path-to-typescript-outputs}" />
  </ItemGroup>

</Project>

Потребляйте содержимое из связанной библиотеки RCL

Файлы в папке wwwroot библиотеки RCL доступны для самой библиотеки RCL или использующего приложения под префиксом _content/{PACKAGE ID}/. Например, библиотека с именем сборки Razor.Class.Lib и без указания <PackageId> в файле проекта приводит к формированию пути к статическому контенту в _content/Razor.Class.Lib/. При создании пакета NuGet имя сборки не совпадает с идентификатором пакета (<PackageId> в файле проекта библиотеки), используйте идентификатор пакета, как указано в файле проекта для {PACKAGE ID}.

Использующее библиотеку приложение ссылается на предоставляемые ею статические ресурсы с помощью тегов HTML <script>, <style>, <img> и других. Для приложения-потребителя необходимо включить поддержку статических файлов следующим образом:

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();

Когда приложение запускается из результата сборки (dotnet run), в среде разработки статические веб-ресурсы включаются по умолчанию. Для поддержки ресурсов в других средах при запуске из выходного пути сборки вызовите метод UseStaticWebAssets построителя узла в файле 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();

При запуске приложения из опубликованного выхода (UseStaticWebAssets) вызывать dotnet publish не нужно.

Процесс разработки нескольких проектов

Когда запускается потребляющее приложение:

• Ресурсы RCL остаются в исходных папках. Активы не перемещаются в потребляющее приложение.
• Любые изменения в папке wwwroot библиотеки RCL отражаются в приложении после перестроения RCL, причем приложение перестраивать не требуется.

При сборке библиотеки RCL создается манифест, в котором описывается расположение статических веб-ресурсов. Приложение, использующее ресурсы, считывает манифест во время выполнения, чтобы использовать компоненты из подключенных проектов и пакетов. При добавлении нового ресурса в библиотеку RCL ее необходимо перестроить, чтобы обновить манифест. Только после этого приложение сможет получить доступ к новому ресурсу.

Публикация

При публикации приложения сопутствующие ресурсы из всех связанных проектов и пакетов копируются в папку wwwroot опубликованного приложения в папке _content/{PACKAGE ID}/. При создании пакета NuGet, если имя сборки не совпадает с идентификатором пакета (<PackageId> в файле проекта библиотеки), используйте идентификатор пакета, указанный в файле проекта для {PACKAGE ID} при проверке папки wwwroot на наличие опубликованных ресурсов.

Дополнительные ресурсы

• Просмотреть или скачать образец кода (описание загрузки)

• Использование компонентов ASP.NET Core Razor из библиотеки классов Razor (RCL)

• Изоляция CSS в ASP.NET Core Blazor