Overzicht van ASP.NET Core Blazor-formulieren

In dit artikel wordt uitgelegd hoe u formulieren gebruikt in Blazor.

Invoeronderdelen en -formulieren

Het Blazor framework ondersteunt formulieren en biedt ingebouwde invoeronderdelen:

• Afhankelijk van een object of model dat gegevensaantekeningenkan gebruiken.
  • HTML-formulieren met het <form>-element.
  • EditForm onderdelen.
• Ingebouwde invoerelementen.

Notitie

Niet-ondersteunde ASP.NET Kernvalidatiefuncties worden behandeld in de sectie Niet-ondersteunde validatiefuncties.

De Microsoft.AspNetCore.Components.Forms-naamruimte biedt:

• Klassen voor het beheren van formulierelementen, status en validatie.
• Toegang tot ingebouwde Input* onderdelen.

Een project dat is gemaakt op basis van de Blazor projectsjabloon bevat de naamruimte in het _Imports.razor-bestand van de app, waardoor de naamruimte beschikbaar is voor de Razor onderdelen van de app.

Standaard HTML-formulieren worden ondersteund. Maak een formulier met behulp van de normale HTML-<form> tag en geef een @onsubmit handler op voor het verwerken van de ingediende formulieraanvraag.

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

In het voorgaande StarshipPlainForm onderdeel:

• Het formulier wordt weergegeven waar het element <form> wordt weergegeven. Het formulier is benoemd met het @formname-richtlijnattribuut, waarmee het formulier uniek wordt geïdentificeerd door het Blazor-framework.
• Het model wordt aangemaakt in het @code-blok van het onderdeel en wordt vastgehouden in een openbare eigenschap (Model). Het kenmerk [SupplyParameterFromForm] geeft aan dat de waarde van de bijbehorende eigenschap moet worden opgegeven op basis van de formuliergegevens. Gegevens in het verzoek die overeenkomen met de naam van de eigenschap zijn aan de eigenschap gebonden.
• Het InputText onderdeel is een invoeronderdeel voor het bewerken van tekenreekswaarden. Het @bind-Value-instructiekenmerk verbindt de Model.Id-model eigenschap met de Value-eigenschap van het InputText-onderdeel.
• De Submit methode wordt geregistreerd als handler voor de @onsubmit callback. De handler wordt aangeroepen wanneer het formulier wordt verzonden door de gebruiker.

Belangrijk

Gebruik altijd het @formname-instructiekenmerk met een unieke formuliernaam.

Blazor de verwerking van paginanavigatie en formulieren verbetert door de aanvraag te onderscheppen om het antwoord op de bestaande DOM toe te passen, waarbij zoveel mogelijk van het gerenderde formulier behouden blijft. De verbetering voorkomt dat de pagina volledig moet worden geladen en biedt een veel soepelere gebruikerservaring, vergelijkbaar met een single-page applicatie (SPA), hoewel de component op de server wordt gerenderd. Zie ASP.NET Core Blazor routering en navigatievoor meer informatie.

Streaming rendering wordt ondersteund voor html-formulieren zonder opmaak.

Notitie

Documentatiekoppelingen naar .NET-referentiebron laden meestal de standaardbranch van de opslagplaats, die de huidige ontwikkeling vertegenwoordigt voor de volgende release van .NET. Als u een tag voor een specifieke release wilt selecteren, gebruikt u de Switch-vertakkingen of tags vervolgkeuzelijst. Zie Een versietag selecteren van ASP.NET Core-broncode (dotnet/AspNetCore.Docs #26205)voor meer informatie.

Het voorgaande voorbeeld bevat antivervalsingsondersteuning door een AntiforgeryToken onderdeel in het formulier op te geven. Ondersteuning voor antivervalsing wordt verder uitgelegd in de sectie Antiforgery-ondersteuning van dit artikel.

Als u een formulier wilt verzenden op basis van dom-gebeurtenissen van een ander element, bijvoorbeeld oninput of onblur, gebruikt u JavaScript om het formulier (submit (MDN-documentatie) in te dienen).

In plaats van gewone formulieren in Blazor apps te gebruiken, wordt een formulier meestal gedefinieerd met Blazoringebouwde formulierondersteuning met behulp van het EditForm-onderdeel van het framework. Het volgende Razor onderdeel demonstreert typische elementen, onderdelen en Razor code om een webformulier weer te geven met behulp van een EditForm onderdeel.

Starship1.razor:

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

In het voorgaande Starship1 onderdeel:

• Het EditForm-onderdeel wordt weergegeven waar het <EditForm>-element wordt weergegeven. Het formulier heeft een naam met de eigenschap FormName, waarmee het formulier uniek wordt geïdentificeerd in het Blazor framework.
• Het model wordt gemaakt in het @code-blok van het onderdeel en opgeslagen in een publieke eigenschap (Model). De eigenschap wordt toegewezen aan de parameter EditForm.Model. Het kenmerk [SupplyParameterFromForm] geeft aan dat de waarde van de bijbehorende eigenschap moet worden opgegeven op basis van de formuliergegevens. Gegevens in het verzoek die overeenkomen met de naam van de eigenschap, worden gekoppeld aan de eigenschap.
• Het onderdeel InputText is een invoeronderdeel voor het bewerken van tekenreekswaarden. Het @bind-Value directiefkenmerk koppelt de model eigenschap Model.Id aan de eigenschap Value van het onderdeel InputText.
• De methode Submit wordt geregistreerd als handler voor de OnSubmit callback. De handler wordt aangeroepen wanneer het formulier wordt verzonden door de gebruiker.

Belangrijk

Gebruik altijd de eigenschap FormName met een unieke formuliernaam.

Blazor verbetert de verwerking van paginanavigatie en formulieren voor EditForm onderdelen. Zie ASP.NET Core Blazor routering en navigatievoor meer informatie.

Streaming rendering wordt ondersteund voor EditForm.

Notitie

Documentatiekoppelingen naar .NET-referentiebron laden meestal de standaardbranch van de opslagplaats, die de huidige ontwikkeling vertegenwoordigt voor de volgende release van .NET. Als u een tag voor een specifieke release wilt selecteren, gebruikt u de Switch-vertakkingen of tags vervolgkeuzelijst. Zie Een versietag selecteren van ASP.NET Core-broncode (dotnet/AspNetCore.Docs #26205)voor meer informatie.

† Zie ASP.NET Core Blazor data bindingvoor meer informatie over eigenschapsbinding.

In het volgende voorbeeld wordt het voorgaande onderdeel gewijzigd om het formulier in het Starship2-onderdeel te maken:

• OnSubmit wordt vervangen door OnValidSubmit, die de toegewezen gebeurtenis-handler verwerkt als het formulier geldig is wanneer het door de gebruiker wordt ingediend.
• Er wordt een ValidationSummary onderdeel toegevoegd om validatieberichten weer te geven wanneer het formulier ongeldig is bij het verzenden van formulieren.
• De validatieondersteuning voor gegevensaantekeningen (DataAnnotationsValidator component†) wordt gekoppeld aan validatieondersteuning met behulp van gegevensaantekeningen:
  • Als het <input> formulierveld leeg blijft wanneer de knop Submit is geselecteerd, wordt er een fout weergegeven in het validatieoverzicht (ValidationSummary component‡) ("The Id field is required.") en wordt Submit niet aangeroepen.
  • Als het <input> formulierveld meer dan tien tekens bevat wanneer de knop Submit is geselecteerd, wordt er een fout weergegeven in het validatieoverzicht ("Id is too long."). Submit wordt niet aangeroepen.
  • Als het <input> formulierveld een geldige waarde bevat wanneer de knop Submit is geselecteerd, wordt Submit aangeroepen.

†De DataAnnotationsValidator-component wordt behandeld in de sectie van Validator-component. ‡Het ValidationSummary onderdeel wordt behandeld in de sectie Validatieoverzicht en Validatiebericht.

Starship2.razor:

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

Verwerken van formulierindiening

De EditForm bevat de volgende callbacks voor het verwerken van formulierinzending:

• Gebruik OnValidSubmit om een gebeurtenishandler toe te wijzen die moet worden uitgevoerd wanneer een formulier met geldige velden wordt verzonden.
• Gebruik OnInvalidSubmit om een gebeurtenishandler toe te wijzen die moet worden uitgevoerd wanneer een formulier met ongeldige velden wordt verzonden.
• Gebruik OnSubmit om een gebeurtenishandler toe te wijzen om te worden uitgevoerd, ongeacht de validatiestatus van de formuliervelden. Het formulier wordt gevalideerd door EditContext.Validate aan te roepen in de gebeurtenis-handlermethode. Als Validatetrueretourneert, is het formulier geldig.

Een formulier of veld wissen

Stel een formulier opnieuw in door het model terug te zetten naar de standaardstatus, wat binnen of buiten de markering van een EditFormkan worden uitgevoerd.

<button @onclick="ClearForm">Clear form</button>

...

private void ClearForm() => Model = new();

U kunt ook een expliciete Razor-expressie gebruiken:

<button @onclick="@(() => Model = new())">Clear form</button>

Stel een veld opnieuw in door de modelwaarde terug te zetten naar de standaardstatus:

<button @onclick="ResetId">Reset Identifier</button>

...

private void ResetId() => Model!.Id = string.Empty;

U kunt ook een expliciete Razor-expressie gebruiken:

<button @onclick="@(() => Model!.Id = string.Empty)">Reset Identifier</button>

Het is niet nodig om StateHasChanged aan te roepen in de voorgaande voorbeelden, omdat StateHasChanged automatisch wordt aangeroepen door het Blazor framework om het onderdeel opnieuw te activeren nadat een gebeurtenis-handler is aangeroepen. Als een gebeurtenis-handler niet wordt gebruikt om de methoden aan te roepen die een formulier of veld wissen, moet de code van de ontwikkelaar StateHasChanged aanroepen om het onderdeel opnieuw te genereren.

Ondersteuning voor antivervalsing

Antivervalsingsservices worden automatisch toegevoegd aan Blazor apps wanneer AddRazorComponents wordt aangeroepen in het Program-bestand.

De app maakt gebruik van Antiforgery Middleware door UseAntiforgery aan te roepen in de aanvraagverwerkingspijplijn in het Program-bestand. UseAntiforgery wordt aangeroepen na het aanroepen van UseRouting. Als er oproepen naar UseRouting en UseEndpointszijn, moet de oproep naar UseAntiforgery ertussen gaan. Een oproep naar UseAntiforgery moet worden geplaatst na oproepen naar UseAuthentication en UseAuthorization.

Het AntiforgeryToken onderdeel geeft een antiforgery-token weer als een verborgen veld en het kenmerk [RequireAntiforgeryToken] maakt beveiliging tegen vervalsing mogelijk. Als een antivervalsingscontrole mislukt, wordt er een 400 - Bad Request antwoord gegenereerd en wordt het formulier niet verwerkt.

Voor formulieren op basis van EditFormworden het AntiforgeryToken-onderdeel en het kenmerk [RequireAntiforgeryToken] automatisch toegevoegd om beveiliging tegen vervalsing te bieden.

Voor formulieren op basis van het HTML-<form>-element voegt u het AntiforgeryToken onderdeel handmatig toe aan het formulier:

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

Waarschuwing

Voor formulieren op basis van EditForm of het HTML-<form>-element kan beveiliging tegen vervalsing worden uitgeschakeld door required: false door te geven aan het kenmerk [RequireAntiforgeryToken]. In het volgende voorbeeld wordt antivervalsing uitgeschakeld en wordt niet aanbevolen voor openbare apps:

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

Zie ASP.NET Core Blazor verificatie- en autorisatie-voor meer informatie.

Overpostingaanvallen beperken

Statisch gegenereerde formulieren aan de serverzijde, zoals formulieren die doorgaans worden gebruikt in onderdelen die records maken en bewerken in een database met een formuliermodel, kunnen kwetsbaar zijn voor een overposting aanval, ook wel een massatoewijzing aanval genoemd. Er treedt een overpostingsaanval op wanneer een kwaadwillende gebruiker een HTML-formulierPOST uitgeeft aan de server die gegevens verwerkt voor eigenschappen die geen deel uitmaken van het gerenderde formulier en die de ontwikkelaar niet toestaat dat gebruikers deze kunnen wijzigen. De term 'overposting' betekent letterlijk dat de kwaadwillende gebruiker met het formulier overheeft gepost.

Overposting is geen probleem wanneer het model geen beperkte eigenschappen bevat voor het maken en bijwerken van bewerkingen. Het is echter belangrijk om rekening te houden met overposting bij het werken met statische SSR-Blazor formulieren die u onderhoudt.

Om overposting te beperken, raden we u aan een afzonderlijk weergavemodel/gegevensoverdrachtobject (DTO) te gebruiken voor het formulier en de database met bewerkingen voor maken (invoegen) en bijwerken. Wanneer het formulier wordt verzonden, worden alleen eigenschappen van het weergavemodel/DTO gebruikt door het onderdeel en C#-code om de database te wijzigen. Eventuele extra gegevens die door een kwaadwillende gebruiker worden opgenomen, worden genegeerd, zodat de kwaadwillende gebruiker wordt verhinderd een overposting-aanval uit te voeren.

Verbeterde verwerking van formulieren

Navigatie voor POST-aanvragen voor formulieren verbeteren met de parameter Enhance voor EditForm formulieren of het kenmerk data-enhance voor HTML-formulieren (<form>):

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

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

❌ Niet ondersteund: U kunt geen uitgebreide navigatie instellen op het bovenliggende element van een formulier om verbeterde formulierafhandeling mogelijk te maken.

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

Verbeterde formulierberichten werken alleen met Blazor-eindpunten. Het plaatsen van een verbeterd formulier op een niet-Blazor eindpunt resulteert in een fout.

Verbeterde formulierafhandeling uitschakelen:

• Voor een EditFormverwijdert u de parameter Enhance uit het formulierelement (of stelt u deze in op false: Enhance="false").
• Voor een HTML-<form>verwijdert u het kenmerk data-enhance uit het formulierelement (of stelt u het in op false: data-enhance="false").

Blazor's verbeterde navigatie en formulierenverwerking kunnen dynamische wijzigingen in de DOM ongedaan maken als de bijgewerkte inhoud geen deel uitmaakt van de server-rendering. Als u de inhoud van een element wilt behouden, gebruikt u het kenmerk data-permanent.

In het volgende voorbeeld wordt de inhoud van het element <div> dynamisch bijgewerkt door een script wanneer de pagina wordt geladen:

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

Zie ASP.NET Core Blazor startupom verbeterde navigatie- en formulierafhandeling wereldwijd uit te schakelen.

Zie ASP.NET Core Blazor routerings- en navigatie-voor hulp bij het gebruik van de enhancedload gebeurtenis om te luisteren naar verbeterde pagina-updates.

Voorbeelden

Voorbeelden nemen geen verbeterde formulierafhandeling voor POST-aanvragen in gebruik, maar alle voorbeelden kunnen worden bijgewerkt om de verbeterde functies te gebruiken door de richtlijnen in de sectie Uitgebreide formulierafhandeling te volgen.

Als u wilt laten zien hoe formulieren werken met gegevensaantekeningen validatie, zijn voorbeeldonderdelen afhankelijk van System.ComponentModel.DataAnnotations API. Als u een extra regel code wilt vermijden in onderdelen die gebruikmaken van gegevensaantekeningen, maakt u de naamruimte beschikbaar in de onderdelen van de app met het importbestand (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Formuliervoorbeelden verwijzen naar aspecten van het Star Trek universum. Star Trek is een copyright ©1966-2023 van CBS Studios en Paramount.

Validatie aan clientzijde vereist een circuit

In Blazor Web Appis voor validatie aan de clientzijde een actief BlazorSignalR circuit vereist. Validatie aan de clientzijde is niet beschikbaar voor formulieren in onderdelen die statische rendering op de server hebben aangenomen (statische SSR). Formulieren die statische SSR aannemen, worden gevalideerd op de server nadat het formulier is verzonden.

Niet-ondersteunde validatiefuncties

Alle ingebouwde validators voor gegevensannotatie van worden ondersteund in Blazor, met uitzondering van het validatiekenmerk [Remote].

jQuery-validatie wordt niet ondersteund in Razor onderdelen. We raden een van de volgende methoden aan:

• Volg de richtlijnen in ASP.NET Core Blazor formuliervalidatie voor:
  • Validatie aan de serverzijde in een Blazor Web App die een interactieve weergavemodus gebruikt.
  • Validatie aan de clientzijde in een zelfstandige Blazor Web Assembly-app.
• Systeemeigen HTML-validatiekenmerken gebruiken (zie MDN-documentatie (Client-Side Form Validation)).
• Een JavaScript-bibliotheek van derden valideren.

Voor statisch gerenderde formulieren op de server wordt een nieuw mechanisme voor validatie aan de clientzijde in overweging genomen voor .NET 10 eind 2025. Zie Server gegenereerde formulieren maken met clientvalidatie met behulp van Blazor zonder circuit (dotnet/aspnetcore #51040)voor meer informatie.

Aanvullende informatiebronnen

• ASP.NET Core Blazor-bestand uploaden
• Blazor voorbeelden GitHub-repository (dotnet/blazor-samples) (hoe te downloaden)
• ASP.NET Core GitHub-opslagplaats (dotnet/aspnetcore) vormt test-assets