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

Oleh Rick Anderson

Razor tampilan, halaman, pengontrol, 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 ditemukan di aplikasi web dan RCL, Razor markup (.cshtml file) di aplikasi web lebih diutamakan.

Untuk informasi tentang cara mengintegrasikan npm dan webpack ke dalam proses build untuk Razor Pustaka Kelas, lihat Membangun aset web klien untuk Pustaka Kelas AndaRazor.

Membuat 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 dukungan dan tampilan jika Anda memerlukan pustaka untuk berisi halaman dan/atau tampilan. Secara default, hanya Razor komponen yang didukung. Pilih Buat.

Templat Razor pustaka kelas (RCL) default ke Razor pengembangan komponen secara default. 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 Core CLI

Dari baris perintah, jalankan dotnet new razorclasslib. Contohnya:

dotnet new razorclasslib -o RazorUIClassLib

Templat Razor pustaka kelas (RCL) default ke Razor pengembangan komponen secara default. Teruskan --support-pages-and-views opsi (dotnet new razorclasslib --support-pages-and-views) untuk memberikan dukungan untuk 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.

Mereferensikan konten RCL

RCL dapat dirujuk dengan:

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

Mengganti tampilan, tampilan parsial, dan halaman

Saat tampilan, tampilan parsial, atau Razor Halaman ditemukan di aplikasi web dan RCL, Razor markup (.cshtml file) di aplikasi web lebih diutamakan. 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 prioritas pengujian.

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

Jika RCL menggunakan Razor Halaman, aktifkan Razor layanan Halaman dan titik akhir 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>

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

@{
    Layout = "_Layout";
}

Membuat RCL dengan aset statis

RCL mungkin memerlukan aset statis pendamping yang dapat direferensikan oleh RCL atau aplikasi penggunaan 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.

dotnet pack Gunakan perintah daripada versi nuget packNuGet.exe .

Menambahkan aset web klien ke proses build

Mengintegrasikan aset web klien ke dalam alur build bersifat nontrivial. Lihat Membangun aset web klien untuk Pustaka Kelas Anda Razor untuk informasi selengkapnya.

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:

1. Referensi paket Microsoft.TypeScript.MSBuild NuGet dalam proyek.

   Catatan

   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.

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

3. Konfigurasikan output build TypeScript untuk wwwroot folder . Atur properti di TypescriptOutDir dalam PropertyGroup file proyek:

   <TypescriptOutDir>wwwroot</TypescriptOutDir>
   

4. Sertakan target TypeScript sebagai dependensi PrepareForBuildDependsOn target dengan menambahkan target berikut di dalam PropertyGroup file proyek:

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

Menggunakan konten dari RCL yang dirujuk

File yang disertakan dalam wwwroot folder RCL diekspos ke RCL atau aplikasi yang mengkonsumsi di bawah awalan _content/{PACKAGE ID}/. Misalnya, pustaka dengan nama Razor.Class.Lib rakitan dan tanpa <PackageId> ditentukan dalam file proyeknya menghasilkan jalur ke konten statis di _content/Razor.Class.Lib/. 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 untuk {PACKAGE ID}.

Aplikasi yang menggunakan mereferensikan aset statis yang disediakan oleh pustaka dengan <script>, <style>, <img>, dan tag HTML lainnya. Aplikasi yang menggunakan 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 dari output build (dotnet run), aset web statis diaktifkan secara default di lingkungan Pengembangan. Untuk mendukung aset di lingkungan lain saat menjalankan dari output build, panggil UseStaticWebAssets 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();

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

Alur pengembangan multi-proyek

Saat aplikasi yang mengonsumsi berjalan:

• Aset dalam RCL tetap berada di folder aslinya. Aset tidak dipindahkan ke aplikasi yang mengonsumsi.
• Setiap perubahan dalam folder RCL wwwroot tercermin dalam aplikasi yang mengkonsumsi setelah RCL dibangun kembali dan tanpa membangun kembali aplikasi yang mengkonsumsi.

Saat RCL dibuat, manifes diproduksi yang menjelaskan lokasi aset web statis. Aplikasi yang menggunakan membaca manifes pada runtime untuk menggunakan 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.

Terbitkan

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 {PACKAGE ID} proyek saat memeriksa wwwroot folder untuk aset yang diterbitkan.

Sumber Daya Tambahan:

• Melihat atau mengunduh kode sampel (cara mengunduh)

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

• isolasi CSS Inti Blazor ASP.NET