Merender dan mengintegrasikan komponen ASP.NET Core Razor

Artikel ini menjelaskan Razor skenario integrasi komponen untuk Blazor aplikasi, termasuk pra-penyajian Razor komponen di server.

Penting

Perubahan kerangka kerja di seluruh rilis ASP.NET Core menyebabkan serangkaian instruksi yang berbeda dalam artikel ini. Sebelum menggunakan panduan artikel ini, konfirmasikan bahwa pemilih versi dokumen di bagian atas artikel ini cocok dengan versi ASP.NET Core yang ingin Anda gunakan untuk aplikasi Anda.

Razorkomponen dapat diintegrasikan ke dalam Razor aplikasi Pages dan MVC dalam solusi yang dihostingBlazor WebAssembly. Ketika halaman atau tampilan dirender, komponen dapat dirender secara bersamaan.

Pra-penyajian dapat meningkatkan Pengoptimalan Mesin Pencari (SEO) dengan merender konten untuk respons HTTP awal yang dapat digunakan mesin pencari untuk menghitung peringkat halaman.

Konfigurasi solusi

Konfigurasi pra-penyajian

Untuk menyiapkan pra-penyajian untuk aplikasi yang dihosting Blazor WebAssembly :

1. Host aplikasi Blazor WebAssembly di aplikasi ASP.NET Core. Aplikasi mandiri Blazor WebAssembly dapat ditambahkan ke solusi ASP.NET Core, atau Anda dapat menggunakan aplikasi yang dihosting Blazor WebAssembly yang dibuat dari Blazor WebAssembly templat proyek dengan opsi yang dihosting:

   • Visual Studio: Dalam dialog Informasi tambahan, pilih kotak centang ASP.NET Core Hosted saat membuat Blazor WebAssembly aplikasi. Dalam contoh artikel ini, solusinya diberi nama BlazorHosted.
   • Shell perintah Visual Studio Code/.NET CLI: dotnet new blazorwasm -ho (gunakan -ho|--hosted opsi ). -o|--output {LOCATION} Gunakan opsi untuk membuat folder untuk solusi dan mengatur namespace proyek solusi. Dalam contoh artikel ini, solusinya diberi nama BlazorHosted (dotnet new blazorwasm -ho -o BlazorHosted).

   Untuk contoh dalam artikel ini, nama solusi yang dihosting (nama rakitan) adalah BlazorHosted. Namespace proyek klien adalah BlazorHosted.Client, dan namespace proyek server adalah BlazorHosted.Server.

2. wwwroot/index.html Hapus file dari Blazor WebAssemblyClient proyek.

3. Client Dalam proyek, hapus baris berikut di Program.cs:

   - builder.RootComponents.Add<App>("#app");
   - builder.RootComponents.Add<HeadOutlet>("head::after");
   

4. Tambahkan _Host.cshtml file ke Server folder proyek Pages . Anda dapat memperoleh file dari proyek yang dibuat dari Blazor Server templat menggunakan Visual Studio atau menggunakan .NET CLI dengan dotnet new blazorserver -o BlazorServer perintah dalam shell perintah ( -o BlazorServer opsi membuat folder untuk proyek). Setelah menempatkan file ke Server folder proyek Pages , buat perubahan berikut pada file.

   Buat perubahan berikut pada _Host.cshtml file:

   • Pages Perbarui namespace layanan di bagian atas file agar sesuai dengan namespace Server halaman aplikasi. Tempat {APP NAMESPACE} penampung dalam contoh berikut mewakili namespace halaman aplikasi donor yang menyediakan _Host.cshtml file:

     Menghapus:

     - @namespace {APP NAMESPACE}.Pages
     

     Tambahkan:

     @namespace BlazorHosted.Server.Pages
     

   • Tambahkan direktif @using untuk Client proyek di bagian atas file:

     @using BlazorHosted.Client
     

   • Perbarui tautan lembar gaya untuk menunjuk ke lembar gaya proyek WebAssembly. Dalam contoh berikut, namespace proyek klien adalah BlazorHosted.Client. Tempat {APP NAMESPACE} penampung mewakili namespace aplikasi donor yang menyediakan _Host.cshtml file. Perbarui Pembantu Tag Komponen (<component> tag) agar HeadOutlet komponen dapat merender komponen.

     Menghapus:

     - <link href="css/site.css" rel="stylesheet" />
     - <link href="{APP NAMESPACE}.styles.css" rel="stylesheet" />
     - <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
     

     Tambahkan:

     <link href="css/app.css" rel="stylesheet" />
     <link href="BlazorHosted.Client.styles.css" rel="stylesheet" />
     <component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />
     

     Catatan

     <link> Biarkan elemen yang meminta lembar gaya Bootstrap (css/bootstrap/bootstrap.min.css) di tempat.

   • Blazor Perbarui sumber skrip untuk menggunakan skrip sisi Blazor WebAssembly klien:

     Menghapus:

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

     Tambahkan:

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

   • render-mode Perbarui Pembantu Tag Komponen untuk merender komponen akar App dengan WebAssemblyPrerendered:

     Menghapus:

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

     Tambahkan:

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

     Penting

     Pra-penyajian tidak didukung untuk titik akhir autentikasi (/authentication/ segmen jalur). Untuk informasi lebih lanjut, lihat skenario keamanan tambahan Blazor WebAssembly ASP.NET Core.

5. Program.cs Dalam file Server proyek, ubah titik akhir fallback dari index.html file ke _Host.cshtml halaman:

   Menghapus:

   - app.MapFallbackToFile("index.html");
   

   Tambahkan:

   app.MapFallbackToPage("/_Host");
   

6. Client Jika proyek dan Server menggunakan satu atau beberapa layanan umum selama pra-penyajian, faktori pendaftaran layanan ke dalam metode yang dapat dipanggil dari kedua proyek. Untuk informasi selengkapnya, lihat Injeksi dependensi ASP.NET Core Blazor.

7. Jalankan Server proyek. Aplikasi yang dihosting Blazor WebAssembly telah di-prerender oleh Server proyek untuk klien.

Konfigurasi untuk menyematkan Razor komponen ke dalam halaman dan tampilan

Bagian dan contoh berikut untuk menyematkan Razor komponen dari ClientBlazor WebAssembly aplikasi ke dalam halaman dan tampilan aplikasi server memerlukan konfigurasi tambahan.

Proyek Server harus memiliki file dan folder berikut.

Razor Halaman:

• Pages/Shared/_Layout.cshtml
• Pages/Shared/_Layout.cshtml.css
• Pages/_ViewImports.cshtml
• Pages/_ViewStart.cshtml

MVC:

• Views/Shared/_Layout.cshtml
• Views/Shared/_Layout.cshtml.css
• Views/_ViewImports.cshtml
• Views/_ViewStart.cshtml

File sebelumnya dapat diperoleh dengan membuat aplikasi dari templat proyek ASP.NET Core menggunakan:

• Alat pembuatan proyek baru Visual Studio.
• Membuka shell perintah dan mengeksekusi dotnet new webapp -o {PROJECT NAME} (Razor Pages) atau dotnet new mvc -o {PROJECT NAME} (MVC). Opsi -o|--output dengan nilai untuk {PROJECT NAME} tempat penampung menyediakan nama untuk aplikasi dan membuat folder untuk aplikasi.

Perbarui namespace dalam file yang diimpor _ViewImports.cshtml agar sesuai dengan yang digunakan oleh proyek yang Server menerima file.

Pages/_ViewImports.cshtml (Razor Halaman):

@using BlazorHosted.Server
@namespace BlazorHosted.Server.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Views/_ViewImports.cshtml (MVC):

@using BlazorHosted.Server
@using BlazorHosted.Server.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Perbarui file tata letak yang diimpor, yaitu Pages/Shared/_Layout.cshtml untuk Razor Pages atau Views/Shared/_Layout.cshtml untuk MVC.

Pertama, hapus judul dan lembar gaya dari proyek donor, yang ada RPDonor.styles.css dalam contoh berikut. Tempat {PROJECT NAME} penampung mewakili nama aplikasi proyek donor.

- <title>@ViewData["Title"] - {PROJECT NAME}</title>
- <link rel="stylesheet" href="~/RPDonor.styles.css" asp-append-version="true" />

Sertakan Client gaya proyek dalam file tata letak. Dalam contoh berikut, Client namespace proyek adalah BlazorHosted.Client. Elemen <title> dapat diperbarui secara bersamaan.

Tempatkan baris berikut dalam <head> konten file tata letak:

<title>@ViewData["Title"] - BlazorHosted</title>
<link href="css/app.css" rel="stylesheet" />
<link rel="stylesheet" href="BlazorHosted.Client.styles.css" asp-append-version="true" />
<component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />

Tata letak yang diimpor berisi dua Home (Index halaman) dan Privacy tautan navigasi. Untuk membuat Home tautan menunjuk ke aplikasi yang dihosting Blazor WebAssembly , ubah hyperlink:

- <a class="navbar-brand" asp-area="" asp-page="/Index">{PROJECT NAME}</a>
+ <a class="navbar-brand" href="/">BlazorHosted</a>

- <a class="nav-link text-dark" asp-area="" asp-page="/Index">Home</a>
+ <a class="nav-link text-dark" href="/">Home</a>

Dalam file tata letak MVC:

- <a class="navbar-brand" asp-area="" asp-controller="Home" 
-     asp-action="Index">{PROJECT NAME}</a>
+ <a class="navbar-brand" href="/">BlazorHosted</a>

- <a class="nav-link text-dark" asp-area="" asp-controller="Home" 
-     asp-action="Index">Home</a>
+ <a class="nav-link text-dark" href="/">Home</a>

<footer> Perbarui nama aplikasi elemen. Contoh berikut menggunakan nama BlazorHostedaplikasi :

- &copy; {DATE} - {DONOR NAME} - <a asp-area="" asp-page="/Privacy">Privacy</a>
+ &copy; {DATE} - BlazorHosted - <a asp-area="" asp-page="/Privacy">Privacy</a>

Dalam contoh sebelumnya, {DATE} tempat penampung mewakili tanggal hak cipta dalam aplikasi yang dihasilkan dari Razor templat proyek Pages atau MVC.

Untuk membuat Privacy tautan mengarah ke privacy halaman (Razor Halaman), tambahkan privacy halaman ke Server proyek.

Pages/Privacy.cshtmlServer dalam proyek:

@page
@model PrivacyModel
@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p>Use this page to detail your site's privacy policy.</p>

Untuk tampilan berbasis privacy MVC, buat privacy tampilan dalam Server proyek.

View/Home/Privacy.cshtmlServer dalam proyek:

@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p>Use this page to detail your site's privacy policy.</p>

Home Di pengontrol aplikasi MVC, kembalikan tampilan.

Tambahkan kode berikut ke Controllers/HomeController.cs:

public IActionResult Privacy()
{
    return View();
}

Jika Anda mengimpor file dari aplikasi donor, pastikan untuk memperbarui namespace apa pun dalam file agar sesuai Server dengan proyek (misalnya, BlazorHosted.Server).

Impor aset statis ke Server proyek dari folder proyek wwwroot donor:

• wwwroot/css folder dan konten
• wwwroot/js folder dan konten
• wwwroot/lib folder dan konten

Jika proyek donor dibuat dari templat proyek ASP.NET Core dan file tidak dimodifikasi, Anda dapat menyalin seluruh wwwroot folder dari proyek donor ke dalam Server proyek dan menghapus favicon file ikon.

Peringatan

Hindari menempatkan aset statis ke dalam Client folder dan Server wwwroot . Jika file yang sama ada di kedua folder, pengecualian dilemparkan karena aset statis berbagi jalur akar web yang sama. Oleh karena itu, host aset statis di salah wwwroot satu folder, bukan keduanya.

Setelah mengadopsi konfigurasi sebelumnya, sematkan Razor komponen ke dalam halaman atau tampilan Server proyek. Gunakan panduan di bagian berikut dari artikel ini:

• Merender komponen dalam halaman atau tampilan dengan Pembantu Tag Komponen
• Merender komponen dalam halaman atau tampilan dengan pemilih CSS

Merender komponen dalam halaman atau tampilan dengan Pembantu Tag Komponen

Setelah mengonfigurasi solusi, termasuk konfigurasi tambahan, Pembantu Tag Komponen mendukung dua mode render untuk merender komponen dari Blazor WebAssembly aplikasi di halaman atau tampilan:

• WebAssembly
• WebAssemblyPrerendered

Dalam contoh Halaman berikut Razor , Counter komponen dirender di halaman. Untuk membuat komponen interaktif, Blazor WebAssembly skrip disertakan di bagian render halaman. Untuk menghindari penggunaan namespace lengkap untuk Counter komponen dengan Component Tag Helper ({ASSEMBLY NAME}.Pages.Counter), tambahkan @using direktif untuk namespace proyek Pages klien. Dalam contoh berikut, Client namespace proyek adalah BlazorHosted.Client.

Dalam proyek Server, Pages/RazorPagesCounter1.cshtml:

@page
@using BlazorHosted.Client.Pages

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

@section Scripts {
    <script src="_framework/blazor.webassembly.js"></script>
}

Jalankan Server proyek. Navigasi ke Razor halaman di /razorpagescounter1. Komponen yang telah dirender Counter disematkan di halaman.

RenderMode mengonfigurasi apakah komponen:

• Di-prerender ke dalam halaman.
• Dirender sebagai HTML statis di halaman atau jika menyertakan informasi yang Blazor diperlukan untuk bootstrap aplikasi dari agen pengguna.

Untuk informasi selengkapnya tentang Pembantu Tag Komponen, termasuk meneruskan parameter dan RenderMode konfigurasi, lihat Pembantu Tag Komponen di ASP.NET Core.

Pekerjaan tambahan mungkin diperlukan tergantung pada sumber daya statis yang digunakan komponen dan bagaimana halaman tata letak diatur dalam aplikasi. Biasanya, skrip ditambahkan ke halaman atau bagian render tampilan Scripts dan lembar gaya ditambahkan ke konten elemen tata letak <head> .

Mengatur konten turunan melalui fragmen render

Pembantu Tag Komponen tidak mendukung penerimaanRenderFragment delegasi untuk konten anak (misalnya, param-ChildContent="..."). Sebaiknya buat Razor komponen (.razor) yang mereferensikan komponen yang ingin Anda render dengan konten anak yang ingin Anda lewati lalu panggil Razor komponen dari halaman atau tampilan.

Pastikan bahwa komponen yang telah dirender tingkat atas tidak dipangkas saat diterbitkan

Jika Pembantu Tag Komponen secara langsung mereferensikan komponen dari pustaka yang tunduk pada pemangkasan penerbitan, komponen mungkin dipangkas selama penerbitan karena tidak ada referensi dari kode aplikasi sisi klien. Akibatnya, komponen tidak dirender sebelumnya, meninggalkan tempat kosong dalam output. Jika ini terjadi, instruksikan pemangkas untuk mempertahankan komponen pustaka dengan menambahkan DynamicDependency atribut ke kelas apa pun di aplikasi sisi klien. Untuk mempertahankan komponen yang disebut SomeLibraryComponentToBePreserved, tambahkan yang berikut ini ke komponen apa pun:

@using System.Diagnostics.CodeAnalysis
@attribute [DynamicDependency(DynamicallyAccessedMemberTypes.All, 
    typeof(SomeLibraryComponentToBePreserved))]

Pendekatan sebelumnya biasanya tidak diperlukan karena aplikasi biasanya merender komponennya (yang tidak dipangkas), yang pada gilirannya mereferensikan komponen dari pustaka (menyebabkannya juga tidak dipangkas). Hanya gunakan DynamicDependency secara eksplisit untuk merender komponen pustaka secara langsung ketika pustaka tunduk pada pemangkasan.

Merender komponen dalam halaman atau tampilan dengan pemilih CSS

Setelah mengonfigurasi solusi, termasuk konfigurasi tambahan, tambahkan komponen root ke Client proyek solusi yang dihosting Blazor WebAssembly dalam Program.cs file. Dalam contoh berikut, Counter komponen dinyatakan sebagai komponen akar dengan pemilih CSS yang memilih elemen dengan id yang cocok counter-component. Dalam contoh berikut, Client namespace proyek adalah BlazorHosted.Client.

Dalam Program.cs file Client proyek, tambahkan namespace layanan untuk komponen proyek Razor ke bagian atas file:

using BlazorHosted.Client.Pages;

builder Setelah ditetapkan dalam Program.cs, tambahkan Counter komponen sebagai komponen akar:

builder.RootComponents.Add<Counter>("#counter-component");

Dalam contoh Halaman berikut Razor , Counter komponen dirender di halaman. Untuk membuat komponen interaktif, Blazor WebAssembly skrip disertakan di bagian render halaman.

Dalam proyek Server, Pages/RazorPagesCounter2.cshtml:

@page

<div id="counter-component">Loading...</div>

@section Scripts {
    <script src="_framework/blazor.webassembly.js"></script>
}

Jalankan Server proyek. Navigasi ke Razor halaman di /razorpagescounter2. Komponen yang telah dirender Counter disematkan di halaman.

Pekerjaan tambahan mungkin diperlukan tergantung pada sumber daya statis yang digunakan komponen dan bagaimana halaman tata letak diatur dalam aplikasi. Biasanya, skrip ditambahkan ke halaman atau bagian render tampilan Scripts dan lembar gaya ditambahkan ke konten elemen tata letak <head> .

Catatan

Contoh sebelumnya melemparkan JSException jika Blazor WebAssembly aplikasi dirender dan diintegrasikan ke dalam Razor Halaman atau aplikasi MVC secara bersamaan dengan penggunaan pemilih CSS. Menavigasi ke salah Client satu komponen proyek Razor atau menavigasi ke halaman atau tampilan Server dengan komponen yang disematkan melempar satu atau beberapa JSException.

Ini adalah perilaku normal karena melakukan prarender dan mengintegrasikan Blazor WebAssembly aplikasi dengan komponen yang dapat dirutekan Razor tidak kompatibel dengan penggunaan pemilih CSS.

Jika Anda telah bekerja dengan contoh di bagian sebelumnya dan hanya ingin melihat pekerjaan pemilih CSS di aplikasi sampel Anda, komentari spesifikasi App komponen Client akar file proyek Program.cs :

- builder.RootComponents.Add<App>("#app");
+ //builder.RootComponents.Add<App>("#app");

Navigasikan ke halaman atau lihat dengan komponen yang disematkan Razor yang menggunakan pemilih CSS (misalnya, /razorpagescounter2 dari contoh sebelumnya). Halaman atau tampilan dimuat dengan komponen yang disematkan, dan komponen yang disematkan berfungsi seperti yang diharapkan.

Razor komponen dapat diintegrasikan ke dalam Razor aplikasi Pages dan MVC. Ketika halaman atau tampilan dirender, komponen dapat dirender secara bersamaan.

Pra-penyajian dapat meningkatkan Pengoptimalan Mesin Pencari (SEO) dengan merender konten untuk respons HTTP awal yang dapat digunakan mesin pencari untuk menghitung peringkat halaman.

Setelah mengonfigurasi proyek, gunakan panduan di bagian berikut tergantung pada persyaratan proyek:

• Untuk komponen yang dapat dirutekan secara langsung dari permintaan pengguna. Ikuti panduan ini ketika pengunjung harus dapat membuat permintaan HTTP di browser mereka untuk komponen dengan arahan @page .
  • Menggunakan komponen yang dapat dirutekan di Razor aplikasi Pages
  • Menggunakan komponen yang dapat dirutekan dalam aplikasi MVC
• Untuk komponen yang tidak dapat dirutekan secara langsung dari permintaan pengguna, lihat bagian Render komponen dari halaman atau tampilan . Ikuti panduan ini saat aplikasi menyematkan komponen ke halaman dan tampilan yang ada dengan Pembantu Tag Komponen.

Konfigurasi

Gunakan panduan berikut untuk mengintegrasikan Razor komponen ke dalam halaman dan tampilan Halaman atau aplikasi MVC yang ada Razor .

1. Tambahkan file impor ke folder akar proyek dengan konten berikut. {APP NAMESPACE} Ubah tempat penampung ke 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 file tata letak proyek (Pages/Shared/_Layout.cshtml di Razor aplikasi Pages atau Views/Shared/_Layout.cshtml di aplikasi MVC):

   • Tambahkan tag dan HeadOutlet Komponen Pembantu Tag berikut <base> ke <head> elemen :

     <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, ikuti panduan di bagian Jalur dasar aplikasi dari artikel Host dan sebarkan ASP.NET CoreBlazor.

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

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

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

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

   Catatan

   Biasanya, tata letak dimuat melalui _ViewStart.cshtml file.

3. Daftarkan Blazor Server layanan tempat Program.cs layanan terdaftar:

   builder.Services.AddServerSideBlazor();
   

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

   app.MapBlazorHub();
   

5. Integrasikan komponen ke halaman atau tampilan apa pun. Misalnya, tambahkan Counter komponen ke folder proyek Shared .

   Pages/Shared/Counter.razor (Razor Pages) 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 Razor proyek Index aplikasi Pages, tambahkan Counter namespace layanan komponen dan sematkan komponen ke dalam halaman. Ketika halaman dimuat Index , Counter komponen telah dirender di halaman. Dalam contoh berikut, ganti {APP NAMESPACE} tempat penampung 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 Index aplikasi MVC, tambahkan Counter namespace layanan komponen dan sematkan komponen ke dalam tampilan. Saat tampilan dimuat Index , Counter komponen telah dirender di halaman. Dalam contoh berikut, ganti {APP NAMESPACE} tempat penampung 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 selengkapnya, lihat bagian Render komponen dari halaman atau tampilan .

Menggunakan komponen yang dapat dirutekan di Razor aplikasi Pages

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

Untuk mendukung komponen yang dapat dirutekan Razor di Razor aplikasi Pages:

1. Ikuti panduan di bagian Konfigurasi .

2. App Tambahkan komponen ke akar 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. _Host Tambahkan halaman ke proyek dengan konten berikut. {APP NAMESPACE} Ganti tempat penampung dengan namespace aplikasi.

   Pages/_Host.cshtml:

   @page
   @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
   
   <component type="typeof(App)" render-mode="ServerPrerendered" />
   

   Catatan

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

   RenderMode mengonfigurasi apakah App komponen:

   • Di-prerender ke dalam halaman.
   • Dirender sebagai HTML statis di halaman atau jika menyertakan informasi yang Blazor diperlukan untuk bootstrap aplikasi dari agen pengguna.

   Untuk informasi selengkapnya tentang Pembantu Tag Komponen, termasuk meneruskan parameter dan RenderMode konfigurasi, lihat Pembantu Tag Komponen di ASP.NET Core.

4. Program.cs Di titik akhir, tambahkan rute berprioritas rendah untuk _Host halaman sebagai titik akhir terakhir:

   app.MapFallbackToPage("/_Host");
   

5. Tambahkan komponen yang dapat dirutekan ke proyek. Contoh berikut adalah RoutableCounter komponen berdasarkan Counter komponen dalam Blazor templat proyek.

   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 dirutekan RoutableCounter di /routable-counter.

Untuk informasi selengkapnya tentang namespace layanan, lihat bagian Namespace komponen .

Menggunakan komponen yang dapat dirutekan dalam aplikasi MVC

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

Untuk mendukung komponen yang dapat dirutekan Razor di aplikasi MVC:

1. Ikuti panduan di bagian Konfigurasi .

2. App Tambahkan komponen ke akar 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. _Host Tambahkan tampilan ke proyek dengan konten berikut. {APP NAMESPACE} Ganti tempat penampung dengan namespace aplikasi.

   Views/Home/_Host.cshtml:

   @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
   
   <component type="typeof(App)" render-mode="ServerPrerendered" />
   

   Catatan

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

   RenderMode mengonfigurasi apakah App komponen:

   • Di-prerender ke dalam halaman.
   • Dirender sebagai HTML statis di halaman atau jika menyertakan informasi yang Blazor diperlukan untuk bootstrap aplikasi dari agen pengguna.

   Untuk informasi selengkapnya tentang Pembantu Tag Komponen, termasuk meneruskan parameter dan RenderMode konfigurasi, lihat Pembantu Tag Komponen di ASP.NET Core.

4. Tambahkan tindakan ke Home pengontrol.

   Controllers/HomeController.cs:

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

5. Program.cs Di titik akhir, tambahkan rute berprioritas rendah untuk tindakan pengontrol yang mengembalikan _Host tampilan:

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

6. Buat Pages folder di aplikasi MVC dan tambahkan komponen yang dapat dirutekan. Contoh berikut adalah RoutableCounter komponen berdasarkan Counter komponen dalam Blazor templat proyek.

   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 dirutekan RoutableCounter di /routable-counter.

Untuk informasi selengkapnya tentang namespace layanan, lihat bagian Namespace komponen .

Merender komponen dari halaman atau tampilan

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

Untuk merender komponen dari halaman atau tampilan, gunakan Pembantu Tag Komponen.

Merender komponen interaktif stateful

Komponen interaktif stateful dapat ditambahkan ke Razor halaman atau tampilan.

Saat halaman atau tampilan dirender:

• Komponen telah dirender dengan halaman atau tampilan.
• Status komponen awal yang digunakan untuk pra-penyajian hilang.
• Status komponen baru dibuat ketika SignalR koneksi dibuat.

Halaman berikut Razor merender Counter komponen:

<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 selengkapnya, lihat Pembantu Tag Komponen di ASP.NET Core.

Merender komponen noninteraktif

Di halaman berikut Razor , Counter komponen dirender secara statis dengan nilai awal yang ditentukan menggunakan formulir. Karena komponen dirender secara statis, komponen 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 selengkapnya, lihat Pembantu Tag Komponen di ASP.NET Core.

Namespace komponen

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

• Komponen disimpan di Components folder proyek.
• Tempat {APP NAMESPACE} penampung adalah namespace proyek. Components mewakili nama folder.

@using {APP NAMESPACE}.Components

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

Untuk informasi selengkapnya, lihat komponen ASP.NET CoreRazor.

Mempertahankan status yang telah dirender sebelumnya

Tanpa mempertahankan status yang telah dirender sebelumnya, status yang digunakan selama pra-penyajian hilang dan harus dibuat ulang saat aplikasi dimuat sepenuhnya. Jika ada status yang disiapkan secara asinkron, UI dapat berkedot karena UI yang telah dirender diganti dengan tempat penampung sementara dan kemudian sepenuhnya dirender lagi.

Untuk mempertahankan status komponen yang telah dirender sebelumnya, gunakan Pembantu Tag Status Komponen Persisten (sumber referensi). Tambahkan tag Pembantu _Host Tag, <persist-component-state />, di dalam tag penutup </body> halaman di aplikasi yang merender komponen.

Catatan

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Di Pages/_Host.cshtml aplikasi Blazor yang dirender webAssembly (WebAssemblyPrerendered) di aplikasi yang dihosting Blazor WebAssembly atau ServerPrerendered di Blazor Server aplikasi:

<body>
    ...

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

Tentukan status apa yang akan bertahan menggunakan PersistentComponentState layanan. PersistentComponentState.RegisterOnPersisting mendaftarkan panggilan balik untuk mempertahankan status komponen sebelum aplikasi dijeda. Status diambil ketika aplikasi dilanjutkan.

Dalam contoh berikut:

• Tempat {TYPE} penampung mewakili jenis data yang akan dipertahankan (misalnya, WeatherForecast[]).
• Tempat {TOKEN} penampung adalah string pengidentifikasi status (misalnya, fetchdata).

@implements IDisposable
@inject PersistentComponentState ApplicationState

...

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

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistData);

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

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

        return Task.CompletedTask;
    }

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

Contoh berikut adalah versi komponen yang diperbarui FetchData dalam aplikasi yang dihosting Blazor WebAssembly berdasarkan Blazor templat proyek. Komponen mempertahankan WeatherForecastPreserveState status prakiraan cuaca selama pra-penyajian lalu mengambil status untuk menginisialisasi komponen. Pembantu Tag Status Komponen Persist 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()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistForecasts);

        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            "fetchdata", out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateOnly.FromDateTime(DateTime.Now));
        }
        else
        {
            forecasts = restored!;
        }
    }

    private Task PersistForecasts()
    {
        ApplicationState.PersistAsJson("fetchdata", forecasts);

        return Task.CompletedTask;
    }

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

Dengan menginisialisasi komponen dengan status yang sama yang digunakan selama prarender, langkah-langkah inisialisasi mahal hanya dijalankan sekali. UI yang dirender juga cocok dengan UI yang telah dirender sebelumnya, sehingga tidak ada kedipan yang terjadi di browser.

Status pra-penyajian yang dipertahankan ditransfer ke klien, di mana ia digunakan untuk memulihkan status komponen. ASP.NET Core Data Protection memastikan bahwa data ditransfer dengan aman di Blazor Server aplikasi. Untuk pra-penyajian di aplikasi yang dihosting Blazor WebAssembly , data diekspos ke browser dan tidak boleh berisi informasi privat yang sensitif.

Sumber daya tambahan Blazor WebAssembly

• Manajemen status: Menangani pra-penyajian
• Dukungan pra-penyajian dengan pemuatan malas rakitan
• Razor subjek siklus hidup komponen yang berkaitan dengan pra-penyajian
  • Inisialisasi komponen (OnInitialized{Async})
  • Setelah render komponen (OnAfterRender{Async})
  • Koneksi ulang stateful setelah pra-penyajian: Meskipun konten di bagian berfokus pada Blazor Server dan koneksi ulang yang statefulSignalR, skenario untuk prarendering di aplikasi yang Blazor WebAssembly dihosting (WebAssemblyPrerendered) melibatkan kondisi dan pendekatan serupa untuk mencegah eksekusi kode pengembang dua kali. Untuk mempertahankan status selama eksekusi kode inisialisasi saat melakukan prarender, lihat bagian Mempertahankan status yang telah dirender sebelumnya di artikel ini.
  • Pra-penyajian dengan interop JavaScript
• Subjek autentikasi dan otorisasi yang berkaitan dengan pra-penyajian
  • Aspek umum
  • Prarendering dengan autentikasi di aplikasi yang dihosting Blazor WebAssembly
• Host dan sebarkan: Blazor WebAssembly
• Menangani kesalahan: Pra-penyajian
• OnNavigateAsync dijalankan dua kali saat pra-penyajian: Menangani peristiwa navigasi asinkron dengan OnNavigateAsync

Ukuran status dan SignalR batas ukuran pesan yang telah dirender sebelumnya

Ukuran status besar yang telah dirender mungkin melebihi SignalR batas ukuran pesan sirkuit, yang menghasilkan hal berikut:

• SignalR Sirkuit gagal diinisialisasi dengan kesalahan pada klien:Circuit host not initialized.
• Antarmuka pengguna koneksi ulang pada klien muncul ketika sirkuit gagal. Pemulihan tidak dimungkinkan.

Untuk mengatasi masalah tersebut, gunakan salah satu pendekatan berikut:

• Kurangi jumlah data yang Anda masukkan ke dalam status yang telah dirender sebelumnya.
• Tingkatkan SignalR batas ukuran pesan. PERINGATAN: Meningkatkan batas dapat meningkatkan risiko serangan Denial of Service (DoS).

Sumber daya tambahan Blazor Server

• Manajemen status: Menangani pra-penyajian
• Razor subjek siklus hidup komponen yang berkaitan dengan pra-penyajian
  • Inisialisasi komponen (OnInitialized{Async})
  • Setelah render komponen (OnAfterRender{Async})
  • Koneksi ulang stateful setelah pra-penyajian
  • Pra-penyajian dengan interop JavaScript
• Autentikasi dan otorisasi: Aspek umum
• Menangani Kesalahan: Pra-penyajian
• Host dan sebarkan: Blazor Server
• Mitigasi ancaman: Pembuatan skrip lintas situs (XSS)
• OnNavigateAsync dijalankan dua kali saat pra-penyajian: Menangani peristiwa navigasi asinkron dengan OnNavigateAsync