Gambaran umum form ASP.NET Core Blazor

• Terikat ke objek atau model yang dapat menggunakan anotasi data.
  • Formulir HTML dengan <form> elemen .
  • EditForm Komponen.
• Komponen input bawaan.

• Komponen EditForm terikat ke objek atau model yang dapat menggunakan anotasi data.
• Komponen input bawaan.

Dalam Blazor Web App yang menggunakan perenderan sisi server statis (SSR statis), komponen input secara otomatis ikut serta dalam validasi di sisi klien saat formulir berisi komponen DataAnnotationsValidator. Untuk detailnya, lihat validasi formulir ASP.NET Core Blazor.

Formulir HTML standar didukung. Buat formulir menggunakan tag HTML <form> normal dan tentukan @onsubmit handler untuk menangani permintaan formulir yang dikirimkan.

StarshipPlainForm.razor:

@page "/starship-plain-form"
@inject ILogger<StarshipPlainForm> Logger

<form method="post" @onsubmit="Submit" @formname="starship-plain-form">
    <AntiforgeryToken />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</form>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        public string? Id { get; set; }
    }
}

@page "/starship-plain-form"
@inject ILogger<StarshipPlainForm> Logger

<form method="post" @onsubmit="Submit" @formname="starship-plain-form">
    <AntiforgeryToken />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</form>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        public string? Id { get; set; }
    }
}

Di komponen sebelumnya StarshipPlainForm :

• Form dirender di tempat elemen <form> muncul. Formulir dinamai dengan atribut direktif @formname , yang secara unik mengidentifikasi formulir ke Blazor kerangka kerja.
• Model dibuat dalam blok dari komponen @code dan disimpan dalam properti public(Model). Atribut [SupplyParameterFromForm] menunjukkan bahwa nilai properti terkait harus disediakan dari data formulir. Data dalam permintaan yang cocok dengan nama properti akan terikat pada properti tersebut.
• Komponen InputText adalah komponen input untuk mengedit nilai string. Atribut direktif @bind-Value menghubungkan properti model Model.Id ke properti InputText dalam komponen Value.
• Metode Submit terdaftar sebagai handler untuk panggilan balik @onsubmit. Handler dipanggil ketika formulir dikirimkan oleh pengguna.

Blazor meningkatkan navigasi halaman dan penanganan formulir dengan mencegat permintaan untuk menerapkan respons ke DOM yang ada, mempertahankan sebanyak mungkin formulir yang dirender. Peningkatan menghindari kebutuhan untuk sepenuhnya memuat halaman dan memberikan pengalaman pengguna yang jauh lebih lancar, mirip dengan aplikasi satu halaman (SPA), meskipun komponen dirender di server. Untuk informasi selengkapnya, lihat navigasi ASP.NET Core Blazor.

Penyajian streaming didukung untuk formulir HTML biasa. Perhatikan bahwa ketika POST suatu formulir, hanya pembaruan DOM di dalam penangan formulir yang dialirkan (misalnya, @onsubmit). Pembaruan di dalam OnInitializedAsync hanya dialirkan untuk permintaan GET. Untuk informasi selengkapnya, lihat Izinkan streaming fase pemuatan respons POST (dotnet/aspnetcore #50994).

Contoh sebelumnya mencakup dukungan antiforgery dengan menyertakan komponen AntiforgeryToken dalam formulir. Dukungan antiforgery dijelaskan lebih lanjut di bagian Dukungan Antiforgery dari artikel ini.

Untuk mengirimkan formulir berdasarkan peristiwa DOM elemen lain, misalnya oninput atau onblur, gunakan JavaScript untuk mengirimkan formulir (submit).

Alih-alih menggunakan formulir biasa dalam aplikasi Blazor, formulir biasanya didefinisikan dengan dukungan formulir bawaan Blazor menggunakan komponen EditForm dari framework. Komponen berikut Razor menunjukkan elemen, komponen, dan Razor kode umum untuk merender formulir web dengan menggunakan komponen EditForm.

Formulir didefinisikan menggunakan komponen Blazor dari kerangka EditForm. Komponen berikut Razor menunjukkan elemen, komponen, dan Razor kode umum untuk merender formulir web dengan menggunakan komponen EditForm.

@page "/starship-1"
@inject ILogger<Starship1> Logger

<EditForm Model="Model" OnSubmit="Submit" FormName="Starship1">
    <div>
        <label>
            Identifier:
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        public string? Id { get; set; }
    }
}

@page "/starship-1"
@inject ILogger<Starship1> Logger

<EditForm Model="Model" OnSubmit="Submit" FormName="Starship1">
    <div>
        <label>
            Identifier:
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        public string? Id { get; set; }
    }
}

Di komponen sebelumnya Starship1 :

• Komponen EditForm dirender di mana elemen <EditForm> muncul. Formulir dinamai dengan properti FormName, yang secara unik mengidentifikasi formulir ke kerangka kerja Blazor.
• Model dibuat dalam blok dari komponen @code dan disimpan dalam properti public(Model). Properti ditetapkan pada parameter EditForm.Model. Atribut [SupplyParameterFromForm] menunjukkan bahwa nilai properti terkait harus disediakan dari data formulir. Data dalam permintaan yang cocok dengan nama properti akan terikat pada properti tersebut.
• Komponen InputText adalah komponen input untuk mengedit nilai string. Atribut direktif @bind-Value menghubungkan properti model Model.Id ke properti InputText dalam komponen Value.
• Metode Submit ini terdaftar sebagai handler untuk OnSubmit panggilan balik. Handler dipanggil ketika formulir dikirimkan oleh pengguna.

Blazor meningkatkan navigasi halaman dan penanganan formulir untuk EditForm komponen. Untuk informasi selengkapnya, lihat navigasi ASP.NET Core Blazor.

Penyajian streaming didukung untuk EditForm. Perhatikan bahwa ketika POST suatu formulir, hanya pembaruan DOM di dalam penangan formulir yang dialirkan (misalnya, OnValidSubmit). Pembaruan di dalam OnInitializedAsync hanya dialirkan untuk permintaan GET. Untuk informasi selengkapnya, lihat Izinkan streaming fase pemuatan respons POST (dotnet/aspnetcore #50994).

@page "/starship-1"
@inject ILogger<Starship1> Logger

<EditForm Model="Model" OnSubmit="Submit">
    <InputText @bind-Value="Model!.Id" />
    <button type="submit">Submit</button>
</EditForm>

@code {
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Model.Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        public string? Id { get; set; }
    }
}

Di komponen sebelumnya Starship1 :

• Komponen EditForm dirender di mana elemen <EditForm> muncul.
• Model dibuat di blok komponen @code dan disimpan di bidang privat (model). Bidang ditetapkan ke parameter EditForm.Model.
• Komponen InputText adalah komponen input untuk mengedit nilai string. Properti model @bind-Value diikat oleh atribut Model.Id direktif ke properti InputText milik komponen Value †.
• Metode Submit ini terdaftar sebagai handler untuk OnSubmit panggilan balik. Handler dipanggil ketika formulir dikirimkan oleh pengguna.

@page "/starship-2"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship2> Logger

<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship2">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <label>
        Identifier: 
        <InputText @bind-Value="Model!.Id" />
    </label>
    <button type="submit">Submit</button>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        [Required]
        [StringLength(10, ErrorMessage = "Id is too long.")]
        public string? Id { get; set; }
    }
}

@page "/starship-2"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship2> Logger

<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship2">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <label>
        Identifier: 
        <InputText @bind-Value="Model!.Id" />
    </label>
    <button type="submit">Submit</button>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        [Required]
        [StringLength(10, ErrorMessage = "Id is too long.")]
        public string? Id { get; set; }
    }
}

@page "/starship-2"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship2> Logger

<EditForm Model="Model" OnValidSubmit="Submit">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <InputText @bind-Value="Model!.Id" />
    <button type="submit">Submit</button>
</EditForm>

@code {
    public Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit()
    {
        Logger.LogInformation("Id = {Id}", Model?.Id);
    }

    public class Starship
    {
        [Required]
        [StringLength(10, ErrorMessage = "Id is too long.")]
        public string? Id { get; set; }
    }
}

Dukungan antipemalsuan

Layanan anti-pemalsuan secara otomatis ditambahkan ke aplikasi Blazor saat dipanggil dalam berkas AddRazorComponents dengan Program.

Aplikasi ini menggunakan Antiforgery Middleware dengan memanggil UseAntiforgery dalam alur pemrosesan permintaannya dalam Program file. UseAntiforgery dipanggil setelah panggilan ke UseRouting. Jika ada panggilan ke UseRouting dan UseEndpoints, panggilan ke UseAntiforgery harus berada di antara mereka. Panggilan ke UseAntiforgery harus dilakukan setelah panggilan ke UseAuthentication dan UseAuthorization.

Komponen AntiforgeryToken merender token antiforgery sebagai bidang tersembunyi, sedangkan atribut [RequireAntiforgeryToken] memungkinkan perlindungan antiforgery. Jika pemeriksaan antiforgery gagal, 400 - Bad Request respons akan dihasilkan dan formulir tidak diproses.

Untuk formulir yang berdasarkan EditForm, komponen AntiforgeryToken dan atribut [RequireAntiforgeryToken] secara otomatis ditambahkan untuk memberikan perlindungan anti-pemalsuan.

Untuk formulir berdasarkan elemen HTML <form> , tambahkan AntiforgeryToken komponen secara manual ke formulir:

<form method="post" @onsubmit="Submit" @formname="starshipForm">
    <AntiforgeryToken />
    <input id="send" type="submit" value="Send" />
</form>

@if (submitted)
{
    <p>Form submitted!</p>
}

@code{
    private bool submitted = false;

    private void Submit() => submitted = true;
}

@using Microsoft.AspNetCore.Antiforgery
@attribute [RequireAntiforgeryToken(required: false)]

Untuk informasi selengkapnya, lihat autentikasi dan otorisasi ASP.NET Core Blazor.

Mengurangi serangan publikasi berlebihan

Formulir sisi server yang dirender secara statis, seperti yang biasanya digunakan dalam komponen yang membuat dan mengedit rekaman dalam basis data dengan model formulir, dapat rentan terhadap serangan overposting, juga dikenal sebagai serangan penugasan massal. Serangan overposting terjadi ketika pengguna berbahaya mengirimkan permintaan POST melalui formulir HTML ke server yang memproses data untuk properti yang bukan bagian dari formulir yang ditampilkan dan yang pengembang tidak ingin pengguna modifikasi. Istilah "overposting" secara harfiah berarti bahwa pengguna jahat telah melakukan POST berlebihan dengan menggunakan formulir.

Overposting bukan masalah ketika model tidak menyertakan properti terbatas untuk operasi membuat dan memperbarui. Namun, penting untuk mengingat kemungkinan posting berlebihan saat bekerja dengan formulir SSR statis yang berbasis Blazor yang Anda pertahankan.

Untuk mengurangi overposting, sebaiknya gunakan model tampilan terpisah/objek transfer data (DTO) untuk formulir dan database dengan operasi buat (sisipkan) dan perbarui. Saat formulir dikirimkan, hanya properti model tampilan/DTO yang digunakan oleh komponen dan kode C# untuk memodifikasi database. Setiap data tambahan yang disertakan oleh pengguna berbahaya dibuang, sehingga pengguna berbahaya dicegah melakukan serangan overposting.

Peningkatan dalam penanganan formulir

Tingkatkan navigasi untuk permintaan POST formulir dengan Enhance parameter untuk EditForm formulir atau data-enhance atribut untuk formulir HTML (<form>):

<EditForm ... Enhance ...>
    ...
</EditForm>

<form ... data-enhance ...>
    ...
</form>

❌ Tidak didukung: Anda tidak dapat mengatur navigasi yang ditingkatkan pada elemen leluhur formulir untuk mengaktifkan penanganan formulir yang ditingkatkan.

<div ... data-enhance ...>
    <form ...>
        <!-- NOT enhanced -->
    </form>
</div>

Posting formulir yang disempurnakan hanya berfungsi dengan Blazor titik akhir. Memposting formulir yang disempurnakan ke endpoint non-Blazor menyebabkan kesalahan.

Untuk menonaktifkan penanganan formulir yang ditingkatkan:

• Hapus parameter EditForm dari elemen formulir (atau atur menjadi Enhance: false).
• Untuk HTML <form>, hapus data-enhance atribut dari elemen formulir (atau atur ke false: data-enhance="false").

BlazorNavigasi dan penanganan formulir yang disempurnakan dapat membatalkan perubahan dinamis pada DOM jika konten yang diperbarui bukan bagian dari penyajian server. Untuk mempertahankan konten elemen, gunakan data-permanent atribut .

Dalam contoh berikut, konten dari elemen <div> diperbarui secara dinamis oleh skrip saat halaman dimuat.

<div data-permanent>
    ...
</div>

Untuk menonaktifkan navigasi dan penanganan formulir yang disempurnakan secara global, lihat startup ASP.NET Core Blazor.

Untuk panduan tentang menggunakan peristiwa enhancedload untuk mendengarkan pembaruan halaman yang ditingkatkan, lihat navigasi ASP.NET Core Blazor.

Contoh tidak menggunakan penanganan formulir yang ditingkatkan untuk permintaan POST form, tetapi semua contoh dapat diperbarui dengan mengikuti panduan di bagian Penanganan formulir yang ditingkatkan agar dapat mengadopsi fitur yang ditingkatkan.

Contohnya menggunakan operator yang berjenis target, yang diperkenalkan dengan C# 9 dan .NET 5. Dalam contoh berikut, jenis tidak dinyatakan secara eksplisit untuk new operator:

public ShipDescription ShipDescription { get; set; } = new();

Jika menggunakan C# 8 atau yang lebih lama (ASP.NET Core 3.1), ubah kode contoh untuk menyatakan jenis ke operator new:

public ShipDescription ShipDescription { get; set; } = new ShipDescription();

Komponen menggunakan jenis referensi nullable (NRT), dan pengkompilasi .NET melakukan analisis statis status null, yang keduanya didukung dalam .NET 6 atau yang lebih baru. Untuk informasi selengkapnya, lihat Migrate dari ASP.NET Core di .NET 5 hingga .NET 6.

Jika menggunakan C# 9 atau yang lebih lama (.NET 5 atau yang lebih lama), hapus NRT dari contoh. Biasanya, ini hanya melibatkan penghapusan tanda tanya (?) dan tanda seru (!) dari jenis dalam kode contoh.

SDK .NET menerapkan arahan using global implisit ke proyek saat menargetkan .NET 6 atau yang lebih baru. Contoh menggunakan pencatat untuk mencatat informasi tentang pemrosesan formulir, tetapi tidak perlu menentukan direktif @using untuk namespace Microsoft.Extensions.Logging dalam contoh komponen. Untuk informasi selengkapnya, lihat SDK proyek .NET: Implisit menggunakan direktif.

Jika menggunakan C# 9 atau yang lebih lama (.NET 5 atau yang lebih lama), tambahkan arahan @using ke bagian atas komponen setelah arahan @page untuk API apa pun yang diperlukan oleh contoh. Temukan namespace API melalui Visual Studio (klik kanan objek dan pilih definisi Peek) atau browser API .NET.

Validasi sisi klien memerlukan sirkuit

Dalam Blazor Web Apphal ini, validasi sisi klien memerlukan sirkuit yang aktif BlazorSignalR. Validasi sisi klien tidak tersedia untuk formulir dalam komponen yang telah mengadopsi penyajian sisi server statis (SSR statis). Formulir yang mengadopsi SSR statis divalidasi di server setelah formulir dikirimkan.

Validasi sisi klien dalam formulir SSR statis

Dalam Blazor Web App, formulir dalam komponen yang mengadopsi perenderan statis di sisi server (SSR statis) secara otomatis memperoleh validasi di sisi klien saat komponen DataAnnotationsValidator terdapat dalam formulir. Untuk detailnya, lihat validasi formulir ASP.NET Core Blazor.

• Ikuti panduan dalam validasi formulir ASP.NET Core Blazor untuk salah satu skenario berikut:
  • Validasi sisi server dalam Blazor Web App yang mengadopsi mode render interaktif.
  • Validasi sisi klien dalam bentuk SSR statis.
  • Validasi di sisi klien dalam aplikasi mandiri Blazor WebAssembly.
• Gunakan atribut validasi HTML asli (lihat validasi formulir sisi klien).
• Mengadopsi pustaka JavaScript validasi pihak ketiga.

• Ikuti panduan dalam validasi formulir ASP.NET Core Blazor untuk:
  • Validasi sisi server dalam Blazor Web App yang mengadopsi mode render interaktif.
  • Validasi di sisi klien dalam aplikasi mandiri Blazor WebAssembly.
• Gunakan atribut validasi HTML asli (lihat validasi formulir sisi klien).
• Mengadopsi pustaka JavaScript validasi pihak ketiga.

• unggahan file ASP.NET Core Blazor
• Blazor sampel GitHub repositorium (dotnet/blazor-samples) (cara mengunduh)
• repositori ASP.NET Core GitHub (dotnet/aspnetcore) membentuk aset pengujian

• unggahan file ASP.NET Core Blazor
• Amankan aplikasi ASP.NET Core Blazor WebAssembly yang dihosting dengan Microsoft Entra ID
• Amankan aplikasi ASP.NET Core Blazor WebAssembly yang dihosting dengan Azure Active Directory B2C
• Amankan aplikasi ASP.NET Core Blazor WebAssembly yang dihosting dengan Identity Server
• Blazor sampel GitHub repositorium (dotnet/blazor-samples) (cara mengunduh)
• repositori ASP.NET Core GitHub (dotnet/aspnetcore) membentuk aset pengujian