mode render ASP.NET Core Blazor

Artikel ini menjelaskan pengaturan perenderan komponen Razor dalam Blazor Web Apps, baik pada waktu kompilasi atau waktu jalan.

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 render mode. 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 Web App mengadopsi mode rendering untuk menentukan model hosting yang digunakannya, di mana ia dirender, dan apakah interaktif. Interaktivitas memungkinkan pengguna untuk berinteraksi dengan komponen yang telah dirender. Ini mencakup respons aplikasi terhadap peristiwa dan perubahan status Document Object Model (DOM) yang terkait dengan anggota C# melalui pengelola peristiwa dan pengikatan Blazor.

Tabel berikut ini memperlihatkan mode render yang tersedia untuk komponen penyajian Razor dalam Blazor Web App. 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 proses render	Interaktif
Server Statik	Penyajian sisi server statis (SSR statis)	pelayan	❌ Tidak
Server Interaktif	Penyajian sisi server interaktif (SSR interaktif) menggunakan Blazor Server.	pelayan	✔️Ya
Perakitan Web Interaktif	Rendering di sisi klien (CSR) menggunakan Blazor WebAssembly†.	Klien	✔️Ya
Mobil Interaktif	SSR interaktif memanfaatkan Blazor Server pada awalnya dan kemudian beralih ke CSR pada kunjungan berikutnya setelah bundel Blazor diunduh.	Server, lalu klien	✔️Ya

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

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

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 Web App templat proyek. 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 Web App, lihat Alat untuk ASP.NET Core Blazor.

Mengaktifkan dukungan untuk mode render interaktif

Sebuah Blazor Web App harus dikonfigurasi untuk mendukung mode render interaktif. Ekstensi berikut secara otomatis diterapkan ke aplikasi yang dibuat dari Blazor Web App templat proyek selama pembuatan aplikasi. Komponen individual tetap diharuskan untuk mendeklarasikan mode render mereka sesuai dengan bagian Render modes setelah layanan komponen dan titik akhir dikonfigurasi dalam file aplikasi Program.

Layanan untuk komponen Razor ditambahkan dengan memanggil AddRazorComponents.

Ekstensi penyusun komponen:

• AddInteractiveServerComponents menambahkan layanan untuk mendukung penyajian komponen Server Interaktif.
• AddInteractiveWebAssemblyComponents menambahkan layanan untuk mendukung penyajian komponen Interactive WebAssembly.

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:

• AddInteractiveServerRenderMode mengonfigurasi penyajian sisi server interaktif (SSR interaktif) untuk aplikasi.
• AddInteractiveWebAssemblyRenderMode mengonfigurasi mode render Interactive WebAssembly untuk aplikasi.

Catatan

Untuk orientasi pada penempatan API dalam contoh berikut, periksa Program file aplikasi yang dihasilkan dari Blazor Web App templat proyek. Untuk panduan tentang cara membuat Blazor Web App, 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();

Blazor Blazor 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. Blazor Web App Templat 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 direktif @rendermodeRazor di mana komponen tersebut 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 singkatan kustom di bagian selanjutnya dari 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 menggunakan mode render yang sama dengan komponen Router yang merender halaman tersebut.

Secara teknis, @rendermode adalah Razordirektif dan Razoratribut direktif. Semantiknya mirip, tetapi ada perbedaan. Direktif @rendermode ada pada definisi komponen, sehingga instans mode render yang direferensikan harus statis. Atribut @rendermode direktif dapat mengambil instance 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. Komponen harus menghindari asumsi tentang di mana ia berjalan (server atau klien) dan harus dapat menyesuaikan diri 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 komponen App, tidak tersedia. Oleh karena itu, mode render untuk seluruh aplikasi tidak dapat diatur langsung oleh App komponen.

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

<Routes @rendermode="InteractiveServer" />

Komponen Router meneruskan mode pemrosesannya ke halaman yang dimuatnya.

Anda juga biasanya harus mengatur mode render interaktif yang sama pada komponen HeadOutlet, yang juga dapat ditemukan di dalam komponen App dari Blazor Web App yang 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 folder Layout di proyek .Client jika tidak ada.
• Tempatkan atau pindahkan komponen folder aplikasi Components/Pages server ke .Client folder proyek Pages . Buat folder Pages di proyek .Client jika tidak ada.
• Tempatkan atau pindahkan komponen Routes dari aplikasi server Components ke folder akar proyek .Client.

Untuk mengaktifkan interaktivitas global saat membuat Blazor Web App:

• Visual Studio: Atur dropdown daftar 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 menurut instans komponen, sangat berguna ketika spesifikasi aplikasi Anda memanggil satu atau beberapa komponen untuk mengadopsi SSR statis di aplikasi interaktif lainnya. Skenario ini dibahas di halaman SSR Statis dalam bagian aplikasi interaktif, yang akan dijelaskan kemudian dalam 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. Bagian Halaman SSR Statis di aplikasi interaktif menunjukkan cara menggunakan pendekatan sebelumnya untuk mengadopsi SSR statis dalam aplikasi interaktif.

Blazor contoh dokumentasi untuk Blazor Web Apps

Saat menggunakan Blazor Web App, sebagian besar contoh komponen dokumentasi Blazor 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

Prerendering adalah proses perenderan awal konten halaman di server tanpa mengaktifkan penangan kejadian untuk kontrol yang telah 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.

Prarendering diaktifkan secara default untuk komponen interaktif.

Navigasi internal dalam perutean interaktif tidak memerlukan permintaan konten halaman baru dari server. Oleh karena itu, prarender tidak terjadi untuk permintaan halaman internal, termasuk untuk navigasi yang ditingkatkan. Untuk informasi selengkapnya, lihat Perutean Statis versus Interaktif, Perutean Interaktif dan Prarender, serta Navigasi yang Ditingkatkan dan Penanganan Formulir.

Menonaktifkan pra-penyajian menggunakan teknik berikut hanya berlaku untuk mode render tingkat atas. Jika komponen induk menentukan mode render, pengaturan prapenggambaran anaknya diabaikan. Perilaku ini sedang diselidiki untuk kemungkinan perubahan dengan rilis .NET 10 pada bulan November 2025.

Untuk menonaktifkan prarendering untuk instans komponen, berikan 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 prarendering di 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 yang didasarkan pada templat proyek Blazor Web App, mode render yang berlaku untuk seluruh aplikasi ditentukan ketika komponen Routes digunakan dalam komponen App (Components/App.razor). Contoh berikut mengatur mode render aplikasi ke Interactive Server dengan prarender dinonaktifkan:

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

Juga, nonaktifkan prarender untuk HeadOutlet komponen di dalam komponen App.

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

Membuat komponen root, seperti komponen App, menjadi interaktif dengan direktif @rendermode pada bagian awal file definisi komponen root (.razor) tidak didukung. Oleh karena itu, prarendering tidak dapat dinonaktifkan secara langsung oleh komponen App.

Mendeteksi lokasi penyajian, interaktivitas, dan mode render yang ditetapkan saat runtime

Properti ComponentBase.RendererInfo dan ComponentBase.AssignedRenderMode mengizinkan aplikasi mendeteksi detail tentang lokasi, interaktivitas, dan mode render komponen yang ditetapkan:

• RendererInfo.Name mengembalikan lokasi tempat komponen dijalankan:
  • Static: Pada server (SSR) dan tidak dapat melakukan interaktivitas.
  • Server: Pada server (SSR) dan dapat berinteraksi setelah prarendering.
  • WebAssembly: Pada klien (CSR) dan mampu interaktif setelah pra-render.
  • WebView: Di perangkat asli dan mampu berinteraksi setelah proses prarendering.
• RendererInfo.IsInteractive menunjukkan apakah komponen mendukung interaktivitas pada saat penyajian. Nilainya adalah true ketika penyajian secara interaktif atau false saat melakukan prarender atau untuk SSR statis (RendererInfo.Name dari Static).
• AssignedRenderMode memperlihatkan mode perenderan komponen yang ditetapkan:
  • InteractiveServerRenderMode untuk Server Interaktif.
  • InteractiveAutoRenderMode untuk Mobil Interaktif.
  • InteractiveWebAssemblyRenderMode untuk Interactive WebAssembly.
  • null jika mode render tidak ditetapkan.

Komponen menggunakan properti ini untuk merender konten tergantung pada lokasi atau status interaktivitasnya. Contoh berikut menunjukkan kasus penggunaan umum.

Tampilkan konten hingga elemen menjadi interaktif.

@if (!RendererInfo.IsInteractive)
{
    <p>Connecting to the assistant...</p>
}
else
{
    ...
}

Nonaktifkan tombol sampai komponen menjadi interaktif.

<button @onclick="Send" disabled="@(!RendererInfo.IsInteractive)">
    Send
</button>

Nonaktifkan formulir selama pra-penyajian dan aktifkan formulir saat komponen interaktif:

<EditForm Model="Movie" ...>
    <fieldset disabled="@disabled">

        ...

        <button type="submit" >Save</button>
    </fieldset>
</EditForm>

@code {
    private bool disabled = true;

    [SupplyParameterFromForm]
    private Movie? Movie { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Movie ??= await ...;

        if (RendererInfo.IsInteractive)
        {
            disabled = false;
        }
    }
}

Render markup untuk mendukung melakukan tindakan HTML reguler jika komponen dirender secara statis:

@if (AssignedRenderMode is null)
{
    // The render mode is Static Server
    <form action="/movies">
        <input type="text" name="titleFilter" />
        <input type="submit" value="Search" />
    </form>
}
else
{
    // The render mode is Interactive Server, WebAssembly, or Auto
    <input @bind="titleFilter" />
    <button @onclick="FilterMovies">Search</button>
}

Dalam contoh sebelumnya:

• Ketika nilai AssignedRenderMode adalah null, komponen mengadopsi SSR statis. Blazor penanganan peristiwa tidak berfungsi di browser dengan SSR statis, sehingga komponen mengirimkan formulir (permintaan GET) dengan string kueri yang titleFilter diatur ke nilai pengguna <input> . Komponen Movie (/movie) dapat membaca string kueri dan memproses nilai titleFilter untuk merender komponen dengan hasil yang difilter.
• Jika tidak, mode render adalah salah satu dari InteractiveServer, InteractiveWebAssembly, atau InteractiveAuto. Komponen ini mampu menggunakan delegasi penanganan aktivitas (FilterMovies) dan nilai yang terikat ke <input> elemen (titleFilter) untuk memfilter film secara interaktif melalui koneksi latar belakang SignalR .

Penyajian sisi server statis (SSR statis)

Komponen menggunakan penyajian sisi server statis (SSR). Komponen merender ke aliran respons dan tidak ada interaktivitas yang 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 ulang sebagai tanggapan 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 Web App, 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, permintaan halaman komponen Razor diproses oleh pipeline middleware ASP.NET Core sisi server untuk perutean dan otorisasi. Fitur khusus Blazor untuk perutean dan otorisasi tidak beroperasi karena komponen Razor tidak dirender selama pemrosesan permintaan sisi server. Blazor fitur router dalam Routes komponen yang tidak tersedia selama SSR statis termasuk menampilkan:

• Konten yang tidak diotorisasi (<NotAuthorized>...</NotAuthorized>) (NotAuthorized): Blazor Web Appbiasanya memproses permintaan yang tidak sah di server dengan menyesuaikan perilaku Middleware Otorisasi.

• Konten tidak ditemukan (<NotFound>...</NotFound>) (NotFound): Server biasanya memproses permintaan URL yang salah dengan menampilkan antarmuka 404 yang disediakan oleh browser atau mengembalikan halaman 404 kustom (atau respons lainnya) melalui middleware ASP.NET Core (misalnya, Blazor Web AppUseStatusCodePagesWithRedirects / ). Untuk informasi selengkapnya, lihat Membuat cara yang lebih sederhana untuk menampilkan UI Not Found 404 dengan Blazor (dotnet/aspnetcore #45654).

Jika aplikasi menunjukkan interaktivitas tingkat utama, pemrosesan permintaan ASP.NET Core di sisi server tidak terlibat setelah SSR statis awal, yang berarti bahwa fitur sebelumnya Blazor berfungsi sebagaimana 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 rangkaian tercipta ketika komponen Server dirender.

Dalam contoh berikut, mode render diatur menjadi SSR interaktif dengan menambahkan @rendermode InteractiveServer pada definisi komponen. Tombol memanggil metode UpdateMessage ketika dipilih. Nilai message berubah, dan komponen di-render ulang 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 dalam Blazor Web App, 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.

Render sisi klien (CSR)

Rendering sisi klien (CSR) melakukan rendering komponen secara interaktif pada klien menggunakan Blazor WebAssembly. Runtime .NET dan app bundle diunduh dan di-cache saat sebuah komponen WebAssembly pertama kali dirender. Komponen yang menggunakan CSR harus dibuat dari proyek klien terpisah yang menyiapkan host Blazor WebAssembly.

Dalam contoh berikut, mode render diatur ke CSR dengan @rendermode InteractiveWebAssembly. Tombol memanggil metode UpdateMessage ketika dipilih. Nilai message berubah, dan komponen di-render ulang 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 Web App, 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 (Auto) menentukan cara menjalankan render komponen saat waktu jalan. Komponen ini awalnya dirender dengan render interaktif sisi server (SSR) menggunakan model hosting Blazor Server. Runtime .NET dan paket aplikasi diunduh ke klien secara background 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 host Blazor WebAssembly.

Dalam contoh berikut, komponen interaktif sepanjang proses. Tombol memanggil metode UpdateMessage ketika dipilih. Nilai message berubah, dan komponen di-render ulang untuk memperbarui pesan di UI. Pada kunjungan pertama, komponen dirender dari sisi server secara interaktif. Namun, pada kunjungan berikutnya, komponen dirender dari sisi 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 Web App, 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 ditransmisikan ke bawah 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 dalam komponen, termasuk menggunakan mode render yang berbeda untuk komponen sejenis.
• 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 komponen induk statis harus dapat diserialisasikan JSON. Ini berarti Anda tidak dapat meneruskan fragmen render atau konten turunan dari komponen induk yang statis ke komponen anak interaktif.

Contoh berikut menggunakan komponen non-halaman SharedMessage yang tidak dapat dirutekan. Komponen SharedMessage mode render agnostik tidak menerapkan mode render dengan direktif@attribute. Jika Anda menguji skenario ini dengan Blazor Web App, tempatkan 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 pemrosesan

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, komponen SharedMessage bersifat interaktif melalui koneksi SignalR ke klien. Tombol memanggil UpdateMessage, dan pesan diperbarui.

RenderMode6.razor:

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

<SharedMessage />

Komponen anak dengan mode render yang berbeda

Dalam contoh berikut, kedua komponen SharedMessage dirender sebelumnya dan muncul saat halaman ditampilkan di browser.

• Komponen pertama SharedMessage dengan penyajian sisi server interaktif (SSR interaktif) menjadi interaktif setelah sirkuit BlazorSignalR dibuat.
• Komponen kedua SharedMessage dengan penyajian sisi klien (CSR) menjadi interaktif setelah 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 diserialkan

Contoh berikut menunjukkan komponen anak interaktif yang menerima 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 komponen SharedMessage menghasilkan kesalahan waktu proses.

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.

Hal yang sama terjadi jika Anda mencoba mengadopsi penyajian interaktif dalam tata letak yang mewarisi dari LayoutComponentBase, seperti komponen MainLayout dalam aplikasi yang mengadopsi penyajian per halaman/komponen. Untuk informasi selengkapnya, lihat ASP.NET Core Blazor layout.

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

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 anak dengan mode render yang berbeda dari komponen induknya

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

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

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 membaca/menulis cookie HTTP dan hanya dapat berfungsi dalam siklus permintaan/respons alih-alih penyajian interaktif. Untuk halaman yang berfungsi dengan penyajian interaktif, Anda tidak boleh memaksanya menggunakan SSR statis, karena kurang efisien dan kurang responsif bagi pengguna akhir.

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

@attribute [ExcludeFromInteractiveRouting]

Menerapkan atribut menyebabkan navigasi ke halaman keluar dari routing interaktif. Navigasi masuk dipaksa melakukan pemuatan ulang halaman penuh alih-alih menyelesaikan halaman melalui perutean interaktif. Pemuatan ulang seluruh halaman memaksakan komponen akar tingkat atas, biasanya komponen App (App.razor), untuk merender ulang dari server, membuat aplikasi dapat beralih ke mode render tingkat atas yang berbeda.

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

App Dalam komponen, gunakan pola dalam contoh berikut:

• Halaman yang tidak diberi anotasi dengan atribut [ExcludeFromInteractiveRouting] beralih secara default ke InteractiveServer mode penyajian dengan interaktivitas global. Anda dapat mengganti InteractiveServer dengan InteractiveWebAssembly atau InteractiveAuto untuk menentukan mode render global default yang berbeda.
• Halaman yang diberi anotasi dengan atribut mengadopsi SSR statis ( ditetapkan ).

<!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 dari penggunaan metode ekstensi RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting adalah membaca metadata endpoint secara manual menggunakan HttpContext.GetEndpoint()?.Metadata.

Layanan sisi klien gagal diselesaikan selama pra-penyajian

Dengan asumsi bahwa prapemrosesan tidak dinonaktifkan untuk komponen atau untuk aplikasi, sebuah komponen dalam proyek .Client diprasajikan di server. Karena server tidak memiliki akses ke layanan sisi Blazor klien terdaftar, tidak dapat menyuntikkan layanan ini ke dalam komponen tanpa menerima kesalahan bahwa layanan tidak dapat ditemukan selama prerendering.

Misalnya, pertimbangkan komponen Home berikut dalam proyek .Client di Blazor Web App dengan Interactive WebAssembly atau Interactive Auto rendering 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 layanan HttpClient dalam Panggil API web dari aplikasi Blazor ASP.NET Core.

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

• Buat abstraksi layanan dan buat implementasi untuk layanan di proyek .Client dan proyek-proyek server. 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.

Temukan komponen dari perakitan tambahan

Rakitan tambahan harus diberitahukan ke Blazor framework untuk menemukan komponen Razor yang dapat dirutekan dalam proyek yang direferensikan. Untuk informasi selengkapnya, lihat Routing dan navigasi Blazor ASP.NET Core.

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 keadaan terkait dibuat ketika komponen Server Interaktif utama dirender. Sirkuit ditutup ketika tidak ada komponen Server Interaktif yang tersisa di halaman, yang membebaskan sumber daya server.

Mode render ringkas 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 seluruh folder Components.

@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 panjangnya penentuan penanda prerender. 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 folder Components (Components/_Imports.razor) akan memasukkan referensinya ke dalam semua komponen di dalam hierarki folder, termasuk komponen App (App.razor). Komponen App selalu dirender secara statis bahkan jika prarender komponen halaman dinonaktifkan. Oleh karena itu, menyuntikkan layanan melalui file impor tingkat atas menghasilkan penyelesaian dua instans layanan dalam komponen dari 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:

• Kompresi WebSocket
  • panduan ASP.NET Core BlazorSignalR
  • Panduan mitigasi ancaman untuk penyajian sisi server interaktif ASP.NET Core Blazor
• ASP.NET Core Blazor JavaScript dengan penyajian sisi server statis (SSR statis)
• Nilai/parameter berjenjang dan batas mode render: Lihat juga bagian nilai berjenjang tingkat akar dan nilai berjenjang tingkat akar dengan pemberitahuan sebelumnya di artikel.
• pustaka kelas ASP.NET Core Razor (RCL) dengan penyajian sisi server statis (SSR statis)
• Mengamankan data dalam Blazor Web Appdengan Penyajian Interaktif Otomatis