Membuat UI yang dapat digunakan kembali menggunakan Razor proyek pustaka kelas di ASP.NET Core

Oleh Rick Anderson

Razor tampilan, halaman, pengendali, model halaman, Razor komponen, komponen tampilan, dan model data dapat dibangun ke dalam Razor pustaka kelas (RCL). RCL dapat dikemas dan digunakan kembali. Aplikasi dapat menyertakan RCL dan mengambil alih tampilan dan halaman yang dikandungnya. Saat tampilan, tampilan parsial, atau Razor Halaman dijumpai di aplikasi web dan RCL, Razor markup (.cshtml file) di aplikasi web memiliki prioritas.

Untuk informasi tentang cara mengintegrasikan npm dan webpack ke dalam proses build untuk RCL, lihat Bangun aset web klien untuk Razor Class Library Anda.

Buatlah pustaka kelas yang berisi Razor UI

Visual Studio

• Dari Visual Studio pilih Buat proyek baru.
• Pilih Razor Pustaka Kelas>Berikutnya.
• Beri nama pustaka (misalnya, "RazorClassLib"), >Buat. Untuk menghindari tabrakan nama file dengan pustaka tampilan yang dihasilkan, pastikan nama pustaka tidak berakhiran .Views.
• Pilih Halaman bantuan dan tampilan jika Anda memerlukan pustaka untuk berisi halaman dan/atau tampilan. Secara default, hanya Razor komponen yang didukung. Pilih Buat.

Templat Pustaka Kelas Razor secara otomatis digunakan untuk pengembangan komponen Razor. Opsi Halaman dukungan dan tampilan mendukung halaman dan tampilan. Untuk informasi selengkapnya tentang dukungan RCL di Blazor, lihat Menggunakan komponen ASP.NET Core Razor dari Razor pustaka kelas (RCL).

.NET CLI

Dari baris perintah, jalankan dotnet new razorclasslib. Contohnya:

dotnet new razorclasslib -o RazorUIClassLib

Templat Pustaka Kelas Razor secara otomatis digunakan untuk pengembangan komponen Razor. Teruskan pilihan --support-pages-and-views (dotnet new razorclasslib --support-pages-and-views) untuk mendukung halaman dan tampilan.

Untuk informasi selengkapnya, lihat dotnet new. Untuk menghindari tabrakan nama file dengan pustaka tampilan yang dihasilkan, pastikan nama pustaka tidak berakhiran .Views.

Tambahkan Razor file ke RCL.

Templat ASP.NET Core mengasumsikan konten RCL ada di Areas folder . Lihat tata letak Halaman RCL di bawah ini untuk membuat RCL yang mengekspos konten ~/Pages , bukan ~/Areas/Pages.

Referensi konten RCL

RCL dapat dirujuk dengan:

• Paket NuGet. Lihat Membuat paket NuGet dan dotnet add package dan Membuat dan menerbitkan paket NuGet.
• {ProjectName}.csproj. Lihat dotnet-add reference.

Mengganti tampilan, tampilan parsial, dan halaman

Saat tampilan, tampilan parsial, atau Razor Halaman dijumpai di aplikasi web dan RCL, Razor markup (.cshtml file) di aplikasi web memiliki prioritas. Misalnya, tambahkan WebApp1/Areas/MyFeature/Pages/Page1.cshtml ke WebApp1, dan Page1 di WebApp1 akan lebih diutamakan daripada Page1 di RCL.

Dalam unduhan sampel, ganti nama WebApp1/Areas/MyFeature2 menjadi WebApp1/Areas/MyFeature untuk menguji urutan.

RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml Salin tampilan parsial ke WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Perbarui markup untuk menunjukkan lokasi baru. Bangun dan jalankan aplikasi untuk memverifikasi bahwa versi parsial dari aplikasi sedang digunakan.

Jika RCL menggunakan Razor Halaman, aktifkan layanan dan titik akhir Razor Halaman di aplikasi hosting.

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

Tata letak Halaman RCL

Untuk mereferensikan konten RCL seolah-olah itu adalah bagian dari folder aplikasi Pages web, buat proyek RCL dengan struktur file berikut:

• RazorUIClassLib/Pages
• RazorUIClassLib/Pages/Shared

Misalkan RazorUIClassLib/Pages/Shared berisi dua file parsial: _Header.cshtml dan _Footer.cshtml. Tag <partial> dapat ditambahkan ke _Layout.cshtml file:

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

Tambahkan file _ViewStart.cshtml ke folder Pages proyek RCL untuk menggunakan file _Layout.cshtml dari aplikasi web host.

@{
    Layout = "_Layout";
}

Membuat RCL dengan aset statis

RCL mungkin memerlukan aset statis pendamping yang dapat direferensikan oleh RCL atau aplikasi yang menggunakan RCL. ASP.NET Core memungkinkan pembuatan RCL yang menyertakan aset statis yang tersedia untuk aplikasi yang mengonsumsi.

Untuk menyertakan aset pendamping sebagai bagian dari RCL, buat wwwroot folder di pustaka kelas dan sertakan file yang diperlukan dalam folder tersebut.

Saat mengemas RCL, semua aset pendamping dalam wwwroot folder secara otomatis disertakan dalam paket.

Gunakan perintah dotnet pack daripada versi NuGet.exe nuget pack.

Menambahkan aset web klien ke proses build

Mengintegrasikan aset web klien ke dalam alur build bersifat nontrivial. Lihat Bangun aset web klien untuk Razor Perpustakaan Kelas Anda untuk informasi lebih lanjut.

Mengecualikan aset statis

Untuk mengecualikan aset statis, tambahkan jalur pengecualian yang diinginkan ke $(DefaultItemExcludes) grup properti dalam file proyek. Pisahkan entri dengan titik koma (;).

Dalam contoh berikut, lib.css lembar gaya di wwwroot folder tidak dianggap sebagai aset statis dan tidak disertakan dalam RCL yang diterbitkan:

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

Integrasi typescript

Untuk menyertakan file TypeScript dalam RCL:

• Cantumkan paket Microsoft.TypeScript.MSBuild NuGet dalam proyek.

  Note

  Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

• Tempatkan file TypeScript (.ts) di luar wwwroot folder. Misalnya, tempatkan file dalam Client folder.

• Tambahkan markup berikut ke file proyek:

  • Konfigurasikan output build TypeScript untuk folder wwwroot dengan properti TypescriptOutDir.
  • Jadikan target TypeScript sebagai dependensi dari target PrepareForBuildDependsOn.
  • Hapus output di 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>

Mengonsumsi konten dari RCL yang dirujuk

File yang terdapat dalam folder wwwroot di RCL diekspos ke RCL atau aplikasi yang menggunakan dengan awalan _content/{PACKAGE ID}/. Misalnya, pustaka dengan nama rakitan Razor.Class.Lib dan tanpa <PackageId> yang ditentukan dalam file proyeknya menghasilkan jalur menuju konten statis di _content/Razor.Class.Lib/. Ketika membuat paket NuGet dan nama rakitannya tidak cocok dengan ID paket (<PackageId> dalam file proyek pustaka), gunakan ID paket yang ditentukan dalam file proyek untuk {PACKAGE ID}.

Aplikasi yang mengonsumsi mereferensikan aset statis yang disediakan oleh pustaka dengan <script>, <style>, <img>, dan tag HTML lainnya. Aplikasi yang mengonsumsi harus mengaktifkan dukungan file statis di:

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

Saat menjalankan aplikasi yang menggunakan hasil build (dotnet run), aset web statis diaktifkan secara default di lingkungan Pengembangan. Agar aset didukung di lingkungan lain saat menjalankan dari output build, panggil UseStaticWebAssets pada pembangun host di 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();

Memanggil UseStaticWebAssets tidak diperlukan saat menjalankan aplikasi dari output yang diterbitkan (dotnet publish).

Alur pengembangan multi-proyek

Saat aplikasi yang digunakan dijalankan:

• Aset dalam RCL tetap berada di folder aslinya. Aset tidak dipindahkan ke aplikasi penerima.
• Setiap perubahan dalam folder RCL wwwroot tercermin dalam aplikasi konsumen setelah RCL selesai dibangun ulang dan tanpa perlu membangun ulang aplikasi konsumen.

Saat RCL dibuat, manifes diproduksi yang menjelaskan lokasi aset web statis. Aplikasi pemakai membaca manifes saat runtime untuk memanfaatkan aset dari proyek dan paket yang dirujuk. Saat aset baru ditambahkan ke RCL, RCL harus dibangun kembali untuk memperbarui manifesnya sebelum aplikasi yang menggunakan dapat mengakses aset baru.

Publish

Saat aplikasi diterbitkan, aset pendamping dari semua proyek dan paket yang direferensikan disalin ke dalam wwwroot folder aplikasi yang diterbitkan di bawah _content/{PACKAGE ID}/. Saat memproduksi paket NuGet dan nama rakitan tidak sama dengan ID paket (<PackageId> dalam file proyek pustaka), gunakan ID paket seperti yang ditentukan dalam file proyek {PACKAGE ID} saat memeriksa folder wwwroot untuk aset yang diterbitkan.

Sumber daya tambahan

• Melihat atau mengunduh kode sampel (cara mengunduh)

• Memanfaatkan komponen Razor ASP.NET Core dari pustaka kelas Razor (RCL)

• Isolasi CSS Blazor ASP.NET Core