Omówienie formularzy ASP.NET Core Blazor

• Powiązana z obiektem lub modelem, który może używać adnotacji danych.
  • Formularze HTML z elementem <form> .
  • EditForm Składniki.
• Wbudowane składniki wejściowe.

• EditForm Składnik powiązany z obiektem lub modelem, który może używać adnotacji danych.
• Wbudowane składniki wejściowe.

W aplikacjach Blazor Web App, które korzystają ze statycznego renderowania po stronie serwera (static SSR), komponenty wejściowe są automatycznie uwzględniane w walidacji po stronie klienta, gdy formularz zawiera komponent DataAnnotationsValidator. Aby uzyskać szczegółowe informacje, zobacz ASP.NET Core Blazor forms validation.

Obsługiwane są standardowe formularze HTML. Utwórz formularz przy użyciu normalnego tagu HTML <form> i określ procedurę @onsubmit obsługi przesłanego żądania formularza.

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; }
    }
}

W poprzednim StarshipPlainForm składniku:

• Formularz jest wyświetlany w miejscu, gdzie pojawia się element <form>. Formularz ma nazwę z atrybutem @formname dyrektywy, który jednoznacznie identyfikuje formularz w Blazor strukturze.
• Model jest tworzony w bloku składnika @code i przechowywany w właściwości public (Model). Atrybut [SupplyParameterFromForm] wskazuje, że wartość skojarzonej właściwości powinna być dostarczana z danych formularza. Dane w żądaniu zgodnym z nazwą właściwości są powiązane z właściwością.
• Składnik InputText jest składnikiem wejściowym do edytowania wartości ciągów. Atrybut @bind-Value dyrektywy wiąże Model.Id właściwość modelu z właściwością InputText składnika Value .
• Metoda Submit jest zarejestrowana jako procedura obsługi @onsubmit wywołania zwrotnego. Procedura obsługi jest wywoływana po przesłaniu formularza przez użytkownika.

Blazor Ulepsza nawigację na stronie i obsługę formularzy, przechwytując żądanie w celu zastosowania odpowiedzi do istniejącego modelu DOM, zachowując jak najwięcej renderowanego formularza. Rozszerzenie pozwala uniknąć konieczności pełnego załadowania strony i zapewnia znacznie bardziej płynne środowisko użytkownika, podobnie jak aplikacja jednostronicowa (SPA), chociaż składnik jest renderowany na serwerze. Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor navigation.

Renderowanie strumieniowe jest obsługiwane w przypadku zwykłych formularzy HTML. Należy pamiętać, że podczas POSTtworzenia formularza przesyłane strumieniowo są tylko aktualizacje MODELU DOM wewnątrz procedur obsługi formularza (na przykład @onsubmit). Aktualizacje wewnątrz OnInitializedAsync są przesyłane strumieniowo tylko dla GET żądań. Aby uzyskać więcej informacji, zobacz Pozwalanie na strumieniowe ładowanie odpowiedzi POST (dotnet/aspnetcore #50994).

Powyższy przykład obejmuje obsługę ochrony antyfałszywkowej, dołączając komponent AntiforgeryToken w formularzu. Pomoc techniczna dotycząca ochrony przed fałszerzami jest bardziej objaśniona w sekcji pomocy technicznej dotyczącej ochrony przed fałszerzami w tym artykule.

Aby przesłać formularz na podstawie zdarzeń DOM innego elementu, na przykład oninput lub onblur, użyj języka JavaScript do przesłania formularza (submit).

Zamiast używać zwykłych formularzy w Blazor aplikacjach, formularz jest zazwyczaj definiowany za pomocą wbudowanej obsługi formularzy Blazor przy użyciu składnika frameworka EditForm. Poniższy Razor komponent przedstawia typowe elementy, komponenty i Razor kod do renderowania formularzy internetowych przy użyciu EditForm komponentu.

Formularz jest definiowany przy użyciu Blazor składnika platformy EditForm . Poniższy Razor komponent przedstawia typowe elementy, komponenty i Razor kod do renderowania formularzy internetowych przy użyciu EditForm komponentu.

@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; }
    }
}

W poprzednim Starship1 składniku:

• Składnik EditForm jest renderowany w miejscu, gdzie pojawia się element <EditForm>. Formularz ma nazwę z właściwością FormName, która jednoznacznie identyfikuje formularz w strukturze Blazor.
• Model jest tworzony w bloku składnika @code i przechowywany w właściwości public (Model). Właściwość jest przypisywana do parametru EditForm.Model . Atrybut [SupplyParameterFromForm] wskazuje, że wartość skojarzonej właściwości powinna być dostarczana z danych formularza. Dane w żądaniu zgodnym z nazwą właściwości są powiązane z właściwością.
• Składnik InputText jest składnikiem wejściowym do edytowania wartości ciągów. Atrybut @bind-Value dyrektywy wiąże Model.Id właściwość modelu z właściwością InputText składnika Value .
• Metoda Submit jest zarejestrowana jako obsługa wywołania zwrotnego OnSubmit. Procedura obsługi jest wywoływana po przesłaniu formularza przez użytkownika.

Blazor Poprawia nawigację po stronie i obsługę formularzy dla EditForm komponentów. Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor navigation.

Renderowanie strumieniowe jest obsługiwane przez EditForm. Należy pamiętać, że podczas POSTtworzenia formularza przesyłane strumieniowo są tylko aktualizacje MODELU DOM wewnątrz procedur obsługi formularza (na przykład OnValidSubmit). Aktualizacje wewnątrz OnInitializedAsync są przesyłane strumieniowo tylko dla GET żądań. Aby uzyskać więcej informacji, zobacz Pozwalanie na strumieniowe ładowanie odpowiedzi 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; }
    }
}

W poprzednim Starship1 składniku:

• Składnik EditForm jest renderowany w miejscu, gdzie pojawia się element <EditForm>.
• Model jest tworzony w bloku składnika @code i przechowywany w polu prywatnym (model). Pole jest przypisane do parametru EditForm.Model .
• Składnik InputText jest składnikiem wejściowym do edytowania wartości ciągów. Atrybut @bind-Value dyrektywy wiąże Model.Id właściwość modelu z właściwością InputText składnika Value †.
• Metoda Submit jest zarejestrowana jako obsługa wywołania zwrotnego OnSubmit. Procedura obsługi jest wywoływana po przesłaniu formularza przez użytkownika.

@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; }
    }
}

Obsługa zabezpieczeń przed fałszerstwami

Usługi antyfałszerskie są automatycznie dodawane do aplikacji Blazor, gdy w pliku wywołana zostanie funkcja AddRazorComponentsProgram.

Mechanizm pośredniczący automatycznej ochrony przed fałszowaniem żądań między witrynami (CSRF) jest domyślnie włączony w aplikacjach utworzonych przy użyciu WebApplication.CreateBuilder. Oprogramowanie pośredniczące sprawdza nagłówki Sec-Fetch-Site i Origin w przypadku niebezpiecznych metod HTTP i zapisuje wynik walidacji w żądaniu. Blazor Wpisy formularza renderowania po stronie serwera (SSR) wymuszają ten werdykt i zwracanie 400 Bad Request wpisów formularza między źródłami, które nie są zaufane.

Usługi zabezpieczeń przed fałszerstwem oparte na tokenach są dodawane do aplikacji, gdy w pliku AddRazorComponents wywoływana jest metoda Program. Jednak walidacja tokenu jest wykonywana tylko wtedy, gdy oprogramowanie pośredniczące chroniące przed fałszerstwami żądań zostanie jawnie dodane do potoku przetwarzania żądań przez wywołanie UseAntiforgery.

Dodanie oprogramowania pośredniczącego antyfałszerstwowego opartego na tokenach nie zastępuje automatycznego oprogramowania pośredniczącego ochrony przed atakami CSRF opartego na nagłówkach. Gdy aplikacja wywołuje UseAntiforgery, podczas przesyłania formularza uruchamiane są oba mechanizmy ochrony:

• Warstwa pośrednia ochrony CSRF oparta na nagłówkach jest wykonywana jako pierwsza i zapisuje swój werdykt.
• Oprogramowanie pośredniczące chroniące przed złośliwym oprogramowaniem przeprowadza weryfikację opartą na tokenach.

Wynik oparty na tokenach z oprogramowania pośredniczącego chroniącego przed fałszerzacją jest autorytatywny i zastępuje wcześniejszy werdykt oprogramowania pośredniczącego CSRF opartego na nagłówku.

Aby jawnie dodać oprogramowanie pośredniczące zapobiegające fałszerstwom, wywołaj UseAntiforgery po wywołaniu UseRouting. Jeśli istnieją połączenia do UseRouting i UseEndpoints, wywołanie UseAntiforgery musi znaleźć się pomiędzy nimi. Wywołanie UseAntiforgery musi zostać umieszczone po wywołaniach UseAuthentication i UseAuthorization.

Aby wyłączyć automatyczne oprogramowanie pośredniczące do ochrony CSRF oparte na nagłówkach, ustaw klucz konfiguracji DisableCsrfProtection na true. Na przykład użyj pliku ustawień aplikacji (appsettings.json), aby wyłączyć oprogramowanie pośredniczące:

{
  "DisableCsrfProtection": true
}

DisableCsrfProtection Ustawienie konfiguracji może być dostarczane przez dowolne źródło konfiguracji, w tym za pośrednictwem zmiennej środowiskowej (DisableCsrfProtection=true).

Aby uzyskać więcej informacji, zobacz Automatyczna ochrona CSRF.

Aplikacja używa oprogramowania pośredniczącego chroniącego przed fałszowaniem przez wywołanie UseAntiforgery w swoim potoku przetwarzania żądań w pliku Program. UseAntiforgery jest wywoływana po wywołaniu UseRouting. Jeśli istnieją połączenia do UseRouting i UseEndpoints, wywołanie UseAntiforgery musi znaleźć się pomiędzy nimi. Wywołanie UseAntiforgery musi zostać umieszczone po wywołaniach UseAuthentication i UseAuthorization.

Składnik AntiforgeryToken renderuje token antyfałszerstwowy jako ukryte pole, a atrybut [RequireAntiforgeryToken] umożliwia ochronę przed fałszerstwem. Jeśli weryfikacja antyfałszerstwa się nie powiedzie, zgłoszona zostanie 400 - Bad Request odpowiedź i formularz nie zostanie przetworzony.

W przypadku formularzy opartych na EditForm, składnik AntiforgeryToken i atrybut [RequireAntiforgeryToken] są automatycznie dodawane w celu zapewnienia ochrony przed fałszerstwem.

W przypadku formularzy opartych na elemencie HTML <form> ręcznie dodaj AntiforgeryToken składnik do formularza:

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

Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor uwierzytelnianie i autoryzacja.

Łagodzenie ataków nadmiernego przesyłania danych

Statycznie renderowane formularze po stronie serwera, takie jak te, które są zwykle używane w składnikach tworzących i edytujących rekordy w bazie danych z modelem formularzy, mogą być narażone na atak nadmierny , znany również jako atak masowego przypisania . Atak overposting występuje, gdy złośliwy użytkownik wysyła formularz POST HTML na serwer, który przetwarza dane właściwości formularza, które nie są częścią renderowanego formularza, i do których deweloper nie chce umożliwić użytkownikom dostępu lub modyfikacji. Termin "overposting" oznacza dosłownie, że złośliwy użytkownik zastosował nadmierne wysyłanie POST z formularzem.

Overposting nie jest problemem, gdy model nie zawiera ograniczonych właściwości operacji tworzenia i aktualizowania. Jednak ważne jest, aby pamiętać o problemie nadmiarowego przesyłania podczas pracy ze statycznymi formularzami opartymi na Blazor SSR, które utrzymujesz.

Aby zminimalizować nadmierne przesyłanie danych, zalecamy stosowanie oddzielnego modelu widoku/obiektu transferu danych (DTO) dla formularza i bazy danych, przy operacjach wstawiania i aktualizacji. Po przesłaniu formularza tylko właściwości modelu widoku/DTO są używane przez składnik i kod C# do modyfikowania bazy danych. Wszelkie dodatkowe dane zawarte przez złośliwego użytkownika są odrzucane, więc złośliwy użytkownik nie może przeprowadzić ataku overpostingu.

Ulepszona obsługa formularzy

Ulepsz nawigację dla żądań POST formularza za pomocą parametru Enhance dla formularzy lub atrybutu EditForm dla formularzy HTML (data-enhance):

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

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

❌ Nieobsługiwane: nie można ustawić rozszerzonej nawigacji na elemencie przodkowym formularza, aby włączyć rozszerzoną obsługę formularzy.

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

Rozszerzone wpisy formularza działają tylko z końcowymi punktami Blazor. Opublikowanie rozszerzonego formularza do nie-Blazor punktu końcowego powoduje wystąpienie błędu.

Aby wyłączyć rozszerzoną obsługę formularzy:

• W przypadku elementu EditFormusuń Enhance parametr z elementu formularza (lub ustaw go na wartość false: Enhance="false").
• W przypadku kodu HTML <form>usuń data-enhance atrybut z elementu formularza (lub ustaw go na wartość false: data-enhance="false").

BlazorUlepszona nawigacja i obsługa formularzy mogą cofnąć zmiany dynamiczne w modelu DOM, jeśli zaktualizowana zawartość nie jest częścią renderowania serwera. Aby zachować zawartość elementu, użyj atrybutu data-permanent .

W poniższym przykładzie zawartość <div> elementu jest aktualizowana dynamicznie przez skrypt podczas ładowania strony:

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

Aby wyłączyć rozszerzoną nawigację i obsługę formularzy globalnie, zobacz ASP.NET Core Blazor startup.

Aby uzyskać wskazówki dotyczące używania zdarzenia enhancedload do nasłuchiwania ulepszonych aktualizacji stron, zobacz nawigację w ASP.NET CoreBlazor.

Przykłady nie wykorzystują ulepszonej obsługi formularzy dla żądań POST, ale wszystkie można zaktualizować, aby wdrożyć te ulepszone funkcje, postępując zgodnie ze wskazówkami w sekcji Ulepszona obsługa formularzy.

Przykłady korzystają z operatora typu docelowego new, który został wprowadzony w języku C# 9 i .NET 5. W poniższym przykładzie typ nie jest jawnie określony dla new operatora:

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

Jeśli używasz języka C# 8 lub starszego (ASP.NET Core 3.1), zmodyfikuj przykładowy kod, aby oznaczyć typ operatorem new:

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

Składniki używają typów odwołań dopuszczających wartość null (NRT), a kompilator .NET wykonuje analizę statyczną stanu null, z których obie są obsługiwane w .NET 6 lub nowszych. Aby uzyskać więcej informacji, zobacz Migrate from ASP.NET Core in .NET 5 to .NET 6(

Jeśli używasz języka C# 9 lub starszego (.NET 5 lub starszego), usuń z przykładów punkty NRT. Zwykle polega to jedynie na usunięciu znaków zapytania (?) i wykrzyknika (!) z typów w przykładowym kodzie.

Zestaw SDK .NET stosuje niejawne globalne dyrektywy using do projektów, które są tworzone z myślą o .NET 6 lub nowszym. Przykłady używają rejestratora do rejestrowania informacji o przetwarzaniu formularzy, ale nie ma potrzeby określania dyrektywy @using dla przestrzeni nazw Microsoft.Extensions.Logging w przykładach składników. Aby uzyskać więcej informacji, zobacz zestawy SDK projektu .NET: niejawne używanie dyrektyw.

Jeśli używasz języka C# 9 lub starszego (.NET 5 lub starszego), dodaj dyrektywy @using na początku składnika po dyrektywie @page dla dowolnego interfejsu API wymaganego przez przykład. Znajdź przestrzenie nazw interfejsu API za pomocą Visual Studio (kliknij obiekt prawym przyciskiem myszy i wybierz Peek Definition) lub przeglądarkę interfejsu API .NET.

Walidacja po stronie klienta wymaga obwodu

W Blazor Web App, weryfikacja po stronie klienta wymaga aktywnego obwodu BlazorSignalR. Walidacja po stronie klienta nie jest dostępna dla formularzy w składnikach, które przyjęły statyczne renderowanie po stronie serwera (statyczne SSR). Formularze, które przyjmują statyczne SSR, są weryfikowane na serwerze po przesłaniu formularza.

Walidacja po stronie klienta w statycznych formularzach SSR

W Blazor Web App formularze w komponentach, które używają statycznego renderowania po stronie serwera (statycznego SSR), automatycznie zyskują walidację po stronie klienta, gdy w formularzu jest obecny komponent DataAnnotationsValidator. Aby uzyskać szczegółowe informacje, zobacz ASP.NET Core Blazor forms validation.

• Postępuj zgodnie ze wskazówkami w ASP.NET Core Blazor weryfikacji formularzy dla dowolnego z następujących scenariuszy:
  • Walidacja po stronie serwera w Blazor Web App programie, który przyjmuje tryb renderowania interakcyjnego.
  • Walidacja po stronie klienta w statycznych formularzach SSR.
  • Walidacja po stronie klienta w aplikacji autonomicznej Blazor WebAssembly .
• Użyj natywnych atrybutów weryfikacji HTML (zobacz Walidacja formularza po stronie klienta).
• Adopt a third-party validation JavaScript library (Wdrażanie biblioteki JavaScript walidacji innej firmy).

• Postępuj zgodnie ze wskazówkami w ASP.NET Core Blazor walidacja formularzy dla jednej z dwóch opcji:
  • Walidacja po stronie serwera w Blazor Web App programie, który przyjmuje tryb renderowania interakcyjnego.
  • Walidacja po stronie klienta w aplikacji autonomicznej Blazor WebAssembly .
• Użyj natywnych atrybutów weryfikacji HTML (zobacz Walidacja formularza po stronie klienta).
• Adopt a third-party validation JavaScript library (Wdrażanie biblioteki JavaScript walidacji innej firmy).

• ASP.NET Core Blazor przesyłanie plików
• Blazor samples GitHub repository (dotnet/blazor-samples) (Jak pobrać)
• Repozytorium ASP.NET Core na GitHubie (dotnet/aspnetcore) tworzy zasoby testowe

• ASP.NET Core Blazor przesyłanie plików
• Blazor WebAssembly
• Zabezpiecz hostowaną aplikację ASP.NET Core przy użyciu Azure Active Directory B2C
• Zabezpiecz hostowaną aplikację ASP.NET Core przy użyciu Server
• Blazor samples GitHub repository (dotnet/blazor-samples) (Jak pobrać)
• Repozytorium ASP.NET Core na GitHubie (dotnet/aspnetcore) tworzy zasoby testowe