Dasar-dasar Blazor ASP.NET Core

Artikel Dasar-dasar memberikan panduan tentang konsep Blazor dasar. Beberapa konsep terkait dengan pemahaman dasar tentang komponen Razor, yang dijelaskan lebih lanjut di bagian berikutnya dari artikel ini dan dibahas secara mendetail dalam artikel Komponen.

Konsep penyajian klien dan server

Sepanjang Blazor dokumentasi, aktivitas yang terjadi pada sistem pengguna dikatakan terjadi di sisi klien atau klien. Aktivitas yang terjadi di server dikatakan terjadi di server atau sisi server.

Istilah penyajian berarti menghasilkan markup HTML yang ditampilkan browser.

• Penyajian sisi klien (CSR) berarti markup HTML akhir dihasilkan oleh Blazor WebAssembly runtime pada klien. Tidak ada HTML untuk UI yang dihasilkan klien aplikasi yang dikirim dari server ke klien untuk jenis penyajian ini. Interaktivitas pengguna dengan halaman diasumsikan. Tidak ada konsep seperti penyajian sisi klien statis . CSR diasumsikan interaktif, sehingga "penyajian sisi klien interaktif " dan "CSR interaktif " tidak digunakan oleh industri atau dalam Blazor dokumentasi.

• Penyajian sisi server (SSR) berarti markup HTML akhir dihasilkan oleh runtime ASP.NET Core di server. HTML dikirim ke klien melalui jaringan untuk ditampilkan oleh browser klien. Tidak ada HTML untuk UI yang dihasilkan server aplikasi yang dibuat oleh klien untuk jenis penyajian ini. SSR dapat terdiri dari dua varietas:

  • SSR statis: Server menghasilkan HTML statis yang tidak menyediakan interaktivitas pengguna atau mempertahankan Razor status komponen.
  • SSR interaktif: Blazor peristiwa memungkinkan interaktivitas pengguna dan Razor status komponen dikelola oleh Blazor kerangka kerja.

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

Konsep penyajian statis dan interaktif

Razor komponen dirender secara statis atau dirender secara interaktif.

Penyajian statis atau statis adalah skenario sisi server yang berarti komponen dirender tanpa kapasitas untuk interplay antara pengguna dan kode .NET/C#. Peristiwa JavaScript dan HTML DOM tetap tidak terpengaruh, tetapi tidak ada peristiwa pengguna pada klien yang dapat diproses dengan .NET yang berjalan di server.

Penyajian interaktif atau interaktif berarti bahwa komponen memiliki kapasitas untuk memproses peristiwa .NET melalui kode C#. Peristiwa .NET diproses di server oleh runtime ASP.NET Core atau di browser pada klien oleh runtime berbasis Blazor WebAssembly.

Penting

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

Informasi selengkapnya tentang konsep-konsep ini dan cara mengontrol penyajian statis dan interaktif ditemukan dalam artikel mode render ASP.NET Core Blazor nanti dalam Blazor dokumentasi.

Komponen Razor

Aplikasi Blazor didasarkan pada komponen Razor, sering disebut hanya sebagai komponen. Komponen adalah elemen UI, seperti halaman, dialog, atau formulir entri data. Komponen adalah kelas C# .NET yang dibangun dalam rakitan .NET.

Razor mengacu pada bagaimana komponen biasanya ditulis dalam bentuk halaman markup Razor untuk logika dan komposisi UI sisi klien. Razor adalah sintaks untuk menggabungkan markup HTML dengan kode C# yang dirancang untuk produktivitas pengembang. File Razor menggunakan ekstensi file .razor.

Meskipun beberapa pengembang Blazor dan sumber daya online menggunakan istilah "komponen Blazor", dokumentasi menghindari istilah tersebut dan secara universal menggunakan "komponen Razor" atau "komponen".

Dokumentasi Blazor mengadopsi beberapa konvensi untuk menampilkan dan mendiskusikan komponen:

• Kode proyek, jalur dan nama file, nama template proyek, dan istilah khusus lainnya dalam bahasa Inggris Amerika Serikat dan biasanya dipagari kode.
• Komponen biasanya dirujuk menggunakan nama kelas C# (Pascal case) diikuti dengan kata "komponen". Misalnya, komponen pengunggahan file umumnya disebut sebagai "komponen FileUpload".
• Biasanya, nama kelas C# komponen sama dengan nama filenya.
• Komponen yang dapat dirutekan biasanya mengatur URL relatifnya ke nama kelas komponen dalam kebab-case. Misalnya, komponen FileUpload menyertakan konfigurasi perutean untuk mencapai komponen yang dirender di /file-upload URL relatif. Perutean dan navigasi tercakup dalam perutean dan navigasi Blazor ASP.NET Core.
• Ketika beberapa versi komponen digunakan, komponen tersebut diberi nomor secara berurutan. Misalnya, komponen tercapai FileUpload3 di /file-upload-3.
• Razor direktif di bagian atas definisi komponen (.razor file) ditempatkan dalam urutan berikut: @page, ( @rendermode .NET 8 atau yang lebih baru), @using pernyataan, arahan lain dalam urutan alfabet. Informasi tambahan tentang Razor pengurutan direktif ditemukan di bagianRazorsintaks komponen ASP.NET CoreRazor.
• Pengubah akses digunakan dalam contoh artikel. Misalnya, bidang adalah private secara default tetapi secara eksplisit ada dalam kode komponen. Misalnya, private dinyatakan untuk mendeklarasikan bidang bernama maxAllowedFiles sebagai private int maxAllowedFiles = 3;.
• Nilai parameter komponen mengarah dengan simbol yang Razor dipesan@, tetapi tidak diperlukan. Literal (misalnya, nilai boolean), kata kunci (misalnya, this), dan null karena nilai parameter komponen tidak diawali dengan @, tetapi ini juga hanya konvensi dokumentasi. Kode Anda sendiri dapat mengawali literal dengan @ jika Anda mau.
• Umumnya, contoh mematuhi konvensi pengodean ASP.NET Core/C# dan pedoman teknik. Untuk informasi selengkapnya, lihat sumber daya berikut ini:
  • Pedoman teknik (repositori GitHub dotnet/aspnetcore)
  • Konvensi Pengodean C# (panduan C#)

Berikut ini adalah contoh komponen penghitung dan bagian dari aplikasi yang dibuat dari template proyek Blazor. Cakupan komponen terperinci ditemukan di artikel Komponen nanti dalam dokumentasi. Contoh berikut menunjukkan konsep komponen yang terlihat di artikel Dasar-dasar sebelum mencapai artikel Komponen nanti dalam dokumentasi.

Counter.razor:

Komponen mengasumsikan bahwa mode render interaktif diwariskan dari komponen induk atau diterapkan secara global ke aplikasi.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

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

Komponen Counter sebelumnya:

• Menetapkan rutenya dengan arahan @page di baris pertama.
• Menetapkan judul halaman dan judul.
• Membuat hitungan saat ini dengan @currentCount. currentCount adalah variabel bilangan bulat yang ditentukan dalam kode C# dari blok @code.
• Menampilkan tombol untuk memicu metode IncrementCount, yang juga ditemukan di blok @code dan meningkatkan nilai variabel currentCount.

Mode render

Artikel dalam node Fundamentals merujuk pada konsep mode render. Subjek ini dibahas secara rinci dalam artikel mode render ASP.NET Core Blazor di node Komponen, yang muncul setelah node Dasar-Dasar artikel.

Untuk referensi awal dalam simpul artikel ini untuk merender konsep mode, perhatikan hal-hal berikut saat ini:

Setiap komponen dalam Blazor Aplikasi Web mengadopsi mode render untuk menentukan model hosting yang digunakannya, tempatnya dirender, dan apakah dirender secara statis di server, dirender dengan untuk interaktivitas pengguna di server, atau dirender untuk interaktivitas pengguna pada klien (biasanya dengan prarender di server).

Blazor Server dan Blazor WebAssembly aplikasi untuk rilis ASP.NET Core sebelum .NET 8 tetap terpasang pada konsep model hosting, bukan mode render. Mode render secara konseptual diterapkan ke Blazor Web Apps di .NET 8 atau yang lebih baru.

Tabel berikut ini memperlihatkan mode render yang tersedia untuk merender Razor komponen di Blazor Aplikasi Web. Mode render diterapkan ke komponen dengan direktif @rendermode pada instans komponen atau pada definisi komponen. Anda juga dapat mengatur mode render untuk seluruh aplikasi.

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

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

Informasi sebelumnya tentang mode render adalah semua yang perlu Anda ketahui untuk memahami artikel node Fundamentals . Jika Anda baru menggunakan Blazor dan membaca Blazor artikel untuk menurunkan daftar isi, Anda dapat menunda penggunaan informasi mendalam tentang mode render hingga Anda mencapai artikel mode render ASP.NET Core Blazor di node Komponen.

Model Objek Dokumen (DOM)

Referensi ke Model Objek Dokumen menggunakan singkatan DOM.

Untuk informasi selengkapnya, lihat sumber daya berikut:

• Pengantar DOM (dokumentasi MDN)
• Spesifikasi Model Objek Dokumen Tingkat 1 (W3C)

Subset API .NET untuk Blazor WebAssembly aplikasi

Daftar yang dikumpulkan dari API .NET tertentu yang didukung di browser Blazor WebAssembly untuk tidak tersedia. Namun, Anda dapat mencari daftar API .NET yang dianotasi secara [UnsupportedOSPlatform("browser")] manual untuk menemukan API .NET yang tidak didukung di WebAssembly.

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).

Untuk informasi selengkapnya, lihat sumber daya berikut:

• Pustaka kelas: Penganalisis kompatibilitas browser sisi klien
• Menganotasi API sebagai tidak didukung pada platform tertentu (dotnet/designs repositori GitHub

Aplikasi sampel

Aplikasi sampel dokumentasi tersedia untuk diperiksa dan diunduh:

Blazor sampel repositori GitHub (dotnet/blazor-samples)

Temukan aplikasi sampel dengan terlebih dahulu memilih folder versi yang cocok dengan versi .NET yang sedang Anda kerjakan.

Aplikasi sampel di repositori:

• Blazor Aplikasi Web
• Blazor WebAssembly
• Blazor Aplikasi Web dengan EF Core (ASP.NET Core Blazor dengan Entity Framework Core (EF Core))
• Blazor Aplikasi Web dengan SignalR (Gunakan ASP.NET Core SignalR dengan Blazor)
• Dua Blazor Web Apps dan aplikasi Blazor WebAssembly untuk memanggil API web (server) (Panggil API web dari aplikasi ASP.NET CoreBlazor)
• Blazor Aplikasi Web dengan OIDC (pola BFF dan non-BFF) (Mengamankan aplikasi web ASP.NET Core Blazor dengan OpenID Connect (OIDC))
• Blazor WebAssemblypengelogan berkemampuan cakupan (pengelogan ASP.NET CoreBlazor)
• Blazor WebAssemblydengan ASP.NET Core Identity (Secure ASP.NET Core Blazor WebAssembly dengan ASP.NET Core Identity)
• .NET MAUIBlazor Hybrid aplikasi dengan Blazor Aplikasi Web dan UI bersama yang disediakan oleh Razor pustaka kelas (RCL) (Bangun .NET MAUIBlazor Hybrid aplikasi dengan Blazor Aplikasi Web)

Untuk informasi selengkapnya, lihat Blazor file README.md repositori GitHub sampel.

Aplikasi Pengujian Dasar repositori ASP.NET Core juga merupakan serangkaian sampel yang berguna untuk berbagai Blazor skenario:

BasicTestApp di sumber referensi ASP.NET Core (dotnet/aspnetcore)

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).

Untuk mengunduh aplikasi sampel:

• Blazor Unduh file ZIP repositori sampel.
• Ekstrak file.

Perkalian byte

Ukuran byte .NET menggunakan awalan metrik untuk kelipatan byte non-desimal berdasarkan daya 1024.

Nama (singkatan)	Ukuran	Contoh
Kilobyte (KB)	1.024 byte	1 KB = 1.024 byte
Megabyte (MB)	1.0242 byte	1 MB = 1.048.576 byte
Gigabyte (GB)	1.0243 byte	1 GB = 1.073.741.824 byte

Permintaan dukungan

Hanya masalah terkait dokumentasi yang sesuai untuk repositori dotnet/AspNetCore.Docs. Untuk dukungan produk, jangan buka masalah dokumentasi. Cari bantuan melalui satu atau beberapa saluran dukungan berikut:

• Stack Overflow (diberi tag: blazor)
• Tim ASP.NET Core Slack Umum
• Blazor Gitter

Untuk kemungkinan bug dalam kerangka kerja atau umpan balik produk, buka masalah untuk unit produk ASP.NET Core di masalah dotnet/aspnetcore. Laporan bug biasanya memerlukan berikut ini:

• Penjelasan masalah yang jelas: Ikuti petunjuk di template masalah GitHub yang disediakan oleh unit produk saat membuka masalah.
• Proyek repro minimal: Tempatkan proyek di GitHub untuk diunduh dan dijalankan oleh teknisi unit produk. Tautkan silang proyek ke komentar pembuka masalah.

Untuk kemungkinan masalah dengan artikel Blazor, buka masalah dokumentasi. Untuk membuka masalah dokumentasi, gunakan tombol dan formulir umpan balik Halaman ini di bagian bawah artikel dan biarkan metadata tetap di tempatnya saat membuat komentar pembuka. Metadata menyediakan data pelacakan dan secara otomatis melakukan ping ke pembuat artikel. Jika subjek telah didiskusikan dengan unit produk, tempatkan tautan silang ke masalah teknik dalam komentar pembuka masalah dokumentasi.

Untuk masalah atau umpan balik di Visual Studio, gunakan gerakan Laporkan Masalah atau Sarankan Fitur dari dalam Visual Studio, yang membuka masalah internal untuk Visual Studio. Untuk informasi selengkapnya, lihat Umpan Balik Visual Studio.

Untuk masalah dengan Visual Studio Code, mintalah dukungan di forum dukungan komunitas. Untuk laporan bug dan umpan balik produk, buka masalah di repo GitHub microsoft/vscode.

Masalah GitHub untuk dokumentasi Blazor secara otomatis ditandai untuk triase pada proyek Blazor.Docs (repositori GitHub dotnet/AspNetCore.Docs). Harap tunggu beberapa saat untuk memperoleh respons, terutama saat akhir pekan dan hari libur. Biasanya, pembuat dokumentasi merespons dalam waktu 24 jam pada hari kerja.

Tautan komunitas ke sumber daya Blazor

Untuk kumpulan tautan ke sumber daya Blazor yang dikelola oleh komunitas, kunjungi Awesome Blazor.

Catatan

Microsoft tidak memiliki, mengelola, atau mendukung Awesome Blazor dan sebagian besar produk dan layanan komunitas yang dijelaskan dan ditautkan di sana.