ASP.NET Core Blazor formulierenvalidatie

Notitie

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 10-versie van dit artikel voor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie het .NET en .NET Core Support Policy voor meer informatie. Zie de .NET 10-versie van dit artikel voor de huidige release.

In dit artikel wordt uitgelegd hoe u gebruikersinvoer in Blazor formulieren valideert.

Voor de meeste formulieren is de eenvoudigste en aanbevolen methode het toevoegen van validatiekenmerken voor gegevensaantekeningen aan het model en het plaatsen van een DataAnnotationsValidator onderdeel in het EditForm. Blazor biedt ook ondersteuning voor aangepaste validatie via het formulier EditContext, rechtstreeks in het formulieronderdeel of in een herbruikbaar validatoronderdeel.

Verwante artikelen bieden meer details:

Valideren met gegevensaantekeningen

Het volgende model gebruikt RequiredAttribute en RangeAttribute:

Starship.cs:

using System.ComponentModel.DataAnnotations;

public class Starship
{
    [Required]
    public string? Identifier { get; set; }

    [Range(1, 10, ErrorMessage = "Accommodation must be between 1 and 10.")]
    public int MaximumAccommodation { get; set; }
}

Voeg het model toe aan een EditForm, neem DataAnnotationsValidator op en geef fouten weer met ValidationMessage<TValue> of ValidationSummary. De OnValidSubmit callback wordt alleen aangeroepen wanneer de validatie slaagt:

<EditForm Model="Model" OnValidSubmit="Submit">
    <DataAnnotationsValidator />
    <ValidationSummary />

    <p>
        <label>
            Identifier:
            <InputText @bind-Value="Model.Identifier" />
        </label>
        <ValidationMessage For="() => Model.Identifier" />
    </p>

    <p>
        <label>
            Maximum accommodation:
            <InputNumber @bind-Value="Model.MaximumAccommodation" />
        </label>
        <ValidationMessage For="() => Model.MaximumAccommodation" />
    </p>

    <button type="submit">Submit</button>
</EditForm>

@code {
    private Starship Model { get; } = new Starship();

    private void Submit()
    {
        // Process the valid form.
    }
}

Voor een statische SSR-formulierpost wijst u een unieke FormName toe en ontvangt u het verzonden model met [SupplyParameterFromForm]:

<EditForm Model="Model" FormName="starship" OnValidSubmit="Submit">
    ...
</EditForm>

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

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

Zie ASP.NET Core Blazor overzicht van formulieren en ASP.NET Core Blazor formulierbinding voor meer informatie over formulierinzending en modelbinding in verschillende rendermodi.

Zonder een DataAnnotationsValidator onderdeel nemen validatiekenmerken in het model niet deel aan de validatie van het formulier.

Wanneer de validatie wordt uitgevoerd

Blazor voert veldvalidatie en volledige formuliervalidatie uit:

  • Veldvalidatie wordt uitgevoerd nadat een veld is gewijzigd. In een interactief formulier gebeurt dit in .NET terwijl de gebruiker het formulier bewerkt.
  • Validatie van het volledige formulier vindt normaal plaats wanneer EditForm de verzending afhandelt via OnValidSubmit of OnInvalidSubmit. Een OnSubmit handler heeft de controle over de validatie, zoals beschreven in het verzenden van besturingsformulieren.

Een statisch SSR-formulier kan live browserfeedback geven met ASP.NET Core Blazor formuliervalidatie aan de clientzijde in statische SSR. Het formulier wordt opnieuw gezaghebbend gevalideerd op de server wanneer het wordt gepost.

Een statisch SSR-formulier wordt gevalideerd op de server wanneer deze wordt gepost en biedt geen live veldvalidatie tussen aanvragen.

Validatieresultaten waarmee een lid wordt geïdentificeerd, zijn gekoppeld aan dat veld. Resultaten zonder lidnaam zijn gekoppeld aan het model en worden weergegeven in een validatieoverzicht in plaats van het onderdeel van ValidationMessage een veld.

Validatie van gegevensaantekeningen configureren

DataAnnotationsValidator Schakelt altijd validatie van DataAnnotations in voor het formulier. Als u de uitgebreide validatiemogelijkheden van het Microsoft.Extensions.Validation pakket wilt gebruiken, roept u de AddValidation extensiemethode in het Program bestand aan:

builder.Services.AddValidation();

De AddValidation aanroep registreert de validatieservices van het pakket en activeert een brongenerator waarmee validatiemetagegevens voor gedetecteerde modeltypen worden gemaakt. Het beschikbare gedrag is afhankelijk van of die metagegevens het model van het formulier bevatten:

Configuration Gedrag
Gegenereerde metagegevens zijn beschikbaar Valideert geneste objecten en verzamelingen en ondersteunt berichtlokalisatie.
Gegenereerde metagegevens zijn niet beschikbaar Hiermee worden eigenschappen op het hoogste niveau gevalideerd, maar worden geneste objecten of verzamelingen niet gevalideerd en wordt de Microsoft.Extensions.Validation pijplijn voor berichtlokalisatie niet gebruikt.
Configuration Gedrag
Gegenereerde metagegevens zijn beschikbaar Valideert geneste objecten en verzamelingen.
Gegenereerde metagegevens zijn niet beschikbaar Valideert alleen eigenschappen op het hoogste niveau.

De ValidatableTypeAttribute api's en SkipValidationAttribute API's zijn experimenteel in .NET 10. Zie Validatie in ASP.NET Core voor meer informatie en beschikbare tijdelijke oplossingen.

Wanneer u Microsoft.Extensions.Validation gebruikt, declareer modeltypen in C#-bestanden (.cs) in plaats van in componentbestanden (.razor) Razor. De brongenerator maakt validatiemetagegevens van de C#-bron en kan geen modeltypen bevatten die zijn gedeclareerd in Razor onderdelen.

Zie Validatie in ASP.NET Core voor configuratievereisten, validatievolgorde, aangepaste regels, geneste objectgrafieken en gegenereerde metagegevens.

Geneste objectgrafieken valideren

In .NET 9 of eerder valideert u modeleigenschappen op het hoogste niveau, DataAnnotationsValidator maar valideert u geen recursieve verzamelings- of complexe eigenschappen. Gebruik [ValidateComplexType] en Microsoft.AspNetCore.Components.DataAnnotations.Validation uit het experimentele ObjectGraphDataAnnotationsValidator voor recursieve validatie:

<EditForm Model="Model" OnValidSubmit="Submit">
    <ObjectGraphDataAnnotationsValidator />
    ...
</EditForm>

public class Starship
{
    [ValidateComplexType]
    public ShipDescription Description { get; set; } =
        new ShipDescription();
}

Het pakket blijft experimenteel in deze frameworkversies.

kenmerk [CompareProperty]

Gebruik voor .NET 5 of eerder het experimentele pakket ComparePropertyAttribute in plaats van CompareAttribute. ComparePropertyAttribute koppelt het validatieresultaat consistent aan het veld tijdens veld- en volledige validatie.

Aangepaste regels schrijven op basis van een model

Wanneer ingebouwde kenmerken geen regel kunnen uitdrukken, gebruikt u een aangepaste ValidationAttribute of IValidatableObject. Zie Validatie in ASP.NET Core voor gedetailleerde richtlijnen.

Aangepaste regels schrijven op basis van een model

Wanneer ingebouwde kenmerken geen regel kunnen uitdrukken, gebruikt u een aangepast validatiekenmerk of implementeert u IValidatableObject. Beide gaan via DataAnnotationsValidator.

Wanneer u een ValidationResult vanuit een aangepast kenmerk retourneert, moet u de naam van het gevalideerde lid opnemen, zodat het resultaat kan worden weergegeven in het ValidationMessage-onderdeel van dat veld.

Aangepaste attributen kunnen geregistreerde services oplossen via GetService.

Validatie toevoegen via EditContext

EditForm maakt automatisch een EditContext aan wanneer de parameter Model wordt toegewezen. Als u validatie-API's rechtstreeks wilt gebruiken, maakt u de context zelf en wijst u deze toe aan de EditContext parameter van EditForm. Wijs niet zowel Model als EditContext aan hetzelfde formulier toe.

Bij aangepaste validatie wordt vaak gebruikgemaakt van:

Met het volgende interactieve formulierpatroon wordt naast validatie van gegevensaantekeningen een bedrijfsregel op formulierniveau toegevoegd en wordt de regel opnieuw gecontroleerd wanneer een van de relevante velden wordt gewijzigd:

@implements IDisposable

<EditForm EditContext="editContext" OnValidSubmit="Submit">
    <DataAnnotationsValidator />
    <ValidationSummary />

    ...
</EditForm>

@code {
    private Starship Model { get; } = new Starship();
    private EditContext editContext = default!;
    private ValidationMessageStore messages = default!;

    protected override void OnInitialized()
    {
        editContext = new EditContext(Model);
        messages = new ValidationMessageStore(editContext);
        editContext.OnValidationRequested += ValidateBusinessRules;
        editContext.OnFieldChanged += ValidateChangedField;
    }

    private void ValidateBusinessRules(
        object? sender, ValidationRequestedEventArgs e)
    {
        messages.Clear();
        ValidateIdentifier();
        editContext.NotifyValidationStateChanged();
    }

    private void ValidateChangedField(
        object? sender, FieldChangedEventArgs e)
    {
        if (e.FieldIdentifier.FieldName != nameof(Starship.Identifier) &&
            e.FieldIdentifier.FieldName != nameof(Starship.MaximumAccommodation))
        {
            return;
        }

        messages.Clear(
            editContext.Field(nameof(Starship.Identifier)));
        ValidateIdentifier();
        editContext.NotifyValidationStateChanged();
    }

    private void ValidateIdentifier()
    {
        if (Model.MaximumAccommodation == 1 &&
            string.IsNullOrWhiteSpace(Model.Identifier))
        {
            messages.Add(
                editContext.Field(nameof(Starship.Identifier)),
                "An identifier is required for a single-occupant ship.");
        }
    }

    private void Submit()
    {
        // Process the valid form.
    }

    public void Dispose()
    {
        editContext.OnValidationRequested -= ValidateBusinessRules;
        editContext.OnFieldChanged -= ValidateChangedField;
    }
}

Een OnFieldChanged handler ontvangt het gewijzigde veld in e.FieldIdentifier. Verwijder of vervang de betreffende berichten en roep NotifyValidationStateChanged aan, zoals in het voorgaande voorbeeld wordt gedemonstreerd.

Statische SSR biedt geen live .NET veldvalidatie tussen aanvragen.

Voor asynchrone volledige formuliervalidatie roept u een aanroep e.AddAsyncValidator van een OnValidationRequested handler aan. Voor asynchrone veldvalidatie in een interactief formulier roept u een aanroep EditContext.RegisterAsyncFieldValidator van een OnFieldChanged handler aan. Een nieuwe asynchrone validatie voor hetzelfde veld vervangt en annuleert de vorige.

Zie Validatie in ASP.NET Core voor asynchrone validatiekenmerken op basis van modellen. Zie ASP.NET Core Blazor geavanceerde formuliervalidatie voor een volledig herbruikbaar validatoronderdeel.

Zie ASP.NET Core Blazor geavanceerde formuliervalidatie voor een herbruikbare implementatie waarin gebeurtenisabonnementen en de berichtenopslag worden ingekapseld.

Validatieberichten weergeven

Gebruiken ValidationMessage<TValue> om berichten weer te geven die zijn gekoppeld aan één veld:

<ValidationMessage For="() => Model.Identifier" />

De For-expressie identificeert het veld aan de hand van de modelinstantie en de eigenschap. Blazor vertegenwoordigt deze identiteit met een FieldIdentifier, zodat eigenschappen met dezelfde naam op verschillende modelexemplaren worden behandeld als verschillende velden. Als u een expressie gebruikt in plaats van een tekenreeks, kunnen refactoringshulpmiddelen ook de verwijzing naar de eigenschap bijwerken.

Gebruik ValidationSummary deze indeling om berichten voor het formulier weer te geven:

<ValidationSummary />

Wijs de parameter van Model de samenvatting toe om deze te beperken tot berichten die zijn gekoppeld aan een bepaald model:

<ValidationSummary Model="Model" />

Als u de huidige berichten in code wilt controleren, roept u het volgende GetValidationMessagesaan:

var allMessages = editContext.GetValidationMessages();
var fieldMessages = editContext.GetValidationMessages(
    editContext.Field(nameof(Starship.Identifier)));

Deze methoden lezen de huidige validatiestatus. Ze initiëren geen validatie.

Weergave van validatie aanpassen

Blazor past CSS-klassen toe die de veld- en berichtstatus vertegenwoordigen:

Element Klassen
Input valid of invalid, plus modified nadat de gebruiker het veld heeft bewerkt
Validatiebericht validation-message
Validatieoverzicht validation-summary-errors of validation-summary-valid

Invoervelden met asynchrone veldvalidatie gebruiken pending of faulted, optioneel met modified, in plaats van valid of invalid wanneer de overeenkomstige status van toepassing is.

De Blazor projectsjablonen bevatten stijlen voor de algemene geldige en ongeldige klassen. Voeg indien nodig stijlen toe voor andere klassen. ValidationMessage en ValidationSummary ook willekeurige HTML-kenmerken accepteren. Als u een class kenmerk opgeeft, wordt de standaardklasse van het onderdeel vervangen.

Als u de klassen wilt wijzigen die op invoercomponenten worden toegepast, leid deze dan af van FieldCssClassProvider.

using Microsoft.AspNetCore.Components.Forms;

public sealed class BootstrapFieldCssClassProvider : FieldCssClassProvider
{
    public override string GetFieldCssClass(
        EditContext editContext,
        in FieldIdentifier fieldIdentifier)
    {
        if (!editContext.IsModified(fieldIdentifier))
        {
            return string.Empty;
        }

        return editContext.IsValid(fieldIdentifier)
            ? "is-valid"
            : "is-invalid";
    }
}

using System.Linq;
using Microsoft.AspNetCore.Components.Forms;

public sealed class BootstrapFieldCssClassProvider : FieldCssClassProvider
{
    public override string GetFieldCssClass(
        EditContext editContext,
        in FieldIdentifier fieldIdentifier)
    {
        if (!editContext.IsModified(fieldIdentifier))
        {
            return string.Empty;
        }

        return editContext.GetValidationMessages(fieldIdentifier).Any()
            ? "is-invalid"
            : "is-valid";
    }
}

Een aangepaste FieldCssClassProvider waarde bepaalt de volledige klassewaarde voor elk veld. Als in het formulier asynchrone veldvalidatie wordt gebruikt, moet u IsValidationPending(fieldIdentifier) en IsValidationFaulted(fieldIdentifier) in de provider afhandelen wanneer klassen voor in behandeling of foutstatus vereist zijn.

Wijs de provider toe aan de EditContext van het formulier:

editContext.SetFieldCssClassProvider(
    new BootstrapFieldCssClassProvider());

Voor aangepaste invoermarkeringen roept FieldCssClass u aan om de klasse te verkrijgen die is geselecteerd door de huidige provider.

Wanneer aan een EditForm een model wordt toegewezen, ontvangt de onderliggende inhoud de gegenereerde EditContext. Leg de context vast via de Context parameter en roep FieldCssClass om de klassen van het veld toe te passen op omringende markeringen:

<EditForm Model="Model" Context="editContext">
    <DataAnnotationsValidator />

    <div class="@editContext.FieldCssClass(
        () => Model.Identifier)">
        <InputText @bind-Value="Model.Identifier" />
        <ValidationMessage For="() => Model.Identifier" />
    </div>
</EditForm>

Reageren op validatiestatus

EditContext maakt de huidige validatiestatus beschikbaar zonder validatie te starten.

  • Gebruik IsModified(field) of IsModified() om te bepalen of een veld of een veld in het formulier is gewijzigd.
  • Gebruik GetValidationMessages(field) of GetValidationMessages() controleer huidige veld- of formulierberichten.

Gebruik IsValid(field) dit om te bepalen of een veld momenteel validatieberichten bevat.

Voor een veld kan het ontbreken van berichten worden nagegaan met !editContext.GetValidationMessages(field).Any().

In het volgende voorbeeld wordt pas een aangepaste gebruikersinterface weergegeven nadat een veld is gewijzigd en ongeldig is:

@{
    var identifier = editContext.Field(nameof(Starship.Identifier));
}

@if (editContext.IsModified(identifier) &&
    !editContext.IsValid(identifier))
{
    <p>Correct the identifier before continuing.</p>
}

@{
    var identifier = editContext.Field(nameof(Starship.Identifier));
}

@if (editContext.IsModified(identifier) &&
    editContext.GetValidationMessages(identifier).Any())
{
    <p>Correct the identifier before continuing.</p>
}

Invoeronderdelen ValidationMessageen ValidationSummary zichzelf bijwerken wanneer de validatiestatus wordt gewijzigd. Een onderdeel dat andere gebruikersinterface voor voorwaardelijke validatie weergeeft, moet zich abonneren op OnValidationStateChanged en aanroepen StateHasChanged:

private void HandleValidationStateChanged(
    object? sender, ValidationStateChangedEventArgs e) =>
    _ = InvokeAsync(StateHasChanged);

Schrijf u uit van OnValidationStateChanged wanneer de component wordt verwijderd.

Gebruik IsValidationPending(field) en IsValidationFaulted(field) voor asynchrone veldvalidatie. De parameterloze methoden beschrijven passes op formulierniveau ValidateAsync en voegen niet de status van elk veld samen.

Deze statussen omvatten ook asynchroon werk dat wordt uitgevoerd door DataAnnotationsValidator. Een AsyncValidationAttribute toegepast op een eigenschap gebruikt veldstatus tijdens veldvalidatie, inclusief de standaard pending - en faulted CSS-klassen. Tijdens ValidateAsync dragen asynchrone attributen en IAsyncValidatableObject bij aan de status op formulierniveau die door de parameterloze methoden wordt gerapporteerd.

Voor indicatoren die in behandeling zijn voor live is een interactieve weergavemodus vereist. Tijdens het posten van een statisch SSR-formulier wordt de server-sidevalidatie voltooid voordat de respons wordt gerenderd.

Indienen van formulieren beheren

EditForm biedt drie callbacks voor het indienen:

Terugroepfunctie Gedrag
OnValidSubmit Wordt uitgevoerd nadat de automatische validatie is geslaagd.
OnInvalidSubmit Wordt uitgevoerd nadat de automatische validatie is mislukt.
OnSubmit Geeft de handler controle over validatie en indiening.

OnValidSubmit en OnInvalidSubmit kan samen worden gebruikt. Combineer OnSubmit niet met geen van beide.

EditForm gebruikt ValidateAsync voordat u aanroept OnValidSubmit of OnInvalidSubmit, dus wacht deze op synchrone en asynchrone validators. Bij het verwerken van OnSubmit, roept u ValidateAsync aan voordat het formulier wordt verwerkt:

<EditForm EditContext="editContext" OnSubmit="HandleSubmit">
    ...
</EditForm>

@code {
    private async Task HandleSubmit(EditContext editContext)
    {
        if (await editContext.ValidateAsync())
        {
            await SaveAsync();
        }
    }
}

De synchrone Validate methode is verouderd in .NET 11. Er wordt niet gewacht op asynchrone validatie en er wordt een fout gegenereerd als een handler asynchroon werk probeert te registreren.

Voor interactieve formulieren kan de status 'in behandeling' op formulierniveau worden gebruikt om het verzenden uit te schakelen terwijl ValidateAsync wordt uitgevoerd:

<button type="submit" disabled="@editContext.IsValidationPending()">
    Save
</button>

Bij het verwerken van OnSubmit, roept u Validate aan voordat het formulier wordt verwerkt:

<EditForm EditContext="editContext" OnSubmit="HandleSubmit">
    ...
</EditForm>

@code {
    private void HandleSubmit(EditContext editContext)
    {
        if (editContext.Validate())
        {
            Save();
        }
    }
}

Verwante onderwerpen

  • Laatst bijgewerkt om