Bagikan melalui

Integrasikan komponen ASP.NET Core Razor dengan MVC atau Razor Halaman

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi artikel ini untuk .NET 9.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi lebih lanjut, lihat Kebijakan Dukungan .NET dan .NET Core . Untuk rilis saat ini, lihat versi artikel ini untuk .NET 9.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin akan dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, baik secara tegas maupun tersirat, sehubungan dengan informasi yang disediakan di sini.

Untuk rilis saat ini, lihat versi artikel ini untuk .NET 9.

Komponen Razor dapat diintegrasikan ke dalam Halaman Razor atau aplikasi MVC. Ketika halaman atau tampilan dirender, komponen dapat diprerender pada saat yang sama.

Penting

Perubahan kerangka kerja di berbagai rilis ASP.NET Core menyebabkan munculnya set instruksi yang berbeda dalam artikel ini. Sebelum menggunakan panduan dari artikel ini, pastikan pemilih versi dokumen di bagian atas artikel ini cocok dengan versi ASP.NET Core yang ingin Anda gunakan untuk aplikasi Anda.

Prerendering dapat meningkatkan Search Engine Optimization (SEO) dengan merender konten untuk respons HTTP awal yang dapat digunakan mesin pencari untuk menghitung peringkat halaman.

Setelah mengonfigurasi proyek, gunakan panduan di bagian berikutnya sesuai dengan persyaratan proyek.

Konfigurasi

Gunakan panduan berikut untuk mengintegrasikan komponen Razor ke dalam halaman atau tampilan dari aplikasi Razor Pages atau MVC yang sudah ada.

  1. Tambahkan berkas impor ke folder root proyek dengan isi berikutnya. Ubah placeholder {APP NAMESPACE} menjadi namespace proyek.

    _Imports.razor:

    @using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.JSInterop
@using {APP NAMESPACE}

  2. Dalam berkas tata letak proyek (Pages/Shared/_Layout.cshtml di aplikasi Razor Pages atau Views/Shared/_Layout.cshtml di aplikasi MVC):

    • Tambahkan tag <base> berikut dan komponen Tag Helper HeadOutlet ke dalam elemen <head>.

      <base href="~/" />
<component type="typeof(Microsoft.AspNetCore.Components.Web.HeadOutlet)" 
    render-mode="ServerPrerendered" />

      Nilai href ( jalur dasar aplikasi) dalam contoh sebelumnya mengasumsikan bahwa aplikasi berada di jalur URL akar (/). Jika aplikasi adalah sub-aplikasi, lihat ASP.NET Core Blazor jalur dasar aplikasi.

      Komponen HeadOutlet digunakan untuk merender konten head (<head>) untuk judul halaman (komponen PageTitle) dan elemen head lainnya (komponen HeadContent) yang diatur oleh komponen-komponen Razor. Untuk informasi lebih lanjut, lihat Kontrol konten kepala di aplikasi ASP.NET CoreBlazor.

    • Tambahkan tag <script> untuk skrip blazor.server.js segera sebelum bagian render Scripts (@await RenderSectionAsync(...)).

      <script src="_framework/blazor.server.js"></script>

      Kerangka kerja menambahkan skrip blazor.server.js ke dalam aplikasi. Tidak perlu menambahkan file skrip blazor.server.js secara manual ke aplikasi.

    Catatan

    Biasanya, layout dimuat melalui file _ViewStart.cshtml.

  3. Daftarkan layanan Blazor Server di Program.cs di mana layanan didaftarkan.

    builder.Services.AddServerSideBlazor();

  4. Tambahkan titik akhir Blazor Hub ke titik akhir Program.cs di mana rute dipetakan. Tempatkan baris berikut setelah pemanggilan ke MapRazorPages (Razor Pages) atau MapControllerRoute (MVC):

    app.MapBlazorHub();

  5. Integrasikan komponen ke dalam halaman atau tampilan apa pun. Sebagai contoh, tambahkan komponen Counter ke folder Shared proyek tersebut.

    Pages/Shared/Counter.razor (Razor Halaman) atau Views/Shared/Counter.razor (MVC):

    <h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

    Razor Halaman:

    Di halaman Index proyek dari aplikasi Pages Razor, tambahkan namespace komponen Counter dan tanamkan komponen tersebut ke dalam halaman. Ketika halaman Index dimuat, komponen Counter dirender sebelumnya di dalam halaman. Dalam contoh berikut, gantilah placeholder {APP NAMESPACE} dengan namespace proyek.

    Pages/Index.cshtml:

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

    MVC:

    Dalam tampilan proyek aplikasi MVC, tambahkan namespace komponen dan sematkan komponen ke dalam tampilan. Ketika tampilan Index dimuat, komponen Counter dirender sebelumnya di halaman. Dalam contoh berikut, gantilah placeholder {APP NAMESPACE} dengan namespace proyek.

    Views/Home/Index.cshtml:

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

Untuk informasi lebih lanjut, lihat bagian Render components from a page or view.

Gunakan komponen yang dapat diarahkan dalam aplikasi Pages

Bagian ini berkaitan dengan penambahan komponen yang dapat langsung dirutekan dari permintaan pengguna.

Untuk mendukung komponen Razor yang dapat dirutekan di aplikasi Halaman Razor

  1. Ikuti panduan di bagian Konfigurasi.

  2. Tambahkan komponen App ke root proyek dengan konten berikut.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <p role="alert">Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

  3. Tambahkan halaman _Host ke proyek dengan konten berikut. Ganti placeholder {APP NAMESPACE} dengan namespace aplikasi.

    Pages/_Host.cshtml:

    @page
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

<component type="typeof(App)" render-mode="ServerPrerendered" />

    Catatan

    Contoh sebelumnya mengasumsikan bahwa komponen HeadOutlet dan skrip Blazor (_framework/blazor.server.js) dirender oleh tata letak aplikasi. Untuk informasi lebih lanjut, lihat bagian Configuration.

    RenderMode mengkonfigurasi apakah komponen App.

    • Telah diprarender ke dalam halaman.
    • Apakah di-render sebagai HTML statis pada halaman atau jika itu mencakup informasi yang diperlukan untuk memulai aplikasi Blazor dari agen pengguna.

    Untuk informasi lebih lanjut tentang Component Tag Helper, termasuk penerusan parameter dan konfigurasi RenderMode, lihat Component Tag Helper di ASP.NET Core.

  4. Pada Program.cs titik akhir, tambahkan rute prioritas rendah untuk halaman _Host sebagai titik akhir terakhir.

    app.MapFallbackToPage("/_Host");

  5. Tambahkan komponen berjalur ke dalam proyek. Contoh berikut adalah komponen RoutableCounter yang didasarkan pada komponen Counter dalam template proyek Blazor.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<PageTitle>Routable Counter</PageTitle>

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  6. Jalankan proyek dan navigasikan ke komponen yang dapat diuraikan RoutableCounter di /routable-counter.

Untuk informasi lebih lanjut tentang ruang nama, lihat bagian Ruang nama Komponen.

Gunakan komponen yang dapat di-routing dalam aplikasi MVC

Bagian ini berkaitan dengan penambahan komponen yang dapat langsung dirutekan dari permintaan pengguna.

Untuk mendukung komponen Razor yang dapat diarahkan dalam aplikasi MVC:

  1. Ikuti panduan di bagian Konfigurasi.

  2. Tambahkan komponen App ke root proyek dengan konten berikut.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <p role="alert">Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

  3. Tambahkan tampilan _Host ke proyek dengan konten berikut. Ganti placeholder {APP NAMESPACE} dengan namespace aplikasi.

    Views/Home/_Host.cshtml:

    @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

<component type="typeof(App)" render-mode="ServerPrerendered" />

    Catatan

    Contoh sebelumnya mengasumsikan bahwa komponen HeadOutlet dan skrip Blazor (_framework/blazor.server.js) dirender oleh tata letak aplikasi. Untuk informasi lebih lanjut, lihat bagian Configuration.

    RenderMode mengkonfigurasi apakah komponen App.

    • Telah diprarender ke dalam halaman.
    • Apakah di-render sebagai HTML statis pada halaman atau jika itu mencakup informasi yang diperlukan untuk memulai aplikasi Blazor dari agen pengguna.

    Untuk informasi lebih lanjut tentang Component Tag Helper, termasuk penerusan parameter dan konfigurasi RenderMode, lihat Component Tag Helper di ASP.NET Core.

  4. Tambahkan tindakan ke pengontrol Home.

    Controllers/HomeController.cs:

    public IActionResult Blazor()
{
   return View("_Host");
}

  5. Pada endpoint Program.cs, tambahkan rute prioritas rendah untuk aksi kontroler yang mengembalikan tampilan _Host.

    app.MapFallbackToController("Blazor", "Home");

  6. Buat folder Pages dalam aplikasi MVC dan tambahkan komponen-komponen yang dapat diarahkan. Contoh berikut adalah komponen RoutableCounter yang didasarkan pada komponen Counter dalam template proyek Blazor.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<PageTitle>Routable Counter</PageTitle>

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  7. Jalankan proyek dan navigasikan ke komponen yang dapat diuraikan RoutableCounter di /routable-counter.

Untuk informasi lebih lanjut tentang ruang nama, lihat bagian Ruang nama Komponen.

Render komponen dari halaman atau tampilan

Bagian ini berkaitan dengan menambahkan komponen ke halaman atau tampilan, di mana komponen tersebut tidak dapat langsung diarahkan dari permintaan pengguna.

Untuk merender sebuah komponen dari halaman atau tampilan, gunakan Component Tag Helper.

Render komponen interaktif yang memiliki status

Komponen interaktif berstatus dapat ditambahkan ke halaman atau tampilan Razor.

Ketika halaman atau tampilan dirender:

  • Komponen dirender sebelumnya bersamaan dengan halaman atau tampilan.
  • Status komponen awal yang digunakan untuk prarender telah hilang.
  • Keadaan komponen baru dibuat ketika sambungan SignalR diatur.

Halaman Razor berikut merender komponen Counter.

<h1>Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Untuk informasi lebih lanjut, lihat Component Tag Helper di ASP.NET Core.

Render komponen noninteraktif

Pada halaman Razor berikut, komponen Counter dirender secara statis dengan nilai awal yang ditentukan menggunakan sebuah formulir. Karena komponen dirender secara statis, komponen tersebut tidak interaktif.

<h1>Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Untuk informasi lebih lanjut, lihat Component Tag Helper di ASP.NET Core.

Namespace Komponen

Saat menggunakan folder kustom untuk menyimpan komponen proyek Razor, tambahkan namespace yang mewakili folder tersebut baik ke halaman/tampilan atau ke file _ViewImports.cshtml. Pada contoh berikut:

  • Komponen disimpan dalam folder Components proyek.
  • Placeholder {APP NAMESPACE} adalah namespace proyek. Components mewakili nama folder.
@using {APP NAMESPACE}.Components

File _ViewImports.cshtml terletak di folder Pages dari aplikasi Pages Razor atau folder Views dari aplikasi MVC.

Untuk informasi lebih lanjut, lihat komponen Razor ASP.NET Core.

Mempertahankan keadaan yang sudah diprender

Tanpa mempertahankan status yang telah dirender sebelumnya, status yang digunakan selama proses perenderan akan hilang dan harus dibuat ulang ketika aplikasi sepenuhnya dimuat. Jika ada status yang diatur secara asinkron, UI mungkin akan berkedip saat UI yang sudah dirender sebelumnya digantikan dengan placeholder sementara, dan kemudian dirender sepenuhnya lagi.

Untuk menyimpan status komponen yang telah dirender sebelumnya, gunakan Persist Component State Tag Helper (sumber referensi). Tambahkan tag dari Pembantu Tag, <persist-component-state />, di dalam tag penutup </body> halaman _Host dalam aplikasi yang melakukan pra-render komponen.

Catatan

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis berikutnya dari .NET. Untuk memilih tag untuk rilis tertentu, gunakan daftar dropdown Ganti cabang atau tag. Untuk informasi lebih lanjut, lihat How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205).

Di Pages/_Host.cshtml dari Blazor aplikasi yang ServerPrerendered dalam aplikasi Blazor Server:

<body>
    ...

    <persist-component-state />
</body>

Tentukan status apa yang harus dipertahankan dengan menggunakan layanan PersistentComponentState. Atribut [SupplyParameterFromPersistentComponentState] yang diterapkan ke sebuah properti mendaftarkan callback untuk mempertahankan status selama pra-rendering dan memuatnya saat komponen dirender secara interaktif atau layanan diinisialisasi.

Dalam contoh berikut, placeholder {TYPE} menunjukkan jenis data yang akan disimpan (misalnya, WeatherForecast[]).

@code {
    [SupplyParameterFromPersistentComponentState]
    public {TYPE} Data { get; set; }

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

Dalam contoh berikut, komponen WeatherForecastPreserveState menyimpan keadaan prakiraan cuaca selama prarender dan kemudian mengambil keadaan tersebut untuk menginisialisasi komponen. Tag Helper Persist Component State mempertahankan status komponen setelah semua pemanggilan komponen.

WeatherForecastPreserveState.razor:

@page "/weather-forecast-preserve-state"
@using BlazorSample.Shared
@inject IWeatherForecastService WeatherForecastService

<PageTitle>Weather Forecast</PageTitle>

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from the server.</p>

@if (Forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in Forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    [SupplyParameterFromPersistentComponentState]
    public WeatherForecast[]? Forecasts { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Forecasts ??= await WeatherForecastService.GetForecastAsync(
            DateOnly.FromDateTime(DateTime.Now));
    }
}

Tentukan status apa yang harus dipertahankan dengan menggunakan layanan PersistentComponentState. PersistentComponentState.RegisterOnPersisting mendaftarkan callback untuk mempertahankan status komponen sebelum aplikasi dihentikan sementara. Status aplikasi diambil kembali ketika aplikasi dilanjutkan. Lakukan panggilan pada akhir dari kode inisialisasi untuk menghindari potensi race condition selama pemadaman aplikasi.

Pada contoh berikut:

  • Tempat penampung {TYPE} mewakili jenis data yang akan dipertahankan (misalnya, WeatherForecast[]).
  • Placeholder {TOKEN} adalah string pengidentifikasi negara bagian (misalnya, fetchdata).
@implements IDisposable
@inject PersistentComponentState ApplicationState

...

@code {
    private {TYPE} data;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        if (!ApplicationState.TryTakeFromJson<{TYPE}>(
            "{TOKEN}", out var restored))
        {
            data = await ...;
        }
        else
        {
            data = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson("{TOKEN}", data);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

Dalam contoh berikut, komponen WeatherForecastPreserveState menyimpan keadaan prakiraan cuaca selama prarender dan kemudian mengambil keadaan tersebut untuk menginisialisasi komponen. Tag Helper Persist Component State mempertahankan status komponen setelah semua pemanggilan komponen.

Pages/WeatherForecastPreserveState.razor:

@page "/weather-forecast-preserve-state"
@using BlazorSample.Shared
@implements IDisposable
@inject IWeatherForecastService WeatherForecastService
@inject PersistentComponentState ApplicationState

<PageTitle>Weather Forecast</PageTitle>

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from the server.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[] forecasts = Array.Empty<WeatherForecast>();
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            nameof(forecasts), out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(
                    DateOnly.FromDateTime(DateTime.Now));
        }
        else
        {
            forecasts = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson(nameof(forecasts), forecasts);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

Dengan menginisialisasi komponen dengan kondisi yang sama seperti yang digunakan selama pra-rendering, setiap langkah inisialisasi yang mahal hanya dieksekusi satu kali. UI yang dirender juga sesuai dengan UI yang dirender sebelumnya, sehingga tidak terjadi kedipan di browser.

Keadaan yang telah dirender sebelumnya disimpan dan ditransfer ke klien, di mana keadaan ini digunakan untuk memulihkan keadaan komponen. ASP.NET Core Data Protection menjamin bahwa data ditransfer dengan aman dalam aplikasi Blazor Server.

Ukuran status pra-render dan batas ukuran pesan SignalR

Ukuran status prerendered yang besar mungkin melebihi batas ukuran pesan sirkuit Blazor dari SignalR, yang mengakibatkan hal berikut:

  • Sirkuit SignalR gagal diinisialisasi dengan kesalahan pada klien: Circuit host not initialized.
  • Antarmuka pengguna untuk penyambungan ulang di klien muncul ketika sirkuit gagal berfungsi. Pemulihan tidak mungkin.

Untuk menyelesaikan masalah, gunakan salah satu dari pendekatan berikut ini.

  • Kurangi jumlah data yang Anda masukkan ke dalam keadaan prapemrosesan.
  • Tingkatkan batas ukuran pesanSignalR. PERINGATAN: Meningkatkan batas dapat meningkatkan risiko terjadinya serangan Denial of Service (DoS).

Sumber daya tambahan Blazor Server

Prerendering dapat meningkatkan Search Engine Optimization (SEO) dengan merender konten untuk respons HTTP awal yang dapat digunakan mesin pencari untuk menghitung peringkat halaman.

Setelah mengonfigurasi proyek, gunakan panduan di bagian berikutnya sesuai dengan persyaratan proyek.

Konfigurasi

Gunakan panduan berikut untuk mengintegrasikan komponen Razor ke dalam halaman atau tampilan dari aplikasi Razor Pages atau MVC yang sudah ada.

Penting

Penggunaan halaman tata letak (_Layout.cshtml) dengan Component Tag Helper untuk komponen HeadOutlet diperlukan untuk mengontrol konten <head>, seperti judul halaman (komponen PageTitle) dan elemen kepala lainnya (komponen HeadContent). Untuk informasi lebih lanjut, lihat Kontrol konten kepala di aplikasi ASP.NET CoreBlazor.

  1. Dalam file tata letak proyek:

    • Tambahkan tag <base> dan Tag Helper komponen HeadOutlet berikut ke elemen <head> di Pages/Shared/_Layout.cshtml (Razor Halaman) atau Views/Shared/_Layout.cshtml (MVC):

      <base href="~/" />
<component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

      Nilai href ( jalur dasar aplikasi) dalam contoh sebelumnya mengasumsikan bahwa aplikasi berada di jalur URL akar (/). Jika aplikasi adalah sub-aplikasi, lihat ASP.NET Core Blazor jalur dasar aplikasi.

      Komponen HeadOutlet digunakan untuk merender konten head (<head>) untuk judul halaman (komponen PageTitle) dan elemen head lainnya (komponen HeadContent) yang diatur oleh komponen-komponen Razor. Untuk informasi lebih lanjut, lihat Kontrol konten kepala di aplikasi ASP.NET CoreBlazor.

    • Tambahkan tag <script> untuk script blazor.server.js tepat sebelum bagian render Scripts (@await RenderSectionAsync(...)) dalam tata letak aplikasi.

      Pages/Shared/_Layout.cshtml (Razor Halaman) atau Views/Shared/_Layout.cshtml (MVC):

      <script src="_framework/blazor.server.js"></script>

      Kerangka kerja menambahkan skrip blazor.server.js ke dalam aplikasi. Tidak perlu menambahkan file skrip blazor.server.js secara manual ke aplikasi.

  2. Tambahkan berkas impor ke folder root proyek dengan isi berikutnya. Ubah placeholder {APP NAMESPACE} menjadi namespace proyek.

    _Imports.razor:

    @using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.JSInterop
@using {APP NAMESPACE}

  3. Daftarkan layanan Blazor Server di Program.cs di mana layanan didaftarkan.

    builder.Services.AddServerSideBlazor();

  4. Tambahkan titik akhir Blazor Hub ke titik akhir Program.cs di mana rute dipetakan.

    Tempatkan baris berikut setelah pemanggilan ke MapRazorPages (Razor Pages) atau MapControllerRoute (MVC):

    app.MapBlazorHub();

  5. Integrasikan komponen ke dalam halaman atau tampilan apa pun. Sebagai contoh, tambahkan komponen Counter ke folder Shared proyek tersebut.

    Pages/Shared/Counter.razor (Razor Halaman) atau Views/Shared/Counter.razor (MVC):

    <h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

    Razor Halaman:

    Di halaman Index proyek dari aplikasi Pages Razor, tambahkan namespace komponen Counter dan tanamkan komponen tersebut ke dalam halaman. Ketika halaman Index dimuat, komponen Counter dirender sebelumnya di dalam halaman. Dalam contoh berikut, gantilah placeholder {APP NAMESPACE} dengan namespace proyek.

    Pages/Index.cshtml:

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

    MVC:

    Dalam tampilan proyek aplikasi MVC, tambahkan namespace komponen dan sematkan komponen ke dalam tampilan. Ketika tampilan Index dimuat, komponen Counter dirender sebelumnya di halaman. Dalam contoh berikut, gantilah placeholder {APP NAMESPACE} dengan namespace proyek.

    Views/Home/Index.cshtml:

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

Untuk informasi lebih lanjut, lihat bagian Render components from a page or view.

Gunakan komponen yang dapat diarahkan dalam aplikasi Pages

Bagian ini berkaitan dengan penambahan komponen yang dapat langsung dirutekan dari permintaan pengguna.

Untuk mendukung komponen Razor yang dapat dirutekan di aplikasi Halaman Razor

  1. Ikuti panduan di bagian Konfigurasi.

  2. Tambahkan komponen App ke root proyek dengan konten berikut.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <p role="alert">Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

  3. Tambahkan halaman _Host ke proyek dengan konten berikut.

    Pages/_Host.cshtml:

    @page "/blazor"
@namespace {APP NAMESPACE}.Pages.Shared
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@{
    Layout = "_Layout";
}

<component type="typeof(App)" render-mode="ServerPrerendered" />

    Dalam skenario ini, komponen menggunakan file _Layout.cshtml yang dibagikan untuk tata letaknya.

    Penting

    Penggunaan halaman tata letak (_Layout.cshtml) dengan Component Tag Helper untuk komponen HeadOutlet diperlukan untuk mengontrol konten <head>, seperti judul halaman (komponen PageTitle) dan elemen kepala lainnya (komponen HeadContent). Untuk informasi lebih lanjut, lihat Kontrol konten kepala di aplikasi ASP.NET CoreBlazor.

    RenderMode mengkonfigurasi apakah komponen App.

    • Telah diprarender ke dalam halaman.
    • Apakah di-render sebagai HTML statis pada halaman atau jika itu mencakup informasi yang diperlukan untuk memulai aplikasi Blazor dari agen pengguna.

    Untuk informasi lebih lanjut tentang Component Tag Helper, termasuk penerusan parameter dan konfigurasi RenderMode, lihat Component Tag Helper di ASP.NET Core.

  4. Pada Program.cs titik akhir, tambahkan rute prioritas rendah untuk halaman _Host sebagai titik akhir terakhir.

    app.MapFallbackToPage("/_Host");

  5. Tambahkan komponen berjalur ke dalam proyek. Contoh berikut adalah komponen RoutableCounter yang didasarkan pada komponen Counter dalam template proyek Blazor.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<PageTitle>Routable Counter</PageTitle>

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  6. Jalankan proyek dan navigasikan ke komponen yang dapat diuraikan RoutableCounter di /routable-counter.

Untuk informasi lebih lanjut tentang ruang nama, lihat bagian Ruang nama Komponen.

Gunakan komponen yang dapat di-routing dalam aplikasi MVC

Bagian ini berkaitan dengan penambahan komponen yang dapat langsung dirutekan dari permintaan pengguna.

Untuk mendukung komponen Razor yang dapat diarahkan dalam aplikasi MVC:

  1. Ikuti panduan di bagian Konfigurasi.

  2. Tambahkan komponen App ke root proyek dengan konten berikut.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <p role="alert">Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

  3. Tambahkan tampilan _Host ke proyek dengan konten berikut.

    Views/Home/_Host.cshtml:

    @namespace {APP NAMESPACE}.Views.Shared
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@{
    Layout = "_Layout";
}

<component type="typeof(App)" render-mode="ServerPrerendered" />

    Komponen menggunakan file bersama _Layout.cshtml untuk tata letak mereka.

    Penting

    Penggunaan halaman tata letak (_Layout.cshtml) dengan Component Tag Helper untuk komponen HeadOutlet diperlukan untuk mengontrol konten <head>, seperti judul halaman (komponen PageTitle) dan elemen kepala lainnya (komponen HeadContent). Untuk informasi lebih lanjut, lihat Kontrol konten kepala di aplikasi ASP.NET CoreBlazor.

    RenderMode mengkonfigurasi apakah komponen App.

    • Telah diprarender ke dalam halaman.
    • Apakah di-render sebagai HTML statis pada halaman atau jika itu mencakup informasi yang diperlukan untuk memulai aplikasi Blazor dari agen pengguna.

    Untuk informasi lebih lanjut tentang Component Tag Helper, termasuk penerusan parameter dan konfigurasi RenderMode, lihat Component Tag Helper di ASP.NET Core.

  4. Tambahkan tindakan ke pengontrol Home.

    Controllers/HomeController.cs:

    public IActionResult Blazor()
{
   return View("_Host");
}

  5. Pada endpoint Program.cs, tambahkan rute prioritas rendah untuk aksi kontroler yang mengembalikan tampilan _Host.

    app.MapFallbackToController("Blazor", "Home");

  6. Buat folder Pages dalam aplikasi MVC dan tambahkan komponen-komponen yang dapat diarahkan. Contoh berikut adalah komponen RoutableCounter yang didasarkan pada komponen Counter dalam template proyek Blazor.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<PageTitle>Routable Counter</PageTitle>

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  7. Jalankan proyek dan navigasikan ke komponen yang dapat diuraikan RoutableCounter di /routable-counter.

Untuk informasi lebih lanjut tentang ruang nama, lihat bagian Ruang nama Komponen.

Render komponen dari halaman atau tampilan

Bagian ini berkaitan dengan menambahkan komponen ke halaman atau tampilan, di mana komponen tersebut tidak dapat langsung diarahkan dari permintaan pengguna.

Untuk merender sebuah komponen dari halaman atau tampilan, gunakan Component Tag Helper.

Render komponen interaktif yang memiliki status

Komponen interaktif berstatus dapat ditambahkan ke halaman atau tampilan Razor.

Ketika halaman atau tampilan dirender:

  • Komponen dirender sebelumnya bersamaan dengan halaman atau tampilan.
  • Status komponen awal yang digunakan untuk prarender telah hilang.
  • Keadaan komponen baru dibuat ketika sambungan SignalR diatur.

Halaman Razor berikut merender komponen Counter.

<h1>Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Untuk informasi lebih lanjut, lihat Component Tag Helper di ASP.NET Core.

Penting

Penggunaan halaman tata letak (_Layout.cshtml) dengan Component Tag Helper untuk komponen HeadOutlet diperlukan untuk mengontrol konten <head>, seperti judul halaman (komponen PageTitle) dan elemen kepala lainnya (komponen HeadContent). Untuk informasi lebih lanjut, lihat Kontrol konten kepala di aplikasi ASP.NET CoreBlazor.

Render komponen noninteraktif

Pada halaman Razor berikut, komponen Counter dirender secara statis dengan nilai awal yang ditentukan menggunakan sebuah formulir. Karena komponen dirender secara statis, komponen tersebut tidak interaktif.

<h1>Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Untuk informasi lebih lanjut, lihat Component Tag Helper di ASP.NET Core.

Penting

Penggunaan halaman tata letak (_Layout.cshtml) dengan Component Tag Helper untuk komponen HeadOutlet diperlukan untuk mengontrol konten <head>, seperti judul halaman (komponen PageTitle) dan elemen kepala lainnya (komponen HeadContent). Untuk informasi lebih lanjut, lihat Kontrol konten kepala di aplikasi ASP.NET CoreBlazor.

Namespace Komponen

Saat menggunakan folder kustom untuk menyimpan komponen proyek Razor, tambahkan namespace yang mewakili folder tersebut baik ke halaman/tampilan atau ke file _ViewImports.cshtml. Pada contoh berikut:

  • Komponen disimpan dalam folder Components proyek.
  • Placeholder {APP NAMESPACE} adalah namespace proyek. Components mewakili nama folder.
@using {APP NAMESPACE}.Components

File _ViewImports.cshtml terletak di folder Pages dari aplikasi Pages Razor atau folder Views dari aplikasi MVC.

Untuk informasi lebih lanjut, lihat komponen Razor ASP.NET Core.

Mempertahankan keadaan yang sudah diprender

Tanpa mempertahankan status yang telah dirender sebelumnya, status yang digunakan selama proses perenderan akan hilang dan harus dibuat ulang ketika aplikasi sepenuhnya dimuat. Jika ada status yang diatur secara asinkron, UI mungkin akan berkedip saat UI yang sudah dirender sebelumnya digantikan dengan placeholder sementara, dan kemudian dirender sepenuhnya lagi.

Untuk menyelesaikan masalah ini, Blazor mendukung pelestarian status dalam halaman yang sudah dirender sebelumnya dengan menggunakan Persist Component State Tag Helper. Tambahkan tag Tag Helper, <persist-component-state />, di dalam tag penutup </body>.

Pages/_Layout.cshtml:

<body>
    ...

    <persist-component-state />
</body>

Tentukan status apa yang harus dipertahankan dengan menggunakan layanan PersistentComponentState. PersistentComponentState.RegisterOnPersisting mendaftarkan callback untuk mempertahankan status komponen sebelum aplikasi dihentikan sementara. Status aplikasi diambil kembali ketika aplikasi dilanjutkan. Lakukan panggilan pada akhir dari kode inisialisasi untuk menghindari potensi race condition selama pemadaman aplikasi.

Dalam contoh berikut, komponen WeatherForecastPreserveState menyimpan keadaan prakiraan cuaca selama prarender dan kemudian mengambil keadaan tersebut untuk menginisialisasi komponen. Tag Helper Persist Component State mempertahankan status komponen setelah semua pemanggilan komponen.

Pages/WeatherForecastPreserveState.razor:

@page "/weather-forecast-preserve-state"
@implements IDisposable
@using BlazorSample.Shared
@inject IWeatherForecastService WeatherForecastService
@inject PersistentComponentState ApplicationState

<PageTitle>Weather Forecast</PageTitle>

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from the server.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[] forecasts = Array.Empty<WeatherForecast>();
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            nameof(forecasts), out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateTime.Now);
        }
        else
        {
            forecasts = restored!;
        }

        // Call at the end to avoid a potential race condition at app shutdown
        persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson(nameof(forecasts), forecasts);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

Dengan menginisialisasi komponen dengan kondisi yang sama seperti yang digunakan selama pra-rendering, setiap langkah inisialisasi yang mahal hanya dieksekusi satu kali. UI yang dirender juga sesuai dengan UI yang dirender sebelumnya, sehingga tidak terjadi kedipan di browser.

Keadaan yang telah dirender sebelumnya disimpan dan ditransfer ke klien, di mana keadaan ini digunakan untuk memulihkan keadaan komponen. ASP.NET Core Data Protection menjamin bahwa data ditransfer dengan aman dalam aplikasi Blazor Server.

Ukuran status pra-render dan batas ukuran pesan SignalR

Ukuran status prerendered yang besar mungkin melebihi batas ukuran pesan sirkuit Blazor dari SignalR, yang mengakibatkan hal berikut:

  • Sirkuit SignalR gagal diinisialisasi dengan kesalahan pada klien: Circuit host not initialized.
  • Antarmuka pengguna untuk penyambungan ulang di klien muncul ketika sirkuit gagal berfungsi. Pemulihan tidak mungkin.

Untuk menyelesaikan masalah, gunakan salah satu dari pendekatan berikut ini.

  • Kurangi jumlah data yang Anda masukkan ke dalam keadaan prapemrosesan.
  • Tingkatkan batas ukuran pesanSignalR. PERINGATAN: Meningkatkan batas dapat meningkatkan risiko terjadinya serangan Denial of Service (DoS).

Sumber daya tambahan Blazor Server

Prerendering dapat meningkatkan Search Engine Optimization (SEO) dengan merender konten untuk respons HTTP awal yang dapat digunakan mesin pencari untuk menghitung peringkat halaman.

Setelah mengonfigurasi proyek, gunakan panduan di bagian berikutnya sesuai dengan persyaratan proyek.

Konfigurasi

Sebuah aplikasi Pages atau MVC yang sudah ada dapat mengintegrasikan komponen Razor ke dalam halaman atau tampilan Razor.

  1. Dalam file tata letak proyek:

    • Tambahkan tag <base> berikut ke elemen <head> di Pages/Shared/_Layout.cshtml (Razor Halaman) atau Views/Shared/_Layout.cshtml (MVC):

      <base href="~/" />

      Nilai href ( jalur dasar aplikasi) dalam contoh sebelumnya mengasumsikan bahwa aplikasi berada di jalur URL akar (/). Jika aplikasi adalah sub-aplikasi, lihat ASP.NET Core Blazor jalur dasar aplikasi.

    • Tambahkan tag <script> untuk skrip blazor.server.js tepat sebelum bagian render Scripts.

      Pages/Shared/_Layout.cshtml (Razor Halaman) atau Views/Shared/_Layout.cshtml (MVC):

          ...
    <script src="_framework/blazor.server.js"></script>

    @await RenderSectionAsync("Scripts", required: false)
</body>

      Kerangka kerja menambahkan skrip blazor.server.js ke dalam aplikasi. Tidak perlu menambahkan file skrip blazor.server.js secara manual ke aplikasi.

  2. Tambahkan berkas impor ke folder root proyek dengan isi berikutnya. Ubah placeholder {APP NAMESPACE} menjadi namespace proyek.

    _Imports.razor:

    @using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.JSInterop
@using {APP NAMESPACE}

  3. Daftarkan layanan Blazor Server di Startup.ConfigureServices.

    Dalam Startup.cs:

    services.AddServerSideBlazor();

  4. Tambahkan titik akhir Hub Blazor ke titik akhir (app.UseEndpoints) dari Startup.Configure.

    Startup.cs:

    endpoints.MapBlazorHub();

  5. Integrasikan komponen ke dalam halaman atau tampilan apa pun. Sebagai contoh, tambahkan komponen Counter ke folder Shared proyek tersebut.

    Pages/Shared/Counter.razor (Razor Halaman) atau Views/Shared/Counter.razor (MVC):

    <h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

    Razor Halaman:

    Di halaman Index proyek dari aplikasi Pages Razor, tambahkan namespace komponen Counter dan tanamkan komponen tersebut ke dalam halaman. Ketika halaman Index dimuat, komponen Counter dirender sebelumnya di dalam halaman. Dalam contoh berikut, gantilah placeholder {APP NAMESPACE} dengan namespace proyek.

    Pages/Index.cshtml:

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div>
    <component type="typeof(Counter)" render-mode="ServerPrerendered" />
</div>

    Pada contoh sebelumnya, ganti placeholder {APP NAMESPACE} dengan namespace aplikasi.

    MVC:

    Dalam tampilan proyek aplikasi MVC, tambahkan namespace komponen dan sematkan komponen ke dalam tampilan. Ketika tampilan Index dimuat, komponen Counter dirender sebelumnya di halaman. Dalam contoh berikut, gantilah placeholder {APP NAMESPACE} dengan namespace proyek.

    Views/Home/Index.cshtml:

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

<div>
    <component type="typeof(Counter)" render-mode="ServerPrerendered" />
</div>

Untuk informasi lebih lanjut, lihat bagian Render components from a page or view.

Gunakan komponen yang dapat diarahkan dalam aplikasi Pages

Bagian ini berkaitan dengan penambahan komponen yang dapat langsung dirutekan dari permintaan pengguna.

Untuk mendukung komponen Razor yang dapat dirutekan di aplikasi Halaman Razor

  1. Ikuti panduan di bagian Konfigurasi.

  2. Tambahkan komponen App ke root proyek dengan konten berikut.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

    Catatan

    Dengan rilis .NET 5.0.1 dan untuk rilis 5.x tambahan, Router komponen menyertakan parameter PreferExactMatches diatur ke @true. Untuk informasi selengkapnya, lihat Migrasi dari ASP.NET Core 3.1 ke .NET 5.

  3. Tambahkan halaman _Host ke proyek dengan konten berikut.

    Pages/_Host.cshtml:

    @page "/blazor"
@{
    Layout = "_Layout";
}

<app>
    <component type="typeof(App)" render-mode="ServerPrerendered" />
</app>

    Komponen menggunakan file bersama _Layout.cshtml untuk tata letak mereka.

    RenderMode mengkonfigurasi apakah komponen App.

    • Telah diprarender ke dalam halaman.
    • Apakah di-render sebagai HTML statis pada halaman atau jika itu mencakup informasi yang diperlukan untuk memulai aplikasi Blazor dari agen pengguna.

    Untuk informasi lebih lanjut tentang Component Tag Helper, termasuk penerusan parameter dan konfigurasi RenderMode, lihat Component Tag Helper di ASP.NET Core.

  4. Di endpoint Startup.Configure dari Startup.cs, tambahkan rute prioritas rendah untuk halaman _Host sebagai endpoint terakhir.

    endpoints.MapFallbackToPage("/_Host");

    Contoh berikut menunjukkan baris yang ditambahkan dalam konfigurasi titik akhir aplikasi yang biasa.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToPage("/_Host");
});

  5. Tambahkan komponen berjalur ke dalam proyek.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  6. Jalankan proyek dan navigasikan ke komponen yang dapat diuraikan RoutableCounter di /routable-counter.

Untuk informasi lebih lanjut tentang ruang nama, lihat bagian Ruang nama Komponen.

Gunakan komponen yang dapat di-routing dalam aplikasi MVC

Bagian ini berkaitan dengan penambahan komponen yang dapat langsung dirutekan dari permintaan pengguna.

Untuk mendukung komponen Razor yang dapat diarahkan dalam aplikasi MVC:

  1. Ikuti panduan di bagian Konfigurasi.

  2. Tambahkan komponen App ke root proyek dengan konten berikut.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

    Catatan

    Dengan rilis .NET 5.0.1 dan untuk rilis 5.x tambahan, Router komponen menyertakan parameter PreferExactMatches diatur ke @true. Untuk informasi selengkapnya, lihat Migrasi dari ASP.NET Core 3.1 ke .NET 5.

  3. Tambahkan tampilan _Host ke proyek dengan konten berikut.

    Views/Home/_Host.cshtml:

    @{
    Layout = "_Layout";
}

<app>
    <component type="typeof(App)" render-mode="ServerPrerendered" />
</app>

    Komponen menggunakan file bersama _Layout.cshtml untuk tata letak mereka.

    RenderMode mengkonfigurasi apakah komponen App.

    • Telah diprarender ke dalam halaman.
    • Apakah di-render sebagai HTML statis pada halaman atau jika itu mencakup informasi yang diperlukan untuk memulai aplikasi Blazor dari agen pengguna.

    Untuk informasi lebih lanjut tentang Component Tag Helper, termasuk penerusan parameter dan konfigurasi RenderMode, lihat Component Tag Helper di ASP.NET Core.

  4. Tambahkan tindakan ke pengontrol Home.

    Controllers/HomeController.cs:

    public IActionResult Blazor()
{
   return View("_Host");
}

  5. Di endpoint Startup.Configure dari Startup.cs, tambahkan rute prioritas rendah untuk aksi pengendali yang mengembalikan tampilan _Host.

    endpoints.MapFallbackToController("Blazor", "Home");

    Contoh berikut menunjukkan baris yang ditambahkan dalam konfigurasi titik akhir aplikasi yang biasa.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToController("Blazor", "Home");
});

  6. Tambahkan komponen berjalur ke dalam proyek.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  7. Jalankan proyek dan navigasikan ke komponen yang dapat diuraikan RoutableCounter di /routable-counter.

Untuk informasi lebih lanjut tentang ruang nama, lihat bagian Ruang nama Komponen.

Render komponen dari halaman atau tampilan

Bagian ini berkaitan dengan menambahkan komponen ke halaman atau tampilan, di mana komponen tersebut tidak dapat langsung diarahkan dari permintaan pengguna.

Untuk merender sebuah komponen dari halaman atau tampilan, gunakan Component Tag Helper.

Render komponen interaktif yang memiliki status

Komponen interaktif berstatus dapat ditambahkan ke halaman atau tampilan Razor.

Ketika halaman atau tampilan dirender:

  • Komponen dirender sebelumnya bersamaan dengan halaman atau tampilan.
  • Status komponen awal yang digunakan untuk prarender telah hilang.
  • Keadaan komponen baru dibuat ketika sambungan SignalR diatur.

Halaman Razor berikut merender komponen Counter.

<h1>My Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Untuk informasi lebih lanjut, lihat Component Tag Helper di ASP.NET Core.

Render komponen noninteraktif

Pada halaman Razor berikut, komponen Counter dirender secara statis dengan nilai awal yang ditentukan menggunakan sebuah formulir. Karena komponen dirender secara statis, komponen tersebut tidak interaktif.

<h1>My Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Untuk informasi lebih lanjut, lihat Component Tag Helper di ASP.NET Core.

Namespace Komponen

Saat menggunakan folder kustom untuk menyimpan komponen proyek Razor, tambahkan namespace yang mewakili folder tersebut baik ke halaman/tampilan atau ke file _ViewImports.cshtml. Pada contoh berikut:

  • Komponen disimpan dalam folder Components proyek.
  • Placeholder {APP NAMESPACE} adalah namespace proyek. Components mewakili nama folder.
@using {APP NAMESPACE}.Components

File _ViewImports.cshtml terletak di folder Pages dari aplikasi Pages Razor atau folder Views dari aplikasi MVC.

Untuk informasi lebih lanjut, lihat komponen Razor ASP.NET Core.

Ukuran status pra-render dan batas ukuran pesan SignalR

Ukuran status prerendered yang besar mungkin melebihi batas ukuran pesan sirkuit Blazor dari SignalR, yang mengakibatkan hal berikut:

  • Sirkuit SignalR gagal diinisialisasi dengan kesalahan pada klien: Circuit host not initialized.
  • Antarmuka pengguna untuk penyambungan ulang di klien muncul ketika sirkuit gagal berfungsi. Pemulihan tidak mungkin.

Untuk menyelesaikan masalah, gunakan salah satu dari pendekatan berikut ini.

  • Kurangi jumlah data yang Anda masukkan ke dalam keadaan prapemrosesan.
  • Tingkatkan batas ukuran pesanSignalR. PERINGATAN: Meningkatkan batas dapat meningkatkan risiko terjadinya serangan Denial of Service (DoS).

Sumber daya tambahan Blazor Server

Komponen Razor dapat diintegrasikan ke dalam Halaman Razor atau aplikasi MVC. Ketika halaman atau tampilan dirender, komponen dapat diprerender pada saat yang sama.

Prerendering dapat meningkatkan Search Engine Optimization (SEO) dengan merender konten untuk respons HTTP awal yang dapat digunakan mesin pencari untuk menghitung peringkat halaman.

Setelah mengonfigurasi proyek, gunakan panduan di bagian berikutnya sesuai dengan persyaratan proyek.

Konfigurasi

Sebuah aplikasi Pages atau MVC yang sudah ada dapat mengintegrasikan komponen Razor ke dalam halaman atau tampilan Razor.

  1. Dalam file tata letak proyek:

    • Tambahkan tag <base> berikut ke elemen <head> di Pages/Shared/_Layout.cshtml (Razor Halaman) atau Views/Shared/_Layout.cshtml (MVC):

      + <base href="~/" />

      Nilai href ( jalur dasar aplikasi) dalam contoh sebelumnya mengasumsikan bahwa aplikasi berada di jalur URL akar (/). Jika aplikasi adalah sub-aplikasi, lihat ASP.NET Core Blazor jalur dasar aplikasi.

    • Tambahkan tag <script> untuk skrip blazor.server.js tepat sebelum bagian render Scripts.

      Pages/Shared/_Layout.cshtml (Razor Halaman) atau Views/Shared/_Layout.cshtml (MVC):

          ...
    <script src="_framework/blazor.server.js"></script>

    @await RenderSectionAsync("Scripts", required: false)
</body>

      Kerangka kerja menambahkan skrip blazor.server.js ke dalam aplikasi. Tidak perlu menambahkan file skrip blazor.server.js secara manual ke aplikasi.

  2. Tambahkan berkas impor ke folder root proyek dengan isi berikutnya. Ubah placeholder {APP NAMESPACE} menjadi namespace proyek.

    _Imports.razor:

    @using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.JSInterop
@using {APP NAMESPACE}

  3. Daftarkan layanan Blazor Server di Startup.ConfigureServices.

    Startup.cs:

    services.AddServerSideBlazor();

  4. Tambahkan titik akhir Hub Blazor ke titik akhir (app.UseEndpoints) dari Startup.Configure.

    Startup.cs:

    endpoints.MapBlazorHub();

  5. Integrasikan komponen ke dalam halaman atau tampilan apa pun. Sebagai contoh, tambahkan komponen Counter ke folder Shared proyek tersebut.

    Pages/Shared/Counter.razor (Razor Halaman) atau Views/Shared/Counter.razor (MVC):

    <h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

    Razor Halaman:

    Di halaman Index proyek dari aplikasi Pages Razor, tambahkan namespace komponen Counter dan tanamkan komponen tersebut ke dalam halaman. Ketika halaman Index dimuat, komponen Counter dirender sebelumnya di dalam halaman. Dalam contoh berikut, gantilah placeholder {APP NAMESPACE} dengan namespace proyek.

    Pages/Index.cshtml:

    @page
@using {APP NAMESPACE}.Pages.Shared
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div>
    <component type="typeof(Counter)" render-mode="ServerPrerendered" />
</div>

    Pada contoh sebelumnya, ganti placeholder {APP NAMESPACE} dengan namespace aplikasi.

    MVC:

    Dalam tampilan proyek aplikasi MVC, tambahkan namespace komponen dan sematkan komponen ke dalam tampilan. Ketika tampilan Index dimuat, komponen Counter dirender sebelumnya di halaman. Dalam contoh berikut, gantilah placeholder {APP NAMESPACE} dengan namespace proyek.

    Views/Home/Index.cshtml:

    @using {APP NAMESPACE}.Views.Shared
@{
    ViewData["Title"] = "Home Page";
}

<div>
    <component type="typeof(Counter)" render-mode="ServerPrerendered" />
</div>

Untuk informasi lebih lanjut, lihat bagian Render components from a page or view.

Gunakan komponen yang dapat diarahkan dalam aplikasi Pages

Bagian ini berkaitan dengan penambahan komponen yang dapat langsung dirutekan dari permintaan pengguna.

Untuk mendukung komponen Razor yang dapat dirutekan di aplikasi Halaman Razor

  1. Ikuti panduan di bagian Konfigurasi.

  2. Tambahkan komponen App ke root proyek dengan konten berikut.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

  3. Tambahkan halaman _Host ke proyek dengan konten berikut.

    Pages/_Host.cshtml:

    @page "/blazor"
@{
    Layout = "_Layout";
}

<app>
    <component type="typeof(App)" render-mode="ServerPrerendered" />
</app>

    Komponen menggunakan file bersama _Layout.cshtml untuk tata letak mereka.

    RenderMode mengkonfigurasi apakah komponen App.

    • Telah diprarender ke dalam halaman.
    • Apakah di-render sebagai HTML statis pada halaman atau jika itu mencakup informasi yang diperlukan untuk memulai aplikasi Blazor dari agen pengguna.

    Untuk informasi lebih lanjut tentang Component Tag Helper, termasuk penerusan parameter dan konfigurasi RenderMode, lihat Component Tag Helper di ASP.NET Core.

  4. Di endpoint Startup.Configure dari Startup.cs, tambahkan rute prioritas rendah untuk halaman _Host sebagai endpoint terakhir.

    endpoints.MapFallbackToPage("/_Host");

    Contoh berikut menunjukkan baris yang ditambahkan dalam konfigurasi titik akhir aplikasi yang biasa.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToPage("/_Host");
});

  5. Tambahkan komponen berjalur ke dalam proyek.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  6. Jalankan proyek dan navigasikan ke komponen yang dapat diuraikan RoutableCounter di /routable-counter.

Untuk informasi lebih lanjut tentang ruang nama, lihat bagian Ruang nama Komponen.

Gunakan komponen yang dapat di-routing dalam aplikasi MVC

Bagian ini berkaitan dengan penambahan komponen yang dapat langsung dirutekan dari permintaan pengguna.

Untuk mendukung komponen Razor yang dapat diarahkan dalam aplikasi MVC:

  1. Ikuti panduan di bagian Konfigurasi.

  2. Tambahkan komponen App ke root proyek dengan konten berikut.

    App.razor:

    @using Microsoft.AspNetCore.Components.Routing

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" />
    </Found>
    <NotFound>
        <h1>Page not found</h1>
        <p>Sorry, but there's nothing here!</p>
    </NotFound>
</Router>

  3. Tambahkan tampilan _Host ke proyek dengan konten berikut.

    Views/Home/_Host.cshtml:

    @{
    Layout = "_Layout";
}

<app>
    <component type="typeof(App)" render-mode="ServerPrerendered" />
</app>

    Komponen menggunakan file bersama _Layout.cshtml untuk tata letak mereka.

    RenderMode mengkonfigurasi apakah komponen App.

    • Telah diprarender ke dalam halaman.
    • Apakah di-render sebagai HTML statis pada halaman atau jika itu mencakup informasi yang diperlukan untuk memulai aplikasi Blazor dari agen pengguna.

    Untuk informasi lebih lanjut tentang Component Tag Helper, termasuk penerusan parameter dan konfigurasi RenderMode, lihat Component Tag Helper di ASP.NET Core.

  4. Tambahkan tindakan ke pengontrol Home.

    Controllers/HomeController.cs:

    public IActionResult Blazor()
{
   return View("_Host");
}

  5. Di endpoint Startup.Configure dari Startup.cs, tambahkan rute prioritas rendah untuk aksi pengendali yang mengembalikan tampilan _Host.

    endpoints.MapFallbackToController("Blazor", "Home");

    Contoh berikut menunjukkan baris yang ditambahkan dalam konfigurasi titik akhir aplikasi yang biasa.

    app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    endpoints.MapBlazorHub();
    endpoints.MapFallbackToController("Blazor", "Home");
});

  6. Tambahkan komponen berjalur ke dalam proyek.

    Pages/RoutableCounter.razor:

    @page "/routable-counter"

<h1>Routable Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

  7. Jalankan proyek dan navigasikan ke komponen yang dapat diuraikan RoutableCounter di /routable-counter.

Untuk informasi lebih lanjut tentang ruang nama, lihat bagian Ruang nama Komponen.

Render komponen dari halaman atau tampilan

Bagian ini berkaitan dengan menambahkan komponen ke halaman atau tampilan, di mana komponen tersebut tidak dapat langsung diarahkan dari permintaan pengguna.

Untuk merender sebuah komponen dari halaman atau tampilan, gunakan Component Tag Helper.

Render komponen interaktif yang memiliki status

Komponen interaktif berstatus dapat ditambahkan ke halaman atau tampilan Razor.

Ketika halaman atau tampilan dirender:

  • Komponen dirender sebelumnya bersamaan dengan halaman atau tampilan.
  • Status komponen awal yang digunakan untuk prarender telah hilang.
  • Keadaan komponen baru dibuat ketika sambungan SignalR diatur.

Halaman Razor berikut merender komponen Counter.

<h1>My Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Untuk informasi lebih lanjut, lihat Component Tag Helper di ASP.NET Core.

Render komponen noninteraktif

Pada halaman Razor berikut, komponen Counter dirender secara statis dengan nilai awal yang ditentukan menggunakan sebuah formulir. Karena komponen dirender secara statis, komponen tersebut tidak interaktif.

<h1>My Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Untuk informasi lebih lanjut, lihat Component Tag Helper di ASP.NET Core.

Namespace Komponen

Saat menggunakan folder kustom untuk menyimpan komponen proyek Razor, tambahkan namespace yang mewakili folder tersebut baik ke halaman/tampilan atau ke file _ViewImports.cshtml. Pada contoh berikut:

  • Komponen disimpan dalam folder Components proyek.
  • Placeholder {APP NAMESPACE} adalah namespace proyek. Components mewakili nama folder.
@using {APP NAMESPACE}.Components

File _ViewImports.cshtml terletak di folder Pages dari aplikasi Pages Razor atau folder Views dari aplikasi MVC.

Untuk informasi lebih lanjut, lihat komponen Razor ASP.NET Core.

Ukuran status pra-render dan batas ukuran pesan SignalR

Ukuran status prerendered yang besar mungkin melebihi batas ukuran pesan sirkuit Blazor dari SignalR, yang mengakibatkan hal berikut:

  • Sirkuit SignalR gagal diinisialisasi dengan kesalahan pada klien: Circuit host not initialized.
  • Antarmuka pengguna untuk penyambungan ulang di klien muncul ketika sirkuit gagal berfungsi. Pemulihan tidak mungkin.

Untuk menyelesaikan masalah, gunakan salah satu dari pendekatan berikut ini.

  • Kurangi jumlah data yang Anda masukkan ke dalam keadaan prapemrosesan.
  • Tingkatkan batas ukuran pesanSignalR. PERINGATAN: Meningkatkan batas dapat meningkatkan risiko terjadinya serangan Denial of Service (DoS).

Sumber daya tambahan Blazor Server