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

Komponen dapat dibagikan dalam Razor pustaka kelas (RCL) di seluruh proyek. Sertakan komponen dan aset statis dalam aplikasi dari:

• Proyek lain dalam solusi.
• Pustaka .NET yang dirujuk.
• Paket NuGet.

Sama seperti komponen adalah jenis .NET reguler, komponen yang disediakan oleh RCL adalah rakitan .NET normal.

Membuat RCL

Visual Studio

1. Buat proyek baru.
2. Dalam dialog Buat proyek baru, pilih Razor Pustaka Kelas dari daftar templat proyek inti ASP.NET. Pilih Selanjutnya.
3. Dalam dialog Konfigurasikan proyek baru Anda, berikan nama proyek di bidang Nama proyek. Contoh dalam topik ini menggunakan ComponentLibrary nama proyek. Pilih Selanjutnya.
4. Dalam dialog Informasi tambahan, jangan pilih Halaman dukungan dan tampilan. Pilih Buat.
5. Tambahkan RCL ke solusi:
   1. Buka solusi.
   2. Klik kanan solusi di Penjelajah Solusi. Pilih Tambahkan>Proyek yang Ada.
   3. Navigasikan ke file proyek RCL.
   4. Pilih file proyek RCL (.csproj).
6. Tambahkan referensi ke RCL dari aplikasi:
   1. Klik kanan proyek aplikasi. Pilih Tambahkan>Referensi Proyek.
   2. Pilih proyek RCL. Pilih OK.

Visual Studio Code / .NET CLI

1. Gunakan templat proyek Razor () dengan perintah razorclasslib dalam shell perintah. Dalam contoh berikut, RCL dibuat dan diberi nama ComponentLibrary menggunakan -o|--output opsi . Folder yang disimpan ComponentLibrary dibuat secara otomatis saat perintah dijalankan:

   dotnet new razorclasslib -o ComponentLibrary
   

2. Untuk menambahkan pustaka ke proyek yang sudah ada, gunakan perintah dotnet add reference dalam shell perintah. Dalam perintah berikut, {PATH TO LIBRARY} tempat penampung adalah jalur ke folder proyek pustaka:

   dotnet add reference {PATH TO LIBRARY}
   

Mengonsumsi komponen Razor dari RCL

Untuk menggunakan komponen dari RCL di proyek lain, gunakan salah satu pendekatan berikut:

• Gunakan nama jenis komponen lengkap, yang mencakup namespace RCL.
• Komponen individual dapat ditambahkan berdasarkan nama tanpa namespace RCL jika Razordirektif @using mendeklarasikan namespace RCL. Gunakan pendekatan berikut:
  • Tambahkan direktif @using ke komponen individual.
  • sertakan direktif @using dalam file tingkat _Imports.razor atas untuk membuat komponen pustaka tersedia untuk seluruh proyek. Tambahkan direktif ke file _Imports.razor pada tingkat mana saja untuk menerapkan namespace ke satu komponen atau sekumpulan komponen dalam folder. Ketika sebuah file _Imports.razor digunakan, komponen individual tidak memerlukan sebuah direktif @using untuk namespace RCL.

Dalam contoh berikut, ComponentLibrary adalah RCL yang berisi Component1 komponen. Komponen Component1 adalah komponen contoh yang secara otomatis ditambahkan ke RCL yang dibuat dari templat proyek RCL yang tidak dibuat untuk mendukung halaman dan tampilan.

Component1.razor di ComponentLibrary RCL:

<div class="my-component">
    This component is defined in the <strong>ComponentLibrary</strong> package.
</div>

Dalam aplikasi yang menggunakan RCL, referensikan komponen Component1 menggunakan namespace, seperti yang ditunjukkan dalam contoh berikut.

ConsumeComponent1.razor:

@page "/consume-component-1"

<h1>Consume component (full namespace example)</h1>

<ComponentLibrary.Component1 />

Atau, tambahkan direktif @using dan gunakan komponen tanpa namespace-nya. Direktif berikut @using juga dapat muncul dalam file apa pun _Imports.razor di atau di atas folder saat ini.

ConsumeComponent2.razor:

@page "/consume-component-2"
@using ComponentLibrary

<h1>Consume component (<code>@@using</code> example)</h1>

<Component1 />

Untuk komponen pustaka yang menggunakan isolasi CSS, gaya komponen secara otomatis tersedia untuk aplikasi yang menggunakannya. Tidak perlu secara manual menautkan atau mengimpor lembar gaya komponen individu dari pustaka atau file CSS yang dibundel dalam aplikasi yang memanfaatkan pustaka tersebut. Aplikasi ini menggunakan impor CSS untuk mereferensikan gaya bundel RCL. Gaya yang dibundel tidak diterbitkan sebagai aset web statis aplikasi yang menggunakan pustaka. Untuk pustaka kelas bernama ClassLib dan aplikasi Blazor dengan lembar gaya BlazorSample.styles.css, lembar gaya milik RCL diimpor di bagian atas lembar gaya aplikasi secara otomatis, pada waktu build.

@import '_content/ClassLib/ClassLib.bundle.scp.css';

Untuk contoh sebelumnya, stylesheet Component1 (Component1.razor.css) telah dibundel secara otomatis.

Component1.razor.css di ComponentLibrary RCL:

.my-component {
    border: 2px dashed red;
    padding: 1em;
    margin: 1em 0;
    background-image: url('background.png');
}

Gambar latar belakang juga disertakan dari templat proyek RCL dan berada di wwwroot folder RCL.

wwwroot/background.png di ComponentLibrary RCL:

Untuk menyediakan gaya komponen pustaka tambahan dari lembar gaya di folder pustaka wwwroot, tambahkan tag lembar gaya <link> ke konsumen di RCL, seperti yang ditunjukkan pada contoh berikut.

Penting

Umumnya, komponen pustaka menggunakan isolasi CSS untuk menggabungkan dan menyediakan gaya komponen. Gaya komponen yang mengandalkan isolasi CSS secara otomatis tersedia untuk aplikasi yang menggunakan RCL. Tidak perlu secara manual menautkan atau mengimpor lembar gaya komponen individu dari pustaka atau file CSS yang dibundel dalam aplikasi yang memanfaatkan pustaka tersebut. Contoh berikut adalah untuk menyediakan stylesheet global di luar isolasi CSS, yang biasanya tidak diperlukan untuk aplikasi umum yang mengintegrasikan RCL.

Gambar latar belakang berikut digunakan dalam contoh berikutnya. Jika Anda menerapkan contoh yang ditampilkan di bagian ini, klik kanan gambar untuk menyimpannya secara lokal.

wwwroot/extra-background.png di ComponentLibrary RCL:

Tambahkan lembar gaya baru ke RCL dengan kelas extra-style.

wwwroot/additionalStyles.css di ComponentLibrary RCL:

.extra-style {
    border: 2px dashed blue;
    padding: 1em;
    margin: 1em 0;
    background-image: url('extra-background.png');
}

Tambahkan komponen ke RCL yang menggunakan kelas extra-style.

ExtraStyles.razor di ComponentLibrary RCL:

<div class="extra-style">
    <p>
        This component is defined in the <strong>ComponentLibrary</strong> package.
    </p>
</div>

Tambahkan halaman ke aplikasi yang menggunakan ExtraStyles komponen dari RCL.

ConsumeComponent3.razor:

@page "/consume-component-3"
@using ComponentLibrary

<h1>Consume component (<code>additionalStyles.css</code> example)</h1>

<ExtraStyles />

Hubungkan ke lembar gaya pustaka di markup aplikasi <head> (lokasi <head> konten):

Blazor Web Apps:

<link href="@Assets["_content/ComponentLibrary/additionalStyles.css"]" rel="stylesheet">

Aplikasi Blazor WebAssembly mandiri:

<link href="_content/ComponentLibrary/additionalStyles.css" rel="stylesheet">

Membuat komponen yang dapat dirutekan tersedia dari RCL

Untuk membuat komponen yang dapat dirutekan dalam RCL tersedia untuk permintaan langsung, perakitan RCL harus diungkapkan ke router aplikasi.

Buka komponen aplikasi App (App.razor). Assembly Tetapkan koleksi ke AdditionalAssemblies parameter Router komponen untuk menyertakan rakitan RCL. Dalam contoh berikut, komponen ComponentLibrary.Component1 digunakan untuk menemukan rakitan RCL.

AdditionalAssemblies="new[] { typeof(ComponentLibrary.Component1).Assembly }"

Untuk informasi selengkapnya, lihat ASP.NET Core Blazor routing dan navigasi.

Membuat RCL dengan aset statis di wwwroot folder

Aset statis RCL tersedia untuk aplikasi apa pun yang menggunakan pustaka.

Tempatkan aset statis di wwwroot folder RCL dan referensikan aset statis dengan jalur berikut di aplikasi: _content/{PACKAGE ID}/{PATH AND FILE NAME}. Tempat penampung {PACKAGE ID} adalah ID paket pustaka. Secara default, ID paket diatur ke nama rakitan proyek jika <PackageId> tidak ditentukan dalam file proyek. Placeholder {PATH AND FILE NAME} adalah jalur dan nama file dalam wwwroot. Format jalur ini juga digunakan dalam aplikasi untuk aset statis yang disediakan oleh paket NuGet yang ditambahkan ke RCL.

Contoh berikut menunjukkan penggunaan aset statis RCL dengan RCL bernama ComponentLibrary dan aplikasi Blazor yang mengonsumsi RCL. Aplikasi ini memiliki referensi proyek untuk ComponentLibrary RCL.

Gambar Jeep® berikut digunakan dalam contoh bagian ini. Jika Anda menerapkan contoh yang ditampilkan di bagian ini, klik kanan gambar untuk menyimpannya secara lokal.

wwwroot/jeep-yj.png di ComponentLibrary RCL:

Tambahkan komponen berikut JeepYJ ke RCL.

JeepYJ.razor di ComponentLibrary RCL:

<h3>ComponentLibrary.JeepYJ</h3>

<p>
    <img alt="Jeep YJ&reg;" src="_content/ComponentLibrary/jeep-yj.png" />
</p>

Tambahkan komponen berikut Jeep ke aplikasi yang menggunakan ComponentLibrary RCL. Komponen Jeep menggunakan:

• Gambar Jeep YJ® dari folder ComponentLibrary RCL wwwroot.
• Komponen JeepYJ dari RCL.

Jeep.razor:

@page "/jeep"
@using ComponentLibrary

<div style="float:left;margin-right:10px">
    <h3>Direct use</h3>

    <p>
        <img alt="Jeep YJ&reg;" src="_content/ComponentLibrary/jeep-yj.png" />
    </p>
</div>

<JeepYJ />

<p>
    <em>Jeep</em> and <em>Jeep YJ</em> are registered trademarks of 
    <a href="https://www.stellantis.com">FCA US LLC (Stellantis NV)</a>.
</p>

Komponen yang telah dirender Jeep

Untuk informasi selengkapnya, lihat UI yang dapat digunakan kembali Razor di pustaka kelas dengan ASP.NET Core.

Membuat RCL dengan file JavaScript yang dikolokasikan dengan komponen

Kolokasi file JavaScript (JS) untuk Razor komponen adalah cara mudah untuk mengatur skrip dalam aplikasi.

Razor komponen Blazor aplikasi menggabungkan JS file menggunakan .razor.js ekstensi dan dapat diakses secara publik menggunakan jalur ke file di dalam proyek:

{PATH}/{COMPONENT}.razor.js

• Placeholder {PATH} adalah jalur ke komponen.
• Placeholder {COMPONENT} adalah komponen.

Saat aplikasi diterbitkan, kerangka kerja secara otomatis memindahkan skrip ke akar web. Skrip dipindahkan ke bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js, di mana tempat penampungnya adalah:

• {TARGET FRAMEWORK MONIKER} adalah Moniker Kerangka Kerja Target (TFM).
• {PATH} adalah jalur ke komponen.
• {COMPONENT} adalah nama komponen.

Tidak ada perubahan yang diperlukan pada URL relatif skrip, karena Blazor akan mengurus penempatan file JS dalam aset statis yang telah diterbitkan untuk Anda.

Bagian ini dan contoh berikut terutama berfokus pada penjelasan JS kolokasi file. Contoh pertama menunjukkan file yang dikolokasi JS dengan fungsi biasa JS . Contoh kedua menunjukkan penggunaan modul untuk memuat fungsi, yang merupakan pendekatan yang direkomendasikan untuk sebagian besar aplikasi produksi. Memanggil JS dari .NET dijelaskan secara lengkap dalam Memanggil fungsi JavaScript dari metode .NET di ASP.NET Core Blazor, yang berisi penjelasan lebih lanjut tentang API BlazorJS dengan contoh tambahan. Pembuangan komponen, yang ada dalam contoh kedua, tercakup dalam ASP.NET pembuangan komponen core Razor.

Komponen JsCollocation1 berikut memuat skrip melalui komponen HeadContent dan memanggil fungsi JS dengan IJSRuntime.InvokeAsync. Placeholder {PATH} adalah jalur ke komponen.

Penting

Jika Anda menggunakan kode berikut untuk demonstrasi di aplikasi pengujian, ubah placeholder {PATH} ke path ke komponen (contoh: Components/Pages di .NET 8 atau yang lebih baru atau Pages di .NET 7 atau yang lebih lama). Blazor Web App Dalam (.NET 8 atau yang lebih baru), komponen memerlukan mode render interaktif yang diterapkan baik secara global ke aplikasi atau ke definisi komponen.

Tambahkan skrip berikut setelah skrip Blazor (lokasi skrip Blazor awal):

<script src="{PATH}/JsCollocation1.razor.js"></script>

JsCollocation1 komponen ({PATH}/JsCollocation1.razor):

@page "/js-collocation-1"
@inject IJSRuntime JS

<PageTitle>JS Collocation 1</PageTitle>

<h1>JS Collocation Example 1</h1>

<button @onclick="ShowPrompt">Call showPrompt1</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private string? result;

    public async Task ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

File yang ditempatkan bersamaan JS ditempatkan berdampingan dengan file komponen JsCollocation1 dengan nama JsCollocation1.razor.js file. Dalam komponen JsCollocation1, skrip dirujuk pada jalur file yang terlokalisasi. Dalam contoh berikut, showPrompt1 fungsi menerima nama pengguna dari Window prompt() dan mengembalikannya ke JsCollocation1 komponen untuk ditampilkan.

{PATH}/JsCollocation1.razor.js:

function showPrompt1(message) {
  return prompt(message, 'Type your name here');
}

Pendekatan sebelumnya tidak disarankan untuk penggunaan umum dalam aplikasi produksi karena pendekatan mencemari klien dengan fungsi global. Pendekatan yang lebih baik untuk aplikasi produksi adalah menggunakan JS modul. Prinsip umum yang sama berlaku untuk memuat JS modul dari file yang terletak berdekatan JS, sebagaimana ditunjukkan oleh contoh berikut.

Metode dari komponen berikut JsCollocation2 memuat modul OnAfterRenderAsync ke dalam JS, yang merupakan module dari kelas komponen. module digunakan untuk memanggil showPrompt2 fungsi. Placeholder {PATH} adalah jalur ke komponen.

Penting

Jika Anda menggunakan kode berikut untuk demonstrasi di aplikasi pengujian, ubah placeholder {PATH} ke jalur komponen. Blazor Web App Dalam (.NET 8 atau yang lebih baru), komponen memerlukan mode render interaktif yang diterapkan baik secara global ke aplikasi atau ke definisi komponen.

JsCollocation2 komponen ({PATH}/JsCollocation2.razor):

@page "/js-collocation-2"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>JS Collocation 2</PageTitle>

<h1>JS Collocation Example 2</h1>

<button @onclick="ShowPrompt">Call showPrompt2</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private IJSObjectReference? module;
    private string? result;

    protected async override Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            /*
                Change the {PATH} placeholder in the next line to the path of
                the collocated JS file in the app. Examples:

                ./Components/Pages/JsCollocation2.razor.js (.NET 8 or later)
                ./Pages/JsCollocation2.razor.js (.NET 7 or earlier)
            */
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./{PATH}/JsCollocation2.razor.js");
        }
    }

    public async Task ShowPrompt()
    {
        if (module is not null)
        {
            result = await module.InvokeAsync<string>(
                "showPrompt2", "What's your name?");
            StateHasChanged();
        }
    }

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (module is not null)
        {
            try
            {
                await module.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

Dalam contoh sebelumnya, JSDisconnectedException terjebak selama penghapusan modul jika terjadi kehilangan sirkuit BlazorSignalR. Jika kode sebelumnya digunakan dalam aplikasi Blazor WebAssembly, tidak ada koneksi yang bisa hilang, sehingga Anda dapat menghapus blok SignalRtry- dan meninggalkan baris yang membuang modul (catch). Untuk informasi selengkapnya, lihat ASP.NET Blazor interoperabilitas Core JavaScript (JS interop).

{PATH}/JsCollocation2.razor.js:

export function showPrompt2(message) {
  return prompt(message, 'Type your name here');
}

Penting

Jangan menempatkan tag <script> untuk JsCollocation2.razor.js setelah skrip Blazor karena modul dimuat dan di-cache secara otomatis ketika import() dipanggil secara dinamis.

Penggunaan skrip dan modul untuk JS yang diletakkan bersama di dalam pustaka kelas Razor (RCL) hanya didukung untuk mekanisme interop BlazorJS yang berdasarkan antarmuka IJSRuntime. Jika Anda menerapkan interop JavaScript[JSImport]/[JSExport], lihat JavaScript JSImport/JSExport interop dengan ASP.NET Core Blazor.

Untuk skrip atau modul yang Razor disediakan oleh pustaka kelas (RCL) menggunakan IJSRuntimeinterop berbasis JS , jalur berikut digunakan:

./_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.js

• Segmen jalur untuk direktori saat ini (./) diperlukan untuk membuat jalur aset statis yang benar ke file JS.
• Penanda {PACKAGE ID} adalah pengidentifikasi paket RCL (atau nama pustaka kelas yang dirujuk oleh aplikasi).
• Placeholder {PATH} adalah jalur ke komponen. Jika komponen Razor terletak di akar RCL, segmen jalur tidak disertakan.
• Placeholder {COMPONENT} adalah nama komponen.
• Placeholder {EXTENSION} cocok dengan ekstensi komponen, baik razor maupun cshtml.

Dalam contoh aplikasi Blazor berikut:

• Pengidentifikasi paket RCL adalah AppJS.
• Skrip modul dimuat untuk komponen JsCollocation3 (JsCollocation3.razor).
• Komponen JsCollocation3 ada di folder Components/Pages RCL.

module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

Penganalisis kompatibilitas browser sisi klien

Aplikasi sisi klien menargetkan seluruh permukaan API .NET, tetapi tidak semua API .NET terdukung di WebAssembly karena batasan sandbox browser. API yang tidak didukung ditampilkan PlatformNotSupportedException saat berjalan di WebAssembly. Penganalisis kompatibilitas platform memperingatkan pengembang saat aplikasi menggunakan API yang tidak didukung oleh platform target aplikasi. Untuk aplikasi sisi klien, ini berarti memeriksa bahwa API didukung di browser. Anotasi API .NET framework untuk penganalisis kompatibilitas adalah proses yang sedang berlangsung, jadi tidak semua .NET framework API saat ini diannotasi.

Blazor Web Apps yang memungkinkan komponen Interactive WebAssembly, Blazor WebAssembly aplikasi, dan proyek RCL secara otomatis mengaktifkan pemeriksaan kompatibilitas browser dengan menambahkan browser sebagai platform yang didukung dengan item SupportedPlatform MSBuild. Pengembang pustaka dapat menambahkan SupportedPlatform item secara manual ke file proyek pustaka untuk mengaktifkan fitur:

<ItemGroup>
  <SupportedPlatform Include="browser" />
</ItemGroup>

Saat menulis pustaka, tunjukkan bahwa API tertentu tidak didukung di browser dengan menentukan browser ke UnsupportedOSPlatformAttribute:

using System.Runtime.Versioning;

...

[UnsupportedOSPlatform("browser")]
private static string GetLoggingDirectory()
{
    ...
}

Untuk informasi selengkapnya, lihat Menganotasi API sebagai tidak didukung pada platform tertentu (dotnet/designs repositori GitHub.

Isolasi JavaScript dalam modul JavaScript

Blazormengaktifkan isolasi JavaScript dalam modul JavaScript standar. Isolasi JavaScript memberikan manfaat berikut:

• JavaScript yang diimpor tidak lagi mencemari namespace global.
• Pengguna pustaka dan komponen tidak perlu mengimpor JavaScript terkait secara manual.

Untuk informasi lebih lanjut, lihat Memanggil fungsi JavaScript dari metode .NET di Blazor ASP.NET Core.

Hindari pemangkasan metode .NET yang dapat dipanggil JavaScript

Penautan ulang runtime memangkas metode-metode .NET yang dapat dipanggil melalui JavaScript pada instans kelas kecuali jika dipertahankan secara eksplisit. Untuk informasi selengkapnya, lihat Memanggil metode .NET dari fungsi JavaScript di ASP.NET Core Blazor.

Membangun, mengemas, dan mengirim ke NuGet

Karena Razor pustaka kelas yang berisi Razor komponen adalah pustaka .NET standar, pengemasan dan pengirimannya ke NuGet tidak berbeda dengan pengemasan dan pengiriman pustaka apa pun ke NuGet. Pengemasan dilakukan menggunakan dotnet pack perintah di antarmuka baris perintah.

dotnet pack

Unggah paket ke NuGet menggunakan perintah dotnet nuget push dalam shell perintah.

Merek Dagang

Jeep dan Jeep YJ adalah merek dagang terdaftar dari FCA US LLC (Stellantis NV).

Sumber Daya Tambahan:

• Antarmuka pengguna Razor yang dapat digunakan kembali di pustaka kelas dengan ASP.NET Core
• Menggunakan API ASP.NET Core di pustaka kelas
• Menambahkan file konfigurasi Pemangkas Bahasa Perantara XML (IL) ke pustaka
• Dukungan untuk isolasi CSS dengan pustaka kelas Razor