Rute ASP.NET Core Blazor

Artikel ini menjelaskan Blazor rute permintaan aplikasi dengan panduan untuk perutean statis versus perutean interaktif, integrasi ASP.NET Core perutean titik akhir, peristiwa navigasi, dan templat rute serta batasan untuk komponen Razor.

Routing di Blazor dicapai dengan menyediakan template rute untuk setiap komponen yang dapat diakses dengan direktif @page dalam aplikasi. Saat file Razor dengan arahan @page dikompilasi, kelas yang dihasilkan diberi RouteAttribute yang menentukan template rute. Pada saat runtime, router mencari kelas-kelas komponen dengan RouteAttribute dan merender komponen yang memiliki templat jalur yang sesuai dengan URL yang diminta.

Komponen HelloWorld berikut menggunakan templat rute /hello-world, dan halaman web yang dirender untuk komponen dapat diakses melalui URL relatif /hello-world.

HelloWorld.razor:

@page "/hello-world"

<h1>Hello World!</h1>

Tidak peduli apakah Anda menambahkan komponen ke navigasi UI aplikasi sebagai tautan atau tidak, komponen sebelumnya dimuat di /hello-world browser.

Perutean statis versus interaktif

Bagian ini berlaku untuk Blazor Web Apps.

Jika prerendering diaktifkan, Blazor router (Router komponen, <Router> dalam Routes.razor) melakukan perutean statis ke komponen selama penyajian sisi server statis (SSR). Jenis perutean ini disebut perutean statis.

Ketika mode render interaktif ditetapkan pada komponen Routes, router Blazor menjadi interaktif setelah SSR statis dengan perutean statis di server. Jenis perutean ini disebut perutean interaktif.

Router statis menggunakan perutean titik akhir dan jalur permintaan HTTP untuk menentukan komponen mana yang akan dirender. Ketika router menjadi interaktif, router menggunakan URL dokumen (URL di bilah alamat browser) untuk menentukan komponen mana yang akan dirender. Ini berarti bahwa router interaktif dapat secara dinamis mengubah komponen mana yang dirender jika URL dokumen berubah secara dinamis ke URL internal lain yang valid, dan dapat melakukannya tanpa melakukan permintaan HTTP untuk mengambil konten halaman baru.

Routing interaktif juga mencegah prarendering karena konten halaman baru tidak diminta dari server dengan permintaan halaman yang biasa. Untuk informasi selengkapnya, lihat ASP.NET Blazor Persistensi status core yang telah dirender sebelumnya.

integrasi perutean titik akhir ASP.NET Core

Bagian ini berlaku untuk Blazor Web App yang beroperasi dengan sirkuit.

Blazor Web App diintegrasikan ke dalam Perutean Titik Akhir ASP.NET Core. Aplikasi ASP.NET Core dikonfigurasi dengan titik akhir untuk komponen yang dapat dirutekan dan komponen akar yang akan dirender untuk titik akhir tersebut MapRazorComponents dengan Program dalam file. Komponen akar default (komponen pertama yang dimuat) adalah App komponen (App.razor):

app.MapRazorComponents<App>();

Pola Rute

Router komponen memungkinkan perutean ke komponen Razor dan terletak di komponen aplikasi Routes (Components/Routes.razor).

Razor Ketika komponen (.razor) dengan direktif @page dikompilasi, kelas komponen yang dihasilkan diberi spesifikasi RouteAttribute yang menentukan templat rute komponen.

Ketika aplikasi dimulai, rakitan yang telah ditentukan sebagai AppAssembly pada Router dipindai untuk mengumpulkan informasi rute bagi komponen aplikasi yang memiliki RouteAttribute.

Pada saat runtime, komponen RouteView:

• Menerima RouteData dari Router beserta parameter rute apa pun.
• Merender komponen yang ditentukan dengan tata letaknya, termasuk tata letak berlapis lebih lanjut.

Secara opsional tentukan DefaultLayout parameter dengan kelas tata letak untuk komponen yang tidak menentukan tata letak dengan direktif@layout. Kerangka kerja templat proyekBlazor menentukan MainLayout komponen (MainLayout.razor) sebagai tata letak default aplikasi. Untuk informasi selengkapnya tentang tata letak, lihat Blazor ASP.NET Core.

Komponen mendukung beberapa templat rute menggunakan beberapa @page arahan. Contoh komponen berikut dimuat pada permintaan untuk /blazor-route dan /different-blazor-route.

BlazorRoute.razor:

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Routing Example</h1>

<p>
    This page is reached at either <code>/blazor-route</code> or 
    <code>/different-blazor-route</code>.
</p>

Penting

Agar URL diresolusikan dengan benar, aplikasi harus menyertakan tag <base> (lokasi <head> konten) dengan jalur dasar aplikasi yang ditentukan dalam atribut href. Untuk informasi selengkapnya, lihat jalur dasar aplikasi ASP.NET CoreBlazor.

Sebagai alternatif untuk menentukan templat rute sebagai string literal dengan @page direktif, templat rute berbasis konstan dapat ditentukan dengan direktif@attribute.

Dalam contoh berikut, arahan @page dalam komponen diganti dengan @attribute direktif dan templat rute berbasis konstanta di Constants.CounterRoute, yang diatur di tempat lain di aplikasi ke "/counter":

- @page "/counter"
+ @attribute [Route(Constants.CounterRoute)]

Memusatkan perhatian pada elemen navigasi

Komponen FocusOnNavigate mengatur fokus UI ke elemen berdasarkan pemilih CSS setelah menavigasi dari satu halaman ke halaman lainnya.

<FocusOnNavigate RouteData="routeData" Selector="h1" />

Router Saat komponen menavigasi ke halaman baru, FocusOnNavigate komponen mengatur fokus ke header tingkat atas halaman (<h1>). Ini adalah strategi umum untuk memastikan bahwa navigasi halaman diumumkan saat menggunakan pembaca layar.

Sediakan konten kustom saat konten tidak ditemukan

Untuk permintaan saat konten tidak ditemukan, komponen Razor dapat ditetapkan ke parameter NotFoundPage dari komponen Router. Parameter berfungsi bersama dengan NavigationManager.NotFound, metode yang dipanggil dalam kode pengembang yang memicu respons Tidak Ditemukan. NavigationManager.NotFound dijelaskan dalam artikel berikutnya, navigasi ASP.NET CoreBlazor.

Templat proyek Blazor mencakup halaman NotFound.razor. Halaman ini secara otomatis dirender setiap kali NavigationManager.NotFound dipanggil, memungkinkan untuk menangani rute yang hilang dengan pengalaman pengguna yang konsisten.

NotFound.razor:

@page "/not-found"
@layout MainLayout

<h3>Not Found</h3>
<p>Sorry, the content you are looking for does not exist.</p>

Komponen NotFound ditetapkan ke parameter router NotFoundPage . NotFoundPage mendukung perutean yang dapat digunakan pada Middleware Halaman Kode Status Eksekusi Ulang, termasuk Blazor non-middleware.

Dalam contoh berikut, komponen sebelumnya NotFound ada di folder aplikasi Pages dan diteruskan ke NotFoundPage parameter :

<Router AppAssembly="@typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
</Router>

Untuk informasi selengkapnya, lihat artikel berikutnya tentang navigasi ASP.NET CoreBlazor.

Mengarahkan ke komponen dari beberapa rakitan

Bagian ini berlaku untuk Blazor Web Apps.

Gunakan parameter komponen Router dan pembangun konvensi titik akhir AdditionalAssemblies untuk menemukan komponen yang dapat dirutekan di dalam rakitan tambahan. Sub bagian berikut menjelaskan kapan dan bagaimana menggunakan setiap API.

Pengaturan Rute Statis

Untuk menemukan komponen yang dapat diarahkan dari rakitan tambahan untuk penyajian sisi server statis (SSR statis), walaupun router nantinya menjadi interaktif untuk penyajian, rakitan harus dinyatakan dalam kerangka kerja Blazor. Panggil metode AddAdditionalAssemblies dengan rakitan tambahan yang digabungkan ke MapRazorComponents dalam file Program proyek server.

Contoh berikut mencakup komponen yang bisa diroute dalam perakitan proyek BlazorSample.Client menggunakan file _Imports.razor proyek:

app.MapRazorComponents<App>()
    .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);

Catatan

Panduan sebelumnya juga berlaku dalam skenario perpustakaan kelas komponen. Panduan penting tambahan untuk pustaka kelas dan SSR statis ditemukan di pustaka kelas inti Razor (RCL) ASP.NET dengan penyajian sisi server statis (SSR statis).

Perutean interaktif

Mode pembuat-gambar interaktif dapat ditetapkan ke komponen Routes (Routes.razor) yang membuat router Blazor menjadi interaktif setelah SSR statis dan routing statis di server. Misalnya, <Routes @rendermode="InteractiveServer" /> mengatur penyajian sisi server interaktif (SSR interaktif) pada komponen Routes. Komponen Router mewarisi penyajian sisi server interaktif (SSRI) dari Routes. Router menjadi lebih interaktif setelah melakukan perutean statis pada server.

Navigasi internal untuk routing interaktif tidak melibatkan permintaan konten halaman baru dari server. Oleh karena itu, pra-rendering tidak terjadi untuk permintaan halaman internal. Untuk informasi selengkapnya, lihat ASP.NET Blazor Persistensi status core yang telah dirender sebelumnya.

Jika komponen Routes didefinisikan dalam proyek server, parameter AdditionalAssemblies dari komponen Router harus menyertakan assembly proyek .Client. Ini memungkinkan router untuk berfungsi dengan benar ketika dirender secara interaktif.

Dalam contoh berikut, komponen Routes berada dalam proyek server, dan file _Imports.razor dari proyek BlazorSample.Client menunjukkan assembly untuk mencari komponen yang routable.

<Router
    AppAssembly="..."
    AdditionalAssemblies="[ typeof(BlazorSample.Client._Imports).Assembly ]">
    ...
</Router>

Rakitan tambahan dipindai selain rakitan yang ditentukan oleh AppAssembly.

Catatan

Panduan sebelumnya juga berlaku dalam skenario perpustakaan kelas komponen.

Atau, komponen yang dapat dirutekan hanya terdapat dalam proyek .Client dengan WebAssembly Interaktif global atau pengaturan Rendering otomatis yang diterapkan, serta komponen Routes didefinisikan dalam proyek .Client, bukan proyek server. Dalam hal ini, tidak ada rakitan eksternal dengan komponen yang dapat dirutekan, sehingga tidak perlu menentukan nilai untuk AdditionalAssemblies.

Parameter rute

Router menggunakan parameter rute untuk mengisi parameter komponen yang sesuai dengan nama yang sama. Nama parameter rute tidak sensitif terhadap penggunaan huruf besar atau kecil. Dalam contoh berikut, text parameter menetapkan nilai segmen rute ke properti komponen Text . Ketika permintaan dibuat untuk /route-parameter-1/amazing, konten dirender sebagai Blazor is amazing!.

RouteParameter1.razor:

@page "/route-parameter-1/{text}"

<h1>Route Parameter Example 1</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }
}

Parameter opsional didukung. Dalam contoh berikut, parameter opsional text menetapkan nilai segmen rute ke properti Text komponen. Jika segmen tidak ada, nilai Text diatur ke fantastic.

RouteParameter2.razor:

@page "/route-parameter-2/{text?}"

<h1>Route Parameter Example 2</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }

    protected override void OnParametersSet() => Text = Text ?? "fantastic";
}

Ketika OnInitialized{Async} siklus hidup digunakan alih-alih OnParametersSet{Async} siklus hidup, penetapan default Text properti fantastic tidak terjadi jika pengguna menavigasi dalam komponen yang sama. Misalnya, situasi ini muncul ketika pengguna menavigasi dari /route-parameter-2/amazing ke /route-parameter-2. Saat instans komponen bertahan dan menerima parameter baru, OnInitialized metode tidak dipanggil lagi.

Batasan rute

Batasan rute mengharuskan pencocokan jenis pada segmen rute terhadap komponen.

Dalam contoh berikut, rute ke komponen User hanya cocok jika:

• Id Segmen rute ada di URL permintaan.
• Segmen Id adalah jenis bilangan bulat (int).

User.razor:

@page "/user/{Id:int}"

<h1>User Example</h1>

<p>User Id: @Id</p>

@code {
    [Parameter]
    public int Id { get; set; }
}

Batasan rute yang diperlihatkan dalam tabel berikut ini tersedia. Untuk batasan rute yang cocok dengan budaya invarian, lihat peringatan di bawah tabel untuk informasi selengkapnya.

Batasan	Contoh	Contoh Kecocokan	Invarian budaya Kecocokan
bool	{active:bool}	true, FALSE	Tidak
datetime	{dob:datetime}	2016-12-31, 2016-12-31 7:32pm	Ya
decimal	{price:decimal}	49.99, -1,000.01	Ya
double	{weight:double}	1.234, -1,001.01e8	Ya
float	{weight:float}	1.234, -1,001.01e8	Ya
guid	{id:guid}	00001111-aaaa-2222-bbbb-3333cccc4444, {00001111-aaaa-2222-bbbb-3333cccc4444}	Tidak
int	{id:int}	123456789, -123456789	Ya
long	{ticks:long}	123456789, -123456789	Ya
nonfile	{parameter:nonfile}	Bukan BlazorSample.styles.css, bukan favicon.ico	Ya

Peringatan

Batasan rute yang memverifikasi URL dan dikonversi ke jenis CLR (seperti int atau DateTime) selalu menggunakan budaya yang invarian. Batasan ini mengasumsikan bahwa URL tidak dapat dilokalkan.

Batasan rute juga berfungsi dengan parameter opsional. Dalam contoh berikut, Id diperlukan, tetapi Option merupakan parameter rute boolean opsional.

User.razor:

@page "/user/{id:int}/{option:bool?}"

<p>
    Id: @Id
</p>

<p>
    Option: @Option
</p>

@code {
    [Parameter]
    public int Id { get; set; }

    [Parameter]
    public bool Option { get; set; }
}

Hindari pengambilan file dalam parameter rute

Templat rute berikut secara tidak sengaja mengambil jalur aset statis dalam parameter rute opsionalnya (Optional). Misalnya, stylesheet aplikasi (.styles.css) direkam, yang menyebabkan rusaknya gaya aplikasi:

@page "/{optional?}"

...

@code {
    [Parameter]
    public string? Optional { get; set; }
}

Untuk membatasi parameter rute untuk menangkap jalur non-file, gunakan :nonfile batasan dalam templat rute:

@page "/{optional:nonfile?}"

Parameter serbaguna untuk rute

Parameter rute "catch-all", yang menangkap jalur melintasi beberapa batas folder, didukung dalam komponen.

Parameter rute serba guna adalah:

• Dinamai agar sesuai dengan nama segmen rute. Penamaan tidak sensitif terhadap huruf besar/kecil.
• Tipe string. Kerangka kerja tidak menyediakan konversi tipe otomatis.
• Di akhir URL.

CatchAll.razor:

@page "/catch-all/{*pageRoute}"

<h1>Catch All Parameters Example</h1>

<p>Add some URI segments to the route and request the page again.</p>

<p>
    PageRoute: @PageRoute
</p>

@code {
    [Parameter]
    public string? PageRoute { get; set; }
}

Untuk URL /catch-all/this/is/a/test dengan templat rute /catch-all/{*pageRoute}, nilai PageRoute diatur ke this/is/a/test.

Garis miring dan segmen jalur yang diambil didekodekan. Untuk templat rute /catch-all/{*pageRoute}, URL /catch-all/this/is/a%2Ftest%2A menghasilkan this/is/a/test*.

Menangani peristiwa navigasi asinkron dengan OnNavigateAsync

Komponen Router mendukung OnNavigateAsync fitur. Handler OnNavigateAsync dipanggil saat pengguna:

• Mengunjungi rute untuk pertama kalinya dengan menavigasi ke rute tersebut langsung di browser mereka.
• Bernavigasi ke rute baru menggunakan tautan atau NavigationManager.NavigateTo pemanggilan, yang digunakan dalam kode pengembang untuk bernavigasi ke URI. [NavigationManager API dijelaskan di artikel berikutnya, navigasi ASP.NET CoreBlazor.]

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext args)
    {
        ...
    }
}

Untuk contoh yang menggunakan OnNavigateAsync, lihat Lazy load assemblies di ASP.NET CoreBlazor WebAssembly.

Saat melakukan pra-penyajian di server, OnNavigateAsync dijalankan dua kali:

• Saat komponen titik akhir yang diminta pertama kali dirender secara statis.
• Untuk yang kedua kalinya ketika browser merender komponen endpoint.

Untuk mencegah kode pengembang di OnNavigateAsync dari dieksekusi dua kali, komponen Routes dapat menyimpan NavigationContext untuk digunakan dalam metode daur hidup OnAfterRender{Async}, di mana firstRender dapat diperiksa. Untuk informasi selengkapnya, lihat Prerendering dengan JavaScript interop.

Menangani langkah pembatalan di OnNavigateAsync

Objek NavigationContext yang diteruskan ke fungsi pemanggilan balik OnNavigateAsync berisi CancellationToken yang ditetapkan saat peristiwa navigasi baru terjadi. Panggilan balik OnNavigateAsync harus menghasilkan pengecualian ketika token pembatalan ini telah diaktifkan untuk mencegah eksekusi lanjutan panggilan balik OnNavigateAsync pada navigasi yang usang.

Jika pengguna menavigasi ke titik akhir tetapi segera menavigasi ke titik akhir baru, aplikasi tidak boleh terus menjalankan OnNavigateAsync panggilan balik untuk titik akhir pertama.

Dalam contoh berikut:

• Token pembatalan diteruskan dalam panggilan ke PostAsJsonAsync, yang dapat membatalkan POST jika pengguna berpindah dari /about titik akhir.
• Token pembatalan diatur selama operasi pengambilan awal produk jika pengguna berpindah dari /store titik akhir.

@inject HttpClient Http
@inject ProductCatalog Products

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext context)
    {
        if (context.Path == "/about") 
        {
            var stats = new Stats { Page = "/about" };
            await Http.PostAsJsonAsync("api/visited", stats, 
                context.CancellationToken);
        }
        else if (context.Path == "/store")
        {
            var productIds = new[] { 345, 789, 135, 689 };

            foreach (var productId in productIds) 
            {
                context.CancellationToken.ThrowIfCancellationRequested();
                Products.Prefetch(productId);
            }
        }
    }
}

Catatan

Tidak melemparkan jika token pembatalan di NavigationContext dibatalkan dapat mengakibatkan perilaku yang tidak diinginkan, seperti merender komponen dari navigasi sebelumnya.

Interaksi pengguna dengan <Navigating> konten

Jika ada penundaan yang signifikan selama navigasi, seperti saat pemuatan lambat di Blazor WebAssembly aplikasi atau untuk koneksi jaringan yang lambat ke aplikasi sisi server Blazor, komponen Router dapat menunjukkan kepada pengguna bahwa transisi halaman sedang terjadi.

Di bagian atas komponen Router, tambahkan direktif @using untuk namespace Microsoft.AspNetCore.Components.Routing:

@using Microsoft.AspNetCore.Components.Routing

Berikan konten ke Navigating parameter untuk ditampilkan selama peristiwa transisi halaman.

Dalam konten elemen router (<Router>...</Router>):

<Navigating>
    <p>Loading the requested page&hellip;</p>
</Navigating>

Untuk contoh yang menggunakan properti , lihat pemuatan tertunda rakitan di ASP.NET Core .