ASP.NET Core Blazor formulärverifiering

Observera

Det här är inte den senaste versionen av den här artikeln. Den aktuella versionen finns i .NET 10 versionen av den här artikeln.

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i .NET och .NET Core Support Policy. Den aktuella versionen finns i .NET 10 versionen av den här artikeln.

Den här artikeln beskriver hur du verifierar användarindata i Blazor formulär.

För de flesta formulär är den enklaste och rekommenderade metoden att lägga till valideringsattribut för dataanteckningar i modellen och placera en DataAnnotationsValidator komponent i EditForm. Blazor stöder också anpassad validering genom formulärets EditContext, antingen direkt i formulärkomponenten eller i en återanvändbar valideringskomponent.

Relaterade artiklar innehåller mer information:

Verifiera med dataanteckningar

Följande modell använder RequiredAttribute och 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; }
}

Lägg till modellen i en EditForm, inkludera DataAnnotationsValidator och visa fel med ValidationMessage<TValue> eller ValidationSummary. Återanropet OnValidSubmit anropas endast när valideringen lyckas:

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

För en postning från ett statiskt SSR-formulär tilldelar du ett unikt FormName och tar emot den postade modellen med [SupplyParameterFromForm]:

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

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

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

Mer information om formuläröverföring och modellbindning mellan återgivningslägen finns i översikten över ASP.NET Core Blazor formulär och ASP.NET Core Blazor formulärbindning.

Utan en DataAnnotationsValidator komponent deltar inte valideringsattribut i modellen i formulärets validering.

När valideringen körs

Blazor utför fältverifiering och validering av fullständigt formulär:

  • Fältverifiering körs efter att ett fält har ändrats. I ett interaktivt formulär sker detta i .NET medan användaren redigerar formuläret.
  • Fullständig validering körs normalt när EditForm hanterar sändning via OnValidSubmit eller OnInvalidSubmit. En OnSubmit hanterare tar kontroll över valideringen enligt beskrivningen i Skicka kontrollformulär.

Ett statiskt SSR-formulär kan ge direkt återkoppling i webbläsaren med ASP.NET Core Blazor formulärvalidering på klientsidan i statisk SSR. Formuläret verifieras igen auktoritativt på servern när det publiceras.

Ett statiskt SSR-formulär verifieras på servern när det publiceras och tillhandahåller inte validering av livefält mellan begäranden.

Valideringsresultat som identifierar en medlem är associerade med det fältet. Resultat utan medlemsnamn är associerade med modellen och visas i en valideringssammanfattning i stället för ett fälts ValidationMessage komponent.

Konfigurera validering av dataanteckningar

DataAnnotationsValidator aktiverar alltid DataAnnotations-validering för formuläret. Om du vill använda de utökade valideringsfunktionerna som tillhandahålls av Microsoft.Extensions.Validation paketet anropar AddValidation du tilläggsmetoden i Program filen:

builder.Services.AddValidation();

Anropet AddValidation registrerar paketets valideringstjänster och aktiverar en källgenerator som skapar valideringsmetadata för identifierade modelltyper. Det tillgängliga beteendet beror på om dessa metadata innehåller formulärets modell:

Configuration Behavior
Genererade metadata är tillgängliga Validerar kapslade objekt och samlingar och stöder meddelandelokalisering.
Genererade metadata är inte tillgängliga Validerar egenskaper på den översta nivån, men validerar inte kapslade objekt eller samlingar och använder inte pipelinen Microsoft.Extensions.Validation för meddelandelokalisering.
Configuration Behavior
Genererade metadata är tillgängliga Validerar kapslade objekt och samlingar.
Genererade metadata är inte tillgängliga Validerar endast egenskaper på den översta nivån.

ValidatableTypeAttribute API:erna och SkipValidationAttribute är experimentella i .NET 10. Mer information och tillgängliga lösningar finns i Validering i ASP.NET Core.

När du använder Microsoft.Extensions.Validationdeklarerar du modelltyper i C#-filer (.cs) i stället Razor för komponentfiler (.razor). Källgeneratorn skapar valideringsmetadata från C#-källan och kan inte inkludera modelltyper som deklarerats i Razor komponenter.

Konfigurationskrav, valideringsordning, anpassade regler, kapslade objektdiagram och genererade metadata finns i Validering i ASP.NET Core.

Verifiera kapslade objektdiagram

I .NET 9 eller tidigare validerar du modellegenskaper på toppnivå men DataAnnotationsValidator validerar inte rekursivt egenskaper för samling eller komplex typ. För rekursiv validering använder du ObjectGraphDataAnnotationsValidator och [ValidateComplexType] från det experimentella Microsoft.AspNetCore.Components.DataAnnotations.Validation-paketet:

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

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

Paketet är fortfarande experimentellt i dessa ramverksversioner.

[CompareProperty] attribut

För .NET 5 eller tidigare använder du det experimentella paketets ComparePropertyAttribute i stället för CompareAttribute. ComparePropertyAttribute associerar valideringsresultatet med fältet konsekvent under fält- och fullständig formulärvalidering.

Skriva modellbaserade anpassade regler

När inbyggda attribut inte kan uttrycka en regel använder du en anpassad ValidationAttribute eller IValidatableObject. Detaljerad vägledning finns i Validering i ASP.NET Core.

Skriva modellbaserade anpassade regler

När inbyggda attribut inte kan uttrycka en regel använder du ett anpassat valideringsattribut eller implementerar IValidatableObject. Båda körs via DataAnnotationsValidator.

När du returnerar ett ValidationResult från ett anpassat attribut ska du inkludera det verifierade medlemsnamnet så att resultatet kan visas i fältets ValidationMessage komponent.

Anpassade attribut kan få åtkomst till registrerade tjänster genom GetService.

Lägga till validering via EditContext

EditForm skapar en EditContext automatiskt när dess Model parameter tilldelas. Om du vill använda validerings-API:er direkt skapar du kontexten själv och tilldelar den till parametern EditContextEditForm. Tilldela inte både Model och EditContext till samma formulär.

Anpassad validering används ofta:

Följande interaktiva formulärmönster lägger till en affärsregel på formulärnivå tillsammans med validering av dataanteckningar och avmarkerar regeln igen när något av de relevanta fälten ändras:

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

En OnFieldChanged hanterare tar emot det ändrade fältet i e.FieldIdentifier. Rensa eller ersätt de berörda meddelandena och anropa NotifyValidationStateChanged, vilket visas i föregående exempel.

Statisk SSR tillhandahåller inte live-.NET fältverifiering mellan begäranden.

För asynkron validering av hela formuläret, anropa e.AddAsyncValidator i en OnValidationRequested-hanterare. För asynkron fältvalidering i ett interaktivt formulär anropar du EditContext.RegisterAsyncFieldValidator i en OnFieldChanged-hanterare. En ny asynkron validering för samma fält ersätter och avbryter den föregående.

För modellbaserade asynkrona valideringsattribut, se Validering i ASP.NET Core. En fullständig återanvändbar valideringskomponent finns i ASP.NET Core Blazor avancerad formulärverifiering.

En återanvändbar implementering som kapslar in händelseprenumerationer och dess meddelandearkiv finns i ASP.NET Core Blazor avancerad formulärverifiering.

Visa valideringsmeddelanden

Använd ValidationMessage<TValue> för att visa meddelanden som är associerade med ett fält:

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

Uttrycket For identifierar fältet efter dess modellinstans och egenskap. Blazor representerar den här identiteten med en FieldIdentifier, så egenskaper med samma namn på olika modellinstanser behandlas som olika fält. Om du använder ett uttryck i stället för en sträng kan även refaktoriseringsverktyg uppdatera egenskapsreferensen.

Använd ValidationSummary för att visa meddelanden för formuläret:

<ValidationSummary />

Tilldela sammanfattningens Model parameter för att begränsa den till meddelanden som är associerade med en viss modell:

<ValidationSummary Model="Model" />

Om du vill granska aktuella meddelanden i kod anropar du GetValidationMessages:

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

Dessa metoder läser det aktuella valideringstillståndet. De initierar inte validering.

Anpassa utseende för validering

Blazor tillämpar CSS-klasser som representerar fält- och meddelandetillstånd:

Element Klasserna
Input valid eller invalid, plus modified när användaren har redigerat fältet
Valideringsmeddelande validation-message
Valideringssammanfattning validation-summary-errors eller validation-summary-valid

Indatafält med asynkron fältvalidering använder pending eller faulted, valfritt tillsammans med modified, i stället för valid eller invalid när motsvarande tillstånd gäller.

Projektmallarna Blazor innehåller formatmallar för vanliga giltiga och ogiltiga klasser. Lägg till format för andra klasser efter behov. ValidationMessage och ValidationSummary accepterar även godtyckliga HTML-attribut. Om du anger ett class attribut ersätts komponentens standardklass.

Om du vill ändra de klasser som används för indatakomponenter, ärv från 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";
    }
}

En anpassad FieldCssClassProvider bestämmer det fullständiga klassvärdet för varje fält. Om formuläret använder asynkron fältverifiering ska du hantera IsValidationPending(fieldIdentifier) och IsValidationFaulted(fieldIdentifier) i providern när väntande eller felaktiga klasser krävs.

Tilldela leverantören till formulärets EditContext:

editContext.SetFieldCssClassProvider(
    new BootstrapFieldCssClassProvider());

För anpassad indatamarkering anropar du FieldCssClass för att hämta den klass som valts av den aktuella providern.

När en EditForm tilldelas en modell tar dess underordnade innehåll emot det genererade EditContext. Samla in kontexten via parametern Context och anropet FieldCssClass för att tillämpa fältets klasser på omgivande markering:

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

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

Svara på valideringstillstånd

EditContext exponerar det aktuella valideringstillståndet utan att initiera verifieringen.

  • Använd IsModified(field) eller IsModified() för att avgöra om ett fält eller något fält i formuläret har ändrats.
  • Använd GetValidationMessages(field) eller GetValidationMessages() för att granska aktuellt fält eller formulärmeddelanden.

Använd IsValid(field) för att avgöra om ett fält för närvarande har valideringsmeddelanden.

För ett fält kan frånvaron av meddelanden kontrolleras med !editContext.GetValidationMessages(field).Any().

I följande exempel visas endast anpassat användargränssnitt när ett fält har ändrats och är ogiltigt:

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

Indatakomponenter, ValidationMessageoch ValidationSummary uppdaterar sig själva när valideringstillståndet ändras. En komponent som återger annan UI för villkorlig validering bör prenumerera på OnValidationStateChanged och anropa StateHasChanged:

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

Avsluta prenumerationen från OnValidationStateChanged när komponenten tas bort.

Använd IsValidationPending(field) och IsValidationFaulted(field) för asynkron fältverifiering. De parameterlösa metoderna beskriver formnivåpass ValidateAsync och aggregerar inte tillståndet för varje fält.

Dessa tillstånd omfattar även asynkront arbete som utförs av DataAnnotationsValidator. En AsyncValidationAttribute tillämpad på en egenskap använder fälttillstånd under fältvalidering, inklusive standardklasserna pending och faulted CSS-klasserna. Under ValidateAsync bidrar asynkrona attribut och IAsyncValidatableObject till tillståndet på formulärnivå som rapporteras av de parameterlösa metoderna.

Indikatorer för väntande status i realtid kräver ett interaktivt renderingsläge. Under ett statiskt SSR-formulärinlägg slutförs verifieringen på serversidan innan svaret återges.

Skicka kontrollformulär

EditForm tillhandahåller tre återanrop för inlämning:

Återkoppling Behavior
OnValidSubmit Körs efter att automatisk validering har slutförts.
OnInvalidSubmit Körs när automatisk validering misslyckas.
OnSubmit Ger hanteraren kontroll över validering och överföring.

OnValidSubmit och OnInvalidSubmit kan användas tillsammans. Kombinera OnSubmit inte med någon av dem.

EditForm använder ValidateAsync innan du anropar OnValidSubmit eller OnInvalidSubmit, så den väntar på synkrona och asynkrona validatorer. När du hanterar OnSubmit, anropa ValidateAsync innan du behandlar formuläret:

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

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

Synkron Validate metod är föråldrad i .NET 11. Den inväntar inte någon asynkron validering och utlöser ett undantag om en hanterare försöker registrera asynkront arbete.

För interaktiva formulär kan det väntande tillståndet på formulärnivå användas för att inaktivera insändning medan ValidateAsync körs:

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

När du hanterar OnSubmit, anropa Validate innan du behandlar formuläret:

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

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

Relaterat innehåll

  • Uppdaterades senast