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 atau terima nama proyek default. Contoh dalam topik ini menggunakan nama ComponentLibraryproyek . Pilih Buat.
4. Dalam dialog Buat pustaka kelas baruRazor, 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.

Jika kotak centang Halaman dukungan dan tampilan dipilih untuk mendukung halaman dan tampilan saat membuat RCL dari templat:

• _Imports.razor Tambahkan file ke akar proyek RCL yang dihasilkan dengan konten berikut untuk mengaktifkan Razor penulisan komponen:

  @using Microsoft.AspNetCore.Components.Web
  

• Tambahkan item berikut SupportedPlatform ke file proyek (.csproj):

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

  Untuk informasi selengkapnya tentang SupportedPlatform item, lihat bagian penganalisis kompatibilitas browser sisi klien.

Visual Studio Code / .NET Core CLI

1. Razor Gunakan templat proyek Pustaka Kelas (razorclasslib) dengan dotnet new perintah 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 dotnet add reference perintah dalam shell perintah. Dalam perintah berikut, {PATH TO LIBRARY} tempat penampung adalah jalur ke folder proyek pustaka:

   dotnet add reference {PATH TO LIBRARY}
   

-s|--support-pages-and-views Jika opsi digunakan untuk mendukung halaman dan tampilan saat membuat RCL dari templat:

• _Imports.razor Tambahkan file ke akar proyek RCL yang dihasilkan dengan konten berikut untuk mengaktifkan Razor penulisan komponen:

  @using Microsoft.AspNetCore.Components.Web
  

• Tambahkan item berikut SupportedPlatform ke file proyek (.csproj):

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

  Untuk informasi selengkapnya tentang SupportedPlatform item, lihat bagian penganalisis kompatibilitas browser sisi klien.

Razor Mengonsumsi komponen 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 _Imports.razor file di tingkat mana pun untuk menerapkan namespace layanan ke satu komponen atau sekumpulan komponen dalam folder. _Imports.razor Saat file digunakan, komponen individual tidak memerlukan 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.

Catatan

Jika RCL dibuat untuk mendukung halaman dan tampilan, tambahkan Component1 komponen dan aset statisnya secara manual ke RCL jika Anda berencana untuk mengikuti contoh dalam artikel ini. Komponen dan aset statis ditampilkan di bagian ini.

Component1.razorComponentLibrary di RCL:

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

Dalam aplikasi yang menggunakan RCL, referensikan Component1 komponen menggunakan namespace layanannya, seperti yang ditunjukkan 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 layanannya. 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 mengkonsumsi. Tidak perlu menautkan atau mengimpor lembar gaya komponen individual pustaka secara manual atau file CSS yang dibundel di aplikasi yang menggunakan pustaka. 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 Blazor aplikasi dengan BlazorSample.styles.css lembar gaya, lembar gaya RCL diimpor di bagian atas lembar gaya aplikasi secara otomatis pada waktu build:

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

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

Component1.razor.cssComponentLibrary di 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.pngComponentLibrary di RCL:

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

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 menautkan atau mengimpor lembar gaya komponen individual pustaka secara manual atau file CSS yang dibundel di aplikasi yang menggunakan pustaka. Contoh berikut adalah untuk menyediakan lembar gaya global di luar isolasi CSS, yang biasanya bukan persyaratan untuk aplikasi umum yang menggunakan 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.pngComponentLibrary di RCL:

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

wwwroot/additionalStyles.cssComponentLibrary di RCL:

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

Tambahkan komponen ke RCL yang menggunakan extra-style kelas .

ExtraStyles.razorComponentLibrary di 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 />

Tautkan ke lembar gaya pustaka di markup aplikasi <head> (lokasi <head> konten).

<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, ComponentLibrary.Component1 komponen digunakan untuk menemukan perakitan RCL.

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

Untuk informasi selengkapnya, lihat perutean dan navigasi ASP.NET CoreBlazor.

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. Default ID paket diatur ke nama rakitan proyek jika <PackageId> tidak ditentukan dalam file proyek. Tempat {PATH AND FILE NAME} penampung adalah jalur dan nama file di bawah 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 Blazor aplikasi yang menggunakan 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.pngComponentLibrary di RCL:

Tambahkan komponen berikut JeepYJ ke RCL.

JeepYJ.razorComponentLibrary di 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 ComponentLibrary folder 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 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 menyusun JS file menggunakan .razor.js ekstensi dan dapat diatasi secara publik menggunakan jalur ke file dalam proyek:

{PATH}/{COMPONENT}.razor.js

• Tempat {PATH} penampung adalah jalur ke komponen.
• Tempat {COMPONENT} penampung 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, tempat penampung:

• {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, seperti Blazor yang mengurus penempatan JS file dalam aset statis yang 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. JS Panggilan dari .NET sepenuhnya tercakup dalam fungsi Call JavaScript dari metode .NET di ASP.NET CoreBlazor , di mana ada penjelasan lebih lanjut tentang BlazorJS API dengan contoh tambahan. Pembuangan komponen, yang ada dalam contoh kedua, tercakup dalam siklus hidup komponen ASP.NET CoreRazor.

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

Penting

Jika Anda menggunakan kode berikut untuk demonstrasi di aplikasi pengujian, ubah {PATH} tempat penampung ke jalur komponen (misalnya: Components/Pages di .NET 8 atau yang lebih baru atau Pages di .NET 7 atau yang lebih lama). Blazor Dalam Aplikasi Web (.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 Blazor skrip (lokasi Blazor skrip mulai):

<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 void ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

File yang dikolokasi JS ditempatkan di JsCollocation1 samping file komponen dengan nama JsCollocation1.razor.jsfile . JsCollocation1 Dalam komponen, skrip dirujuk di jalur file yang dikolokasi. 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 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 dikolokasi JS , seperti yang ditunjukkan contoh berikutnya.

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

Penting

Jika Anda menggunakan kode berikut untuk demonstrasi di aplikasi pengujian, ubah {PATH} tempat penampung ke jalur komponen. Blazor Dalam Aplikasi Web (.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 void 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)
        {
            await module.DisposeAsync();
        }
    }
}

{PATH}/JsCollocation2.razor.js:

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

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

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

• Tempat penampung {PACKAGE ID} adalah pengidentifikasi paket RCL (atau nama pustaka untuk pustaka kelas yang dirujuk oleh aplikasi).
• Tempat {PATH} penampung adalah jalur ke komponen. Jika komponen Razor terletak di akar RCL, segmen jalur tidak disertakan.
• Tempat {COMPONENT} penampung adalah nama komponen.
• Tempat {EXTENSION} penampung cocok dengan ekstensi komponen, baik razor atau 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 area permukaan .NET API penuh, tetapi tidak semua API .NET didukung di WebAssembly karena batasan kotak pasir 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 mengaktifkan komponen, aplikasi, Blazor WebAssembly dan proyek RCL Interactive WebAssembly secara otomatis mengaktifkan pemeriksaan kompatibilitas browser dengan menambahkan browser sebagai platform yang didukung dengan SupportedPlatform item 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.
• Konsumen pustaka dan komponen tidak diperlukan untuk 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

Runtime yang menautkan ulang instans kelas javaScript-invokable .NET methods kecuali jika secara eksplisit dipertahankan. 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 dalam shell perintah:

dotnet pack

Unggah paket ke NuGet menggunakan dotnet nuget push perintah 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 isolasi CSS dengan Razor pustaka kelas