Bagikan melalui

mode render inti Blazor ASP.NET

  • Artikel

Artikel ini menjelaskan kontrol penyajian Razor komponen di Blazor Web Apps, baik pada waktu kompilasi atau runtime.

Panduan ini tidak berlaku untuk aplikasi mandiri Blazor WebAssembly . Blazor WebAssembly aplikasi hanya merender pada klien melalui runtime berbasis WebAssembly sisi klien dan tidak memiliki konsep mode render. Jika mode render diterapkan ke komponen dalam Blazor WebAssembly aplikasi, penandaan mode render tidak memiliki pengaruh pada penyajian komponen.

Mode render

Setiap komponen dalam Blazor Aplikasi Web mengadopsi mode render untuk menentukan model hosting yang digunakannya, tempatnya dirender, dan apakah itu interaktif atau tidak.

Tabel berikut ini memperlihatkan mode render yang tersedia untuk merender Razor komponen di Blazor Aplikasi Web. Untuk menerapkan mode render ke komponen, gunakan direktif @rendermode pada instans komponen atau pada definisi komponen. Nantinya dalam artikel ini, contoh ditampilkan untuk setiap skenario mode render.

Nama Deskripsi Lokasi render Interaktif
Server Statis Penyajian sisi server statis (SSR statis) Server
Server Interaktif Penyajian sisi server interaktif (SSR interaktif) menggunakan Blazor Server. Server
Interactive WebAssembly Penyajian sisi klien (CSR) menggunakan Blazor WebAssembly†. Klien
Interaktif Otomatis SSR interaktif menggunakan Blazor Server awalnya dan kemudian CSR pada kunjungan berikutnya setelah Blazor bundel diunduh. Server, lalu klien

†Client-side rendering (CSR) diasumsikan interaktif. "Penyajian sisi klien interaktif " dan "CSR interaktif " tidak digunakan oleh industri atau dalam Blazor dokumentasi.

Pra-penyajian diaktifkan secara default untuk komponen interaktif. Panduan tentang mengontrol pra-penyajian disediakan nanti di artikel ini. Untuk terminologi industri umum tentang konsep rendering klien dan server, lihat dasar-dasar ASP.NET CoreBlazor.

Contoh berikut menunjukkan pengaturan mode render komponen dengan beberapa fitur komponen dasar Razor .

Untuk menguji perilaku mode render secara lokal, Anda dapat menempatkan komponen berikut dalam aplikasi yang dibuat dari Blazor templat proyek Aplikasi Web. Saat Anda membuat aplikasi, pilih opsi dari menu dropdown (Visual Studio) atau terapkan opsi CLI (.NET CLI) untuk mengaktifkan interaktivitas sisi server dan sisi klien. Untuk panduan tentang cara membuat Blazor Aplikasi Web, lihat Alat untuk ASP.NET Core Blazor.

Mengaktifkan dukungan untuk mode render interaktif

Blazor Aplikasi Web harus dikonfigurasi untuk mendukung mode render interaktif. Ekstensi berikut secara otomatis diterapkan ke aplikasi yang dibuat dari Blazor templat proyek Aplikasi Web selama pembuatan aplikasi. Komponen individual masih diperlukan untuk mendeklarasikan mode render mereka per bagian Mode render setelah layanan komponen dan titik akhir dikonfigurasi dalam file aplikasi Program .

Layanan untuk Razor komponen ditambahkan dengan memanggil AddRazorComponents.

Ekstensi penyusun komponen:

MapRazorComponents menemukan komponen yang tersedia dan menentukan komponen akar untuk aplikasi (komponen pertama yang dimuat), yang secara default adalah App komponen (App.razor).

Ekstensi penyusun konvensi titik akhir:

Catatan

Untuk orientasi pada penempatan API dalam contoh berikut, periksa Program file aplikasi yang dihasilkan dari Blazor templat proyek Aplikasi Web. Untuk panduan tentang cara membuat Blazor Aplikasi Web, lihat Alat untuk ASP.NET Core Blazor.

Contoh 1: API file berikut Program menambahkan layanan dan konfigurasi untuk mengaktifkan SSR interaktif:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

Contoh 2: API file berikut Program menambahkan layanan dan konfigurasi untuk mengaktifkan mode render Interactive WebAssembly:

builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode();

Contoh 3: API file berikut Program menambahkan layanan dan konfigurasi untuk mengaktifkan mode render Interactive Server, Interactive WebAssembly, dan Interactive Auto:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode();

BlazorBlazor WebAssembly menggunakan model hosting untuk mengunduh dan menjalankan komponen yang menggunakan mode render Interactive WebAssembly. Proyek klien terpisah diperlukan untuk menyiapkan Blazor WebAssembly hosting untuk komponen-komponen ini. Proyek klien berisi kode startup untuk Blazor WebAssembly host dan menyiapkan runtime .NET untuk berjalan di browser. Templat Blazor Aplikasi Web menambahkan proyek klien ini untuk Anda saat Anda memilih opsi untuk mengaktifkan interaktivitas WebAssembly. Komponen apa pun yang menggunakan mode render Interactive WebAssembly harus dibuat dari proyek klien, sehingga komponen disertakan dalam bundel aplikasi yang diunduh.

Menerapkan mode render ke instans komponen

Untuk menerapkan mode render ke instans komponen, gunakan atribut direktifRazor@rendermodetempat komponen digunakan.

Dalam contoh berikut, penyajian sisi server interaktif (SSR interaktif) diterapkan ke Dialog instans komponen:

<Dialog @rendermode="InteractiveServer" />

Catatan

Blazor templat menyertakan arahan statis using untuk RenderMode dalam file aplikasi _Imports (Components/_Imports.razor) untuk sintaks yang lebih @rendermode pendek:

@using static Microsoft.AspNetCore.Components.Web.RenderMode

Tanpa direktif sebelumnya, komponen harus menentukan kelas statis RenderMode dalam @rendermode sintaks:

<Dialog @rendermode="RenderMode.InteractiveServer" />

Anda juga dapat mereferensikan instans mode render kustom yang dibuat langsung dengan konfigurasi kustom. Untuk informasi selengkapnya, lihat bagian Mode render singkat kustom nanti di artikel ini.

Menerapkan mode render ke definisi komponen

Untuk menentukan mode render untuk komponen sebagai bagian dari definisinya, gunakan @rendermodeRazor direktif dan atribut mode render yang sesuai.

@page "..."
@rendermode InteractiveServer

Menerapkan mode render ke definisi komponen umumnya digunakan saat menerapkan mode render ke halaman tertentu. Halaman yang dapat dirutekan secara default menggunakan mode render yang sama dengan Router komponen yang merender halaman.

Secara teknis, @rendermode adalahRazor atribut direktif dan Razordirektif. Semantiknya mirip, tetapi ada perbedaan. Direktif @rendermode ada pada definisi komponen, sehingga instans mode render yang direferensikan harus statis. Atribut @rendermode direktif dapat mengambil instans mode render apa pun.

Catatan

Penulis komponen harus menghindari kopling implementasi komponen ke mode render tertentu. Sebaliknya, penulis komponen biasanya harus merancang komponen untuk mendukung mode render atau model hosting apa pun. Implementasi komponen harus menghindari asumsi di mana komponen berjalan (server atau klien) dan harus diturunkan dengan baik ketika dirender secara statis. Menentukan mode render dalam definisi komponen mungkin diperlukan jika komponen tidak dibuat secara langsung (seperti dengan komponen halaman yang dapat dirutekan) atau untuk menentukan mode render untuk semua instans komponen.

Menerapkan mode render ke seluruh aplikasi

Untuk mengatur mode render untuk seluruh aplikasi, tunjukkan mode render pada komponen interaktif tingkat tertinggi dalam hierarki komponen aplikasi yang bukan komponen root.

Catatan

Membuat komponen akar interaktif, seperti App komponen, tidak didukung. Oleh karena itu, mode render untuk seluruh aplikasi tidak dapat diatur langsung oleh App komponen.

Untuk aplikasi berdasarkan Blazor templat proyek Aplikasi Web, mode render yang ditetapkan ke seluruh aplikasi biasanya ditentukan di mana Routes komponen digunakan dalam App komponen (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Komponen menyebarluaskan Router mode render-nya ke halaman yang dirutekannya.

Anda juga biasanya harus mengatur mode render interaktif yang sama pada HeadOutlet komponen, yang juga ditemukan di App komponen Aplikasi Web yang Blazor dihasilkan dari templat proyek:

<HeadOutlet @rendermode="InteractiveServer" />

Untuk aplikasi yang mengadopsi mode penyajian sisi klien interaktif (WebAssembly atau Auto) dan mengaktifkan mode render untuk seluruh aplikasi melalui Routes komponen:

  • Tempatkan atau pindahkan file tata letak dan navigasi folder aplikasi Components/Layout server ke .Client folder proyek Layout . Buat Layout folder dalam .Client proyek jika tidak ada.
  • Tempatkan atau pindahkan komponen folder aplikasi Components/Pages server ke .Client folder proyek Pages . Buat Pages folder dalam .Client proyek jika tidak ada.
  • Tempatkan atau pindahkan Routes komponen folder aplikasi Components server ke .Client folder akar proyek.

Untuk mengaktifkan interaktivitas global saat membuat Blazor Aplikasi Web:

  • Visual Studio: Atur daftar dropdown Lokasi interaktivitas ke Global.
  • .NET CLI: Gunakan -ai|--all-interactive opsi .

Untuk informasi selengkapnya, lihat Alat untuk ASP.NET Core Blazor.

Menerapkan mode render secara terprogram

Properti dan bidang dapat menetapkan mode render.

Pendekatan kedua yang dijelaskan di bagian ini, mengatur mode render berdasarkan instans komponen, sangat berguna ketika spesifikasi aplikasi Anda memanggil satu atau beberapa komponen untuk mengadopsi SSR statis di aplikasi interaktif global. Skenario ini tercakup dalam halaman SSR Statis di bagian aplikasi interaktif global nanti di artikel ini.

Mengatur mode render menurut definisi komponen

Definisi komponen dapat menentukan mode render melalui bidang privat:

@rendermode pageRenderMode

...

@code {
    private static IComponentRenderMode pageRenderMode = InteractiveServer;
}

Mengatur mode render menurut instans komponen

Contoh berikut menerapkan penyajian sisi server interaktif (SSR interaktif) ke permintaan apa pun.

<Routes @rendermode="PageRenderMode" />

...

@code {
    private IComponentRenderMode? PageRenderMode => InteractiveServer;
}

Informasi tambahan tentang penyebaran mode render disediakan di bagian Penyebaran mode render nanti di artikel ini. Halaman SSR Statis di bagian aplikasi interaktif global menunjukkan cara menggunakan pendekatan sebelumnya untuk mengadopsi SSR statis di aplikasi interaktif global.

Blazor contoh dokumentasi untuk Blazor Web Apps

Saat menggunakan Blazor Aplikasi Web, sebagian Blazor besar komponen contoh dokumentasi memerlukan interaktivitas untuk berfungsi dan menunjukkan konsep yang dibahas oleh artikel. Saat Anda menguji komponen contoh yang disediakan oleh artikel, pastikan aplikasi mengadopsi interaktivitas global atau komponen mengadopsi mode render interaktif.

Pra-penyajian

Pra-penyajian adalah proses awalnya merender konten halaman di server tanpa mengaktifkan penanganan aktivitas untuk kontrol yang dirender. Server mengeluarkan UI HTML halaman sesegera mungkin sebagai respons terhadap permintaan awal, yang membuat aplikasi merasa lebih responsif terhadap pengguna. Pra-penyajian juga dapat meningkatkan Pengoptimalan Mesin Pencari (SEO) dengan merender konten untuk respons HTTP awal yang digunakan mesin pencari untuk menghitung peringkat halaman.

Pra-penyajian diaktifkan secara default untuk komponen interaktif.

Untuk menonaktifkan pra-penyajian untuk instans komponen, teruskan prerender bendera dengan nilai false ke mode render:

  • <... @rendermode="new InteractiveServerRenderMode(prerender: false)" />
  • <... @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />
  • <... @rendermode="new InteractiveAutoRenderMode(prerender: false)" />

Untuk menonaktifkan pra-penyajian dalam definisi komponen:

  • @rendermode @(new InteractiveServerRenderMode(prerender: false))
  • @rendermode @(new InteractiveWebAssemblyRenderMode(prerender: false))
  • @rendermode @(new InteractiveAutoRenderMode(prerender: false))

Untuk menonaktifkan pra-penyajian untuk seluruh aplikasi, tunjukkan mode render pada komponen interaktif tingkat tertinggi dalam hierarki komponen aplikasi yang bukan komponen akar.

Untuk aplikasi berdasarkan Blazor templat proyek Aplikasi Web, mode render yang ditetapkan ke seluruh aplikasi ditentukan di mana Routes komponen digunakan dalam App komponen (Components/App.razor). Contoh berikut mengatur mode render aplikasi ke Interactive Server dengan prarender dinonaktifkan:

<Routes @rendermode="new InteractiveServerRenderMode(prerender: false)" />

Selain itu, nonaktifkan pra-penyajian HeadOutlet untuk komponen dalam App komponen:

<HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: false)" />

Membuat komponen akar, seperti App komponen, interaktif dengan @rendermode direktif di bagian atas file definisi komponen akar (.razor) tidak didukung. Oleh karena itu, pra-penyajian tidak dapat dinonaktifkan secara langsung oleh App komponen.

Penyajian sisi server statis (SSR statis)

Secara default, komponen menggunakan penyajian sisi server statis (SSR statis). Komponen dirender ke aliran respons dan interaktivitas tidak diaktifkan.

Dalam contoh berikut, tidak ada penandaan untuk mode render komponen, sehingga komponen mewarisi mode rendernya dari induknya. Karena tidak ada komponen leluhur yang menentukan mode render, komponen berikut dirender secara statis di server. Tombol tidak interaktif dan tidak memanggil UpdateMessage metode saat dipilih. Nilai message tidak berubah, dan komponen tidak dirender sebagai respons terhadap peristiwa UI.

RenderMode1.razor:

@page "/render-mode-1"

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Jika menggunakan komponen sebelumnya secara lokal di Blazor Aplikasi Web, tempatkan komponen di folder proyek Components/Pages server. Proyek server adalah proyek solusi dengan nama yang tidak berakhiran .Client. Saat aplikasi berjalan, navigasikan ke /render-mode-1 di bilah alamat browser.

Selama SSR statis, Razor permintaan halaman komponen diproses oleh sisi server ASP.NET pemrosesan permintaan alur middleware Core untuk perutean dan otorisasi. Fitur khusus Blazor untuk perutean dan otorisasi tidak beroperasi karena Razor komponen tidak dirender selama pemrosesan permintaan sisi server. Blazor fitur router dalam Routes komponen yang tidak tersedia selama SSR statis termasuk menampilkan:

Jika aplikasi menunjukkan interaktivitas tingkat akar, pemrosesan permintaan ASP.NET Core sisi server tidak terlibat setelah SSR statis awal, yang berarti bahwa fitur sebelumnya Blazor berfungsi seperti yang diharapkan.

Navigasi yang ditingkatkan dengan SSR statis memerlukan perhatian khusus saat memuat JavaScript. Untuk informasi selengkapnya, lihat ASP.NET Core Blazor JavaScript dengan penyajian sisi server statis (SSR statis).

Penyajian sisi server interaktif (SSR interaktif)

Penyajian sisi server interaktif (SSR interaktif) merender komponen secara interaktif dari server menggunakan Blazor Server. Interaksi pengguna ditangani melalui koneksi real-time dengan browser. Koneksi sirkuit dibuat ketika komponen Server dirender.

Dalam contoh berikut, mode render diatur SSR interaktif dengan menambahkan @rendermode InteractiveServer ke definisi komponen. Tombol memanggil UpdateMessage metode ketika dipilih. Nilai message perubahan, dan komponen dirender untuk memperbarui pesan di UI.

RenderMode2.razor:

@page "/render-mode-2"
@rendermode InteractiveServer

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Jika menggunakan komponen sebelumnya secara lokal di Blazor Aplikasi Web, tempatkan komponen di folder proyek Components/Pages server. Proyek server adalah proyek solusi dengan nama yang tidak berakhiran .Client. Saat aplikasi berjalan, navigasikan ke /render-mode-2 di bilah alamat browser.

Penyajian sisi klien (CSR)

Penyajian sisi klien (CSR) merender komponen secara interaktif pada klien menggunakan Blazor WebAssembly. Runtime .NET dan app bundle diunduh dan di-cache ketika komponen WebAssembly awalnya dirender. Komponen yang menggunakan CSR harus dibangun dari proyek klien terpisah yang menyiapkan Blazor WebAssembly host.

Dalam contoh berikut, mode render diatur ke CSR dengan @rendermode InteractiveWebAssembly. Tombol memanggil UpdateMessage metode ketika dipilih. Nilai message perubahan, dan komponen dirender untuk memperbarui pesan di UI.

RenderMode3.razor:

@page "/render-mode-3"
@rendermode InteractiveWebAssembly

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Jika menggunakan komponen sebelumnya secara lokal di Blazor Aplikasi Web, tempatkan komponen di folder proyek Pages klien. Proyek klien adalah proyek solusi dengan nama yang berakhiran .Client. Saat aplikasi berjalan, navigasikan ke /render-mode-3 di bilah alamat browser.

Penyajian otomatis (Otomatis)

Penyajian otomatis (Otomatis) menentukan cara merender komponen saat runtime. Komponen ini awalnya dirender dengan penyajian sisi server interaktif (SSR interaktif) menggunakan Blazor Server model hosting. Runtime .NET dan app bundle diunduh ke klien di latar belakang dan di-cache sehingga dapat digunakan pada kunjungan mendatang.

Mode Render otomatis tidak pernah secara dinamis mengubah mode render komponen yang sudah ada di halaman. Mode Render otomatis membuat keputusan awal tentang jenis interaktivitas mana yang akan digunakan untuk komponen, lalu komponen menyimpan jenis interaktivitas tersebut selama berada di halaman. Salah satu faktor dalam keputusan awal ini adalah mempertimbangkan apakah komponen sudah ada di halaman dengan interaktivitas WebAssembly/Server. Mode otomatis lebih suka memilih mode render yang cocok dengan mode render komponen interaktif yang ada. Alasan bahwa mode Otomatis lebih suka menggunakan mode interaktivitas yang ada adalah untuk menghindari memperkenalkan runtime interaktif baru yang tidak berbagi status dengan runtime yang ada.

Komponen yang menggunakan mode Render otomatis harus dibangun dari proyek klien terpisah yang menyiapkan Blazor WebAssembly host.

Dalam contoh berikut, komponen interaktif sepanjang proses. Tombol memanggil UpdateMessage metode ketika dipilih. Nilai message perubahan, dan komponen dirender untuk memperbarui pesan di UI. Awalnya, komponen dirender secara interaktif dari server, tetapi pada kunjungan berikutnya dirender dari klien setelah runtime .NET dan app bundle diunduh dan di-cache.

RenderMode4.razor:

@page "/render-mode-4"
@rendermode InteractiveAuto

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Jika menggunakan komponen sebelumnya secara lokal di Blazor Aplikasi Web, tempatkan komponen di folder proyek Pages klien. Proyek klien adalah proyek solusi dengan nama yang berakhiran .Client. Saat aplikasi berjalan, navigasikan ke /render-mode-4 di bilah alamat browser.

Penyebaran mode render

Mode render menyebar ke hierarki komponen.

Aturan untuk menerapkan mode render:

  • Mode render default adalah Statis.
  • Mode render Interactive Server (InteractiveServer), Interactive WebAssembly (InteractiveWebAssembly), dan Interactive Auto (InteractiveAuto) dapat digunakan dari komponen, termasuk menggunakan mode render yang berbeda untuk komponen saudara.
  • Anda tidak dapat beralih ke mode render interaktif yang berbeda dalam komponen anak. Misalnya, komponen Server tidak dapat menjadi anak dari komponen WebAssembly.
  • Parameter yang diteruskan ke komponen turunan interaktif dari induk Statis harus ON yang dapat diserialisasikan JS. Ini berarti Anda tidak dapat meneruskan fragmen render atau konten turunan dari komponen induk Statis ke komponen anak interaktif.

Contoh berikut menggunakan komponen non-halaman SharedMessage yang tidak dapat dirutekan. Komponen agnostik SharedMessage mode render tidak menerapkan mode render dengan direktif@attribute. Jika Anda menguji skenario ini dengan Blazor Aplikasi Web, letakkan komponen berikut di folder aplikasi Components .

SharedMessage.razor:

<p>@Greeting</p>

<button @onclick="UpdateMessage">Click me</button> @message

<p>@ChildContent</p>

@code {
    private string message = "Not updated yet.";

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    [Parameter]
    public string Greeting { get; set; } = "Hello!";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

Pewarisan mode render

SharedMessage Jika komponen ditempatkan dalam komponen induk yang dirender secara statis, SharedMessage komponen juga dirender secara statis dan tidak interaktif. Tombol tidak memanggil UpdateMessage, dan pesan tidak diperbarui.

RenderMode5.razor:

@page "/render-mode-5"

<SharedMessage />

SharedMessage Jika komponen ditempatkan dalam komponen yang menentukan mode render, komponen akan mewarisi mode render yang diterapkan.

Dalam contoh berikut, SharedMessage komponen interaktif melalui SignalR koneksi ke klien. Tombol memanggil UpdateMessage, dan pesan diperbarui.

RenderMode6.razor:

@page "/render-mode-6"
@rendermode InteractiveServer

<SharedMessage />

Komponen turunan dengan mode render yang berbeda

Dalam contoh berikut, kedua SharedMessage komponen telah dirender (secara default) dan muncul ketika halaman ditampilkan di browser.

  • Komponen pertama SharedMessage dengan penyajian sisi server interaktif (SSR interaktif) interaktif setelah SignalR sirkuit dibuat.
  • Komponen kedua SharedMessage dengan penyajian sisi klien (CSR) interaktif setelahBlazor bundel aplikasi diunduh dan runtime .NET aktif pada klien.

RenderMode7.razor:

@page "/render-mode-7"

<SharedMessage @rendermode="InteractiveServer" />
<SharedMessage @rendermode="InteractiveWebAssembly" />

Komponen anak dengan parameter yang dapat diserialisasikan

Contoh berikut menunjukkan komponen anak interaktif yang mengambil parameter. Parameter harus dapat diserialisasikan.

RenderMode8.razor:

@page "/render-mode-8"

<SharedMessage @rendermode="InteractiveServer" Greeting="Welcome!" />

Parameter komponen yang tidak dapat diserialisasikan, seperti konten turunan atau fragmen render, tidak didukung. Dalam contoh berikut, meneruskan konten anak ke SharedMessage komponen menghasilkan kesalahan runtime.

RenderMode9.razor:

@page "/render-mode-9"

<SharedMessage @rendermode="InteractiveServer">
    Child content
</SharedMessage>

Kesalahan:

System.InvalidOperationException: Tidak dapat meneruskan parameter 'ChildContent' ke komponen 'SharedMessage' dengan rendermode 'InteractiveServerRenderMode'. Ini karena parameter adalah jenis delegasi 'Microsoft.AspNetCore.Components.RenderFragment', yang merupakan kode arbitrer dan tidak dapat diserialisasikan.

Untuk menghindari batasan sebelumnya, bungkus komponen anak di komponen lain yang tidak memiliki parameter . Ini adalah pendekatan yang diambil dalam Blazor templat proyek Aplikasi Web dengan Routes komponen (Components/Routes.razor) untuk membungkus Router komponen.

WrapperComponent.razor:

<SharedMessage>
    Child content
</SharedMessage>

RenderMode10.razor:

@page "/render-mode-10"

<WrapperComponent @rendermode="InteractiveServer" />

Dalam contoh sebelumnya:

  • Konten anak diteruskan ke SharedMessage komponen tanpa menghasilkan kesalahan runtime.
  • Komponen SharedMessage merender secara interaktif di server.

Komponen turunan dengan mode render yang berbeda dari induknya

Jangan mencoba menerapkan mode render interaktif yang berbeda ke komponen turunan daripada mode render induknya.

Komponen berikut menghasilkan kesalahan runtime saat komponen dirender:

RenderMode11.razor:

@page "/render-mode-11"
@rendermode InteractiveServer

<SharedMessage @rendermode="InteractiveWebAssembly" />

Kesalahan:

Cannot create a component of type 'BlazorSample.Components.SharedMessage' because its render mode 'Microsoft.AspNetCore.Components.Web.InteractiveWebAssemblyRenderMode' is not supported by Interactive Server rendering.

Halaman SSR statis dalam aplikasi interaktif global

Ada kasus di mana spesifikasi aplikasi memanggil komponen untuk mengadopsi penyajian sisi server statis (SSR statis) dan hanya berjalan di server, sementara aplikasi lainnya menggunakan mode render interaktif.

Pendekatan ini hanya berguna ketika aplikasi memiliki halaman tertentu yang tidak dapat bekerja dengan Server interaktif atau penyajian WebAssembly. Misalnya, adopsi pendekatan ini untuk halaman yang bergantung pada pembacaan/penulisan HTTP cookiedan hanya dapat berfungsi dalam siklus permintaan/respons alih-alih penyajian interaktif. Untuk halaman yang berfungsi dengan penyajian interaktif, Anda tidak boleh memaksanya untuk menggunakan penyajian SSR statis, karena kurang efisien dan kurang responsif bagi pengguna akhir.

Tandai halaman komponen apa pun Razor dengan atribut yang [ExcludeFromInteractiveRouting] ditetapkan dengan direktif @attributeRazor :

@attribute [ExcludeFromInteractiveRouting]

Menerapkan atribut menyebabkan navigasi ke halaman keluar dari perutean interaktif. Navigasi masuk dipaksa untuk melakukan pemuatan ulang halaman penuh sebagai gantinya menyelesaikan halaman melalui perutean interaktif. Pemuatan ulang halaman penuh memaksa komponen akar tingkat atas, biasanya App komponen (App.razor), untuk merender dari server, memungkinkan aplikasi beralih ke mode render tingkat atas yang berbeda.

Metode HttpContext.AcceptsInteractiveRouting ekstensi memungkinkan komponen mendeteksi apakah [ExcludeFromInteractiveRouting] diterapkan ke halaman saat ini.

App Dalam komponen, gunakan pola dalam contoh berikut:

  • Halaman yang tidak dianotasi dengan [ExcludeFromInteractiveRouting] default ke InteractiveServer mode render dengan interaktivitas global. Anda dapat mengganti InteractiveServer dengan InteractiveWebAssembly atau InteractiveAuto untuk menentukan mode render global default yang berbeda.
  • Halaman yang dianotasi dengan [ExcludeFromInteractiveRouting] mengadopsi SSR statis (PageRenderMode ditetapkan null).
<!DOCTYPE html>
<html>
<head>
    ...
    <HeadOutlet @rendermode="@PageRenderMode" />
</head>
<body>
    <Routes @rendermode="@PageRenderMode" />
    ...
</body>
</html>

@code {
    [CascadingParameter]
    private HttpContext HttpContext { get; set; } = default!;

    private IComponentRenderMode? PageRenderMode
        => HttpContext.AcceptsInteractiveRouting() ? InteractiveServer : null;
}

Alternatif untuk menggunakan HttpContext.AcceptsInteractiveRouting metode ekstensi adalah membaca metadata titik akhir secara manual menggunakan HttpContext.GetEndpoint()?.Metadata.

Ada dua pendekatan yang dapat diambil untuk kontrol halus mode render, yang masing-masing dijelaskan dalam subbagian berikut:

  • Area (folder) komponen SSR statis: Anda memiliki area (folder) aplikasi dengan komponen yang harus mengadopsi SSR statis dan berbagi awalan jalur rute yang sama. Aplikasi mengontrol mode render secara global dengan mengatur mode render pada Routes komponen dalam App komponen berdasarkan jalur ke folder.

  • Komponen SSR statis tersebar di seluruh aplikasi: Anda memiliki komponen yang tersebar di berbagai lokasi yang harus mengadopsi SSR statis dan hanya berjalan di server. Komponen khusus SSR statis tidak berada dalam satu folder dan tidak berbagi awalan jalur rute umum. Aplikasi mengontrol mode render berdasarkan per komponen dengan mengatur mode render dengan direktif @rendermode dalam instans komponen. Pantulan digunakan dalam App komponen untuk mengatur mode render pada Routes komponen.

Dalam kedua kasus, komponen yang harus mengadopsi SSR statis juga harus memaksa pemuatan ulang halaman penuh.

Contoh berikut menggunakan HttpContext parameter berskala untuk menentukan apakah halaman dirender secara statis. A nullHttpContext menunjukkan bahwa komponen dirender secara interaktif, yang berguna sebagai sinyal dalam kode aplikasi untuk memicu pemuatan ulang halaman penuh.

Area (folder) komponen SSR statis

Pendekatan yang dijelaskan dalam subbagian ini digunakan oleh Blazor templat proyek Aplikasi Web dengan autentikasi individual dan interaktivitas global.

Area (folder) aplikasi berisi komponen yang harus mengadopsi SSR statis dan hanya berjalan di server. Komponen dalam folder berbagi awalan jalur rute yang sama. Misalnya, IdentityRazor komponen Blazor templat proyek Aplikasi Web berada di Components/Account/Pages folder dan berbagi awalan /Accountjalur akar .

Folder juga berisi _Imports.razor file, yang menerapkan tata letak akun kustom ke komponen dalam folder:

@using BlazorSample.Components.Account.Shared
@layout AccountLayout

Folder Shared mempertahankan AccountLayout komponen tata letak. Komponen memanfaatkan HttpContext untuk menentukan apakah komponen merender di server. Identity komponen harus dirender di server dengan SSR statis karena diatur Identitycookie. Jika nilainya HttpContext adalah null, komponen dirender secara interaktif, dan pemuatan ulang halaman penuh dilakukan dengan memanggil NavigationManager.Refresh dengan forceLoad diatur ke true. Ini memaksa rerender penuh halaman menggunakan SSR statis.

Components/Account/Shared/AccountLayout.razor:

@inherits LayoutComponentBase
@layout BlazorSample.Components.Layout.MainLayout
@inject NavigationManager NavigationManager

@if (HttpContext is null)
{
    <p>Loading...</p>
}
else
{
    @Body
}

@code {
    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override void OnParametersSet()
    {
        if (HttpContext is null)
        {
            NavigationManager.Refresh(forceReload: true);
        }
    }
}

Catatan

Blazor Di templat proyek Aplikasi Web, ada file tata letak kedua (ManageLayout.razor di Components/Account/Shared folder) untuk Identity komponen di Components/Account/Pages/Manage folder. Folder Manage memiliki filenya sendiri _Imports.razor untuk diterapkan ke ManageLayout komponen dalam folder. Di aplikasi Anda sendiri, menggunakan file berlapis _Imports.razor adalah pendekatan yang berguna untuk menerapkan tata letak kustom ke grup halaman.

App Dalam komponen, permintaan apa pun untuk komponen dalam Account folder menerapkan null mode render, yang memberlakukan SSR statis. Permintaan komponen lain menerima aplikasi global dari mode render SSR interaktif (InteractiveServer).

Penting

Menerapkan null mode render tidak selalu memberlakukan SSR statis. Kebetulan berulah seperti itu menggunakan pendekatan yang ditunjukkan di bagian ini.

null Mode render secara efektif sama dengan tidak menentukan mode render, yang menghasilkan komponen yang mewarisi mode render induknya. Dalam hal ini, komponen dirender App menggunakan SSR statis, sehingga null mode render menghasilkan Routes komponen yang mewarisi SSR statis dari App komponen. Jika mode render null ditentukan untuk komponen anak yang induknya menggunakan mode render interaktif, anak akan mewarisi mode render interaktif yang sama.

Components/App.razor:

<Routes @rendermode="RenderModeForPage" />

...

@code {
    [CascadingParameter]
    private HttpContext HttpContext { get; set; } = default!;

    private IComponentRenderMode? RenderModeForPage => 
        HttpContext.Request.Path.StartsWithSegments("/Account")
            ? null
            : {INTERACTIVE RENDER MODE};
}

Dalam kode sebelumnya, ubah {INTERACTIVE RENDER MODE} tempat penampung ke nilai yang sesuai, tergantung pada apakah aplikasi lainnya harus mengadopsi global InteractiveServer, InteractiveWebAssembly, atau InteractiveAuto penyajian.

Komponen yang harus mengadopsi SSR statis di Account folder tidak diperlukan untuk mengatur tata letak karena diterapkan melalui _Imports.razor file, dan komponen tidak mengatur mode render karena harus dirender dengan SSR statis. Tidak ada yang lebih lanjut harus dilakukan untuk komponen dalam Account folder untuk memberlakukan SSR statis.

Komponen SSR statis tersebar di seluruh aplikasi

Pada subbagian sebelumnya, aplikasi mengontrol mode render komponen dengan mengatur mode render secara global dalam App komponen. Atau, App komponen juga dapat mengadopsi mode render per komponen untuk mengatur mode render, yang memungkinkan komponen yang tersebar di sekitar aplikasi untuk menerapkan adopsi SSR statis. Sub bagian ini menjelaskan pendekatannya.

Aplikasi ini memiliki tata letak kustom yang dapat diterapkan ke komponen di sekitar aplikasi. Biasanya, komponen bersama untuk aplikasi ditempatkan di Components/Layout folder . Komponen memanfaatkan HttpContext untuk menentukan apakah komponen merender di server. Jika nilainya HttpContext adalah null, komponen dirender secara interaktif, dan pemuatan ulang halaman penuh dilakukan dengan memanggil NavigationManager.Refresh dengan forceLoad diatur ke true. Ini memicu permintaan ke server untuk komponen.

Components/Layout/StaticSsrLayout.razor:

@inherits LayoutComponentBase
@layout MainLayout
@inject NavigationManager NavigationManager

@if (HttpContext is null)
{
    <p>Loading...</p>
}
else
{
    @Body
}

@code {
    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override void OnParametersSet()
    {
        if (HttpContext is null)
        {
            NavigationManager.Refresh(forceReload: true);
        }
    }
}

App Dalam komponen, pantulan digunakan untuk mengatur mode render. Mode render apa pun yang ditetapkan ke file definisi komponen individual diterapkan ke Routes komponen.

Components/App.razor:

<Routes @rendermode="RenderModeForPage" />

...

@code {
    [CascadingParameter]
    private HttpContext HttpContext { get; set; } = default!;

    private IComponentRenderMode? RenderModeForPage =>
        HttpContext.GetEndpoint()?.Metadata.GetMetadata<RenderModeAttribute>()?
            .Mode;
}

Setiap komponen yang harus mengadopsi SSR statis mengatur tata letak kustom dan tidak menentukan mode render. Tidak menentukan mode render menghasilkan null nilai RenderModeAttribute.Mode dalam App komponen, yang tidak menghasilkan mode render yang ditetapkan ke Routes instans komponen dan penerapan SSR statis.

Penting

Menerapkan null mode render tidak selalu memberlakukan SSR statis. Kebetulan berulah seperti itu menggunakan pendekatan yang ditunjukkan di bagian ini.

null Mode render secara efektif sama dengan tidak menentukan mode render, yang menghasilkan komponen yang mewarisi mode render induknya. Dalam hal ini, komponen dirender App menggunakan SSR statis, sehingga null mode render menghasilkan Routes komponen yang mewarisi SSR statis dari App komponen. Jika mode render null ditentukan untuk komponen anak yang induknya menggunakan mode render interaktif, anak akan mewarisi mode render interaktif yang sama.

Tidak ada yang lebih lanjut harus dilakukan agar komponen memberlakukan SSR statis daripada menerapkan tata letak kustom tanpa mengatur mode render interaktif:

@layout BlazorSample.Components.Layout.StaticSsrLayout

Komponen interaktif di sekitar aplikasi menghindari penerapan tata letak SSR statis kustom dan hanya mengatur mode render interaktif yang sesuai, yang setelah refleksi dalam App komponen diterapkan ke Routes komponen:

@rendermode {INTERACTIVE RENDER MODE}

Dalam kode sebelumnya, ubah {INTERACTIVE RENDER MODE} tempat penampung ke nilai yang sesuai, tergantung pada apakah komponen harus mengadopsi InteractiveServer, , InteractiveWebAssemblyatau InteractiveAuto penyajian.

Layanan sisi klien gagal diselesaikan selama pra-penyajian

Dengan asumsi bahwa pra-penyajian tidak dinonaktifkan untuk komponen atau untuk aplikasi, komponen dalam .Client proyek telah dirender di server. Karena server tidak memiliki akses ke layanan sisi Blazor klien terdaftar, tidak mungkin untuk menyuntikkan layanan ini ke dalam komponen tanpa menerima kesalahan bahwa layanan tidak dapat ditemukan selama pra-penyajian.

Misalnya, pertimbangkan komponen berikut Home dalam proyek di Blazor Aplikasi Web dengan rendering Interactive WebAssembly atau Interactive .Client Auto global. Komponen mencoba menyuntikkan IWebAssemblyHostEnvironment untuk mendapatkan nama lingkungan.

@page "/"
@inject IWebAssemblyHostEnvironment Environment

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<p>
    Environment: @Environment.Environment
</p>

Tidak terjadi kesalahan waktu kompilasi, tetapi terjadi kesalahan runtime selama pra-penyajian:

Tidak dapat memberikan nilai untuk properti 'Lingkungan' pada jenis 'BlazorSample.Client.Pages.Home'. Tidak ada layanan terdaftar jenis 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

Kesalahan ini terjadi karena komponen harus mengkompilasi dan menjalankan pada server selama pra-penyajian, tetapi IWebAssemblyHostEnvironment bukan layanan terdaftar di server.

Jika aplikasi tidak memerlukan nilai selama pra-penyajian, masalah ini dapat diselesaikan dengan menyuntikkan IServiceProvider untuk mendapatkan layanan alih-alih jenis layanan itu sendiri:

@page "/"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IServiceProvider Services

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<p>
    <b>Environment:</b> @environmentName
</p>

@code {
    private string? environmentName;

    protected override void OnInitialized()
    {
        if (Services.GetService<IWebAssemblyHostEnvironment>() is { } env)
        {
            environmentName = env.Environment;
        }
    }
}

Namun, pendekatan sebelumnya tidak berguna jika logika Anda memerlukan nilai selama pra-penyajian.

Anda juga dapat menghindari masalah jika Anda menonaktifkan pra-penyajian untuk komponen, tetapi itu adalah langkah ekstrem yang harus diambil dalam banyak kasus yang mungkin tidak memenuhi spesifikasi komponen Anda.

Ada tiga pendekatan yang dapat Anda ambil untuk mengatasi skenario ini. Berikut ini dicantumkan dari yang paling direkomendasikan ke yang paling tidak direkomendasikan:

  • Direkomendasikan untuk layanan kerangka kerja bersama: Untuk layanan kerangka kerja bersama yang hanya tidak terdaftar di sisi server dalam proyek utama, daftarkan layanan di proyek utama, yang membuatnya tersedia selama pra-penyajian. Untuk contoh skenario ini, lihat panduan untuk HttpClient layanan di Memanggil API web dari aplikasi ASP.NET CoreBlazor.

  • Direkomendasikan untuk layanan di luar kerangka kerja bersama: Buat implementasi layanan kustom untuk layanan di server. Gunakan layanan secara normal dalam komponen .Client interaktif proyek. Untuk demonstrasi pendekatan ini, lihat lingkungan ASP.NET CoreBlazor.

  • Buat abstraksi layanan dan buat implementasi untuk layanan dalam .Client proyek server dan . Daftarkan layanan di setiap proyek. Masukkan layanan kustom dalam komponen.

  • Anda mungkin dapat menambahkan .Client referensi paket proyek ke paket sisi server dan kembali menggunakan API sisi server saat melakukan prarender di server.

Menemukan komponen dari rakitan tambahan

Rakitan tambahan harus diungkapkan ke Blazor kerangka kerja untuk menemukan komponen yang dapat dirutekan Razor dalam proyek yang direferensikan. Untuk informasi selengkapnya, lihat perutean dan navigasi ASP.NET CoreBlazor.

Penutupan sirkuit ketika tidak ada komponen Server Interaktif yang tersisa

Komponen Server Interaktif menangani peristiwa UI web menggunakan koneksi real-time dengan browser yang disebut sirkuit. Sirkuit dan status terkait dibuat ketika komponen Server Interaktif akar dirender. Sirkuit ditutup ketika tidak ada komponen Server Interaktif yang tersisa di halaman, yang membebaskan sumber daya server.

Mode render singkat kustom

Direktif @rendermode mengambil satu parameter yang merupakan instans statis jenis IComponentRenderMode. Atribut @rendermode direktif dapat mengambil instans mode render apa pun, statis atau tidak. Blazor Kerangka kerja ini menyediakan RenderMode kelas statis dengan beberapa mode render yang telah ditentukan sebelumnya untuk kenyamanan, tetapi Anda dapat membuat sendiri.

Biasanya, komponen menggunakan direktif berikut @rendermode untuk menonaktifkan pra-penyajian:

@rendermode @(new InteractiveServerRenderMode(prerender: false))

Namun, pertimbangkan contoh berikut yang membuat mode render sisi server interaktif singkat tanpa melakukan pra-penyajian melalui file aplikasi _Imports (Components/_Imports.razor):

public static IComponentRenderMode InteractiveServerWithoutPrerendering { get; } = 
    new InteractiveServerRenderMode(prerender: false);

Gunakan mode render singkat dalam komponen di Components seluruh folder:

@rendermode InteractiveServerWithoutPrerendering

Atau, instans komponen tunggal dapat menentukan mode render kustom melalui bidang privat:

@rendermode interactiveServerWithoutPrerendering

...

@code {
    private static IComponentRenderMode interactiveServerWithoutPrerendering = 
        new InteractiveServerRenderMode(prerender: false);
}

Saat ini, pendekatan mode render singkat mungkin hanya berguna untuk mengurangi verbositas menentukan prerender bendera. Pendekatan singkat mungkin lebih berguna di masa depan jika bendera tambahan tersedia untuk penyajian interaktif dan Anda ingin membuat mode render singkat dengan kombinasi bendera yang berbeda.

Injeksi layanan melalui file impor tingkat atas (_Imports.razor)

Bagian ini hanya berlaku untuk Blazor Web Apps.

File impor tingkat atas di Components folder (Components/_Imports.razor) menyuntikkan referensinya ke semua komponen dalam hierarki folder, yang mencakup App komponen (App.razor). Komponen App selalu dirender secara statis bahkan jika prarender komponen halaman dinonaktifkan. Oleh karena itu, menyuntikkan layanan melalui tingkat atas mengimpor hasil file dalam menyelesaikan dua instans layanan dalam komponen halaman.

Untuk mengatasi skenario ini, masukkan layanan dalam file impor baru yang ditempatkan di Pages folder (Components/Pages/_Imports.razor). Dari lokasi tersebut, layanan hanya diselesaikan sekali dalam komponen halaman.

Sumber Daya Tambahan: