Blazor ASP.NET Core erweiterte Formularüberprüfung

Modellbasierte Gültigkeitsprüfungsregeln, die von Blazor und minimalen APIs gemeinsam genutzt werden, finden Sie unter "Überprüfung" in ASP.NET Core.

Informationen zur Browserüberprüfung im statischen serverseitigen Rendering (statischer SSR) finden Sie unter ASP.NET Core Blazor clientseitige Formularüberprüfung in statischem SSR.

Asynchrone Überprüfung hinzufügen

Dasselbe Komponentenmuster unterstützt asynchrone Arbeit:

• Rufen Sie in einem OnValidationRequested-Handler e.AddAsyncValidator auf, um die Arbeit auf Formularebene zu registrieren. EditForm wartet, bevor OnInvalidSubmit oder OnValidSubmit aufgerufen wird.
• Rufen Sie EditContext.RegisterAsyncFieldValidator in einem OnFieldChanged Handler auf, um die Überprüfung für dieses Feld zu starten. Starten einer weiteren Überprüfung für dasselbe Feld ersetzt und bricht den vorherigen Vorgang ab.

Für asynchrone Überprüfung auf Formularebene:

private void HandleValidationRequested(
    object? sender, ValidationRequestedEventArgs e) =>
    e.AddAsyncValidator(ValidateAsync);

private async Task ValidateAsync(CancellationToken cancellationToken)
{
    var field = CurrentEditContext!.Field(nameof(Model.Username));
    messages.Clear(field);

    var available = await Http.GetFromJsonAsync<bool>(
        $"api/usernames/available?value={Uri.EscapeDataString(Model.Username)}",
        cancellationToken);

    if (!available)
    {
        messages.Add(field, "The username is already taken.");
    }

    CurrentEditContext.NotifyValidationStateChanged();
}

Für asynchrone Überprüfung auf Feldebene:

private void HandleFieldChanged(
    object? sender, FieldChangedEventArgs e)
{
    CurrentEditContext!.RegisterAsyncFieldValidator(
        e.FieldIdentifier,
        token => ValidateFieldAsync(e.FieldIdentifier, token));
}

Übergeben Sie das bereitgestellte Abbruchtoken an E/A. Löschen Sie vorherige Nachrichten vor dem Starten des Vorgangs, vermeiden Sie die Veröffentlichung teilweiser Ergebnisse nach einer Ausnahme, und rufen Sie nach dem Aktualisieren von Nachrichten auf NotifyValidationStateChanged .

Ein Vorgang, der abgebrochen wurde, weil er ersetzt wurde oder weil der Validierungsdurchlauf abgebrochen wurde, wird verworfen. Andere Ausnahmen platzieren das Feld oder Formular im fehlerhaften Zustand. Informationen zum Anzeigen des ausstehenden und fehlerhaften Zustands finden Sie unter ASP.NET Core Blazor Formularüberprüfung.

Eine vollständige Komponente, die die asynchrone Überprüfung auf Formularebene und pro Feld kombiniert, finden Sie im folgenden Beispiel:

@implements IDisposable
@inject HttpClient Http

@* A validator component that runs asynchronous validation, both when the whole form is
   validated on submit and per field as the user edits the Username field. *@

@code {
    [CascadingParameter]
    private EditContext? CurrentEditContext { get; set; }

    [Parameter, EditorRequired]
    public RegistrationModel Model { get; set; } = default!;

    private ValidationMessageStore? messages;

    protected override void OnInitialized()
    {
        ArgumentNullException.ThrowIfNull(CurrentEditContext);
        messages = new ValidationMessageStore(CurrentEditContext);
        CurrentEditContext.OnValidationRequested += OnValidationRequested;
        CurrentEditContext.OnFieldChanged += OnFieldChanged;
    }

    // Registers asynchronous work for the whole form. EditForm awaits it before invoking
    // OnValidSubmit.
    private void OnValidationRequested(
        object? sender, ValidationRequestedEventArgs e) =>
        e.AddAsyncValidator(ValidateUsernameAsync);

    // Registers asynchronous work for a single field. A new registration supersedes and
    // cancels any validation already in flight for the field.
    private void OnFieldChanged(object? sender, FieldChangedEventArgs e)
    {
        if (e.FieldIdentifier.FieldName != nameof(RegistrationModel.Username))
        {
            return;
        }

        CurrentEditContext!.RegisterAsyncFieldValidator(
            e.FieldIdentifier,
            token => CheckAsync(e.FieldIdentifier, token));
    }

    private Task ValidateUsernameAsync(CancellationToken token) =>
        CheckAsync(CurrentEditContext!.Field(nameof(Model.Username)), token);

    private async Task CheckAsync(FieldIdentifier field, CancellationToken token)
    {
        messages!.Clear(field);

        var available = await Http.GetFromJsonAsync<bool>(
            $"api/usernames/available?value={Uri.EscapeDataString(Model.Username)}",
            token);

        if (!available)
        {
            messages.Add(field, "The username is already taken.");
        }

        CurrentEditContext!.NotifyValidationStateChanged();
    }

    public void Dispose()
    {
        if (CurrentEditContext is not null)
        {
            CurrentEditContext.OnValidationRequested -= OnValidationRequested;
            CurrentEditContext.OnFieldChanged -= OnFieldChanged;
        }
    }
}

Informationen zu asynchronen Überprüfungsattributen für das Modell finden Sie unter "Überprüfung" in ASP.NET Core.

Bei statischem SSR wird der Code der Validator-Komponente beim Absenden des Formulars auf dem Server ausgeführt und bietet zwischen den Anfragen keine Live-Feldvalidierung für .NET.

In diesem Beispiel wird remote überprüft, wann das Formular gesendet wird. Verwenden Sie für Live-Remoteprüfungen auf Feldebene das Muster zur asynchronen Feldvalidierung aus Asynchrone Validierung hinzufügen.

Wenn das WebAssembly-Formular vorab gerendert wird, müssen die clientseitigen Dienste auch während der Vorbearbeitung verfügbar sein. Die verfügbaren Ansätze finden Sie unter Prerender ASP.NET Core Razor Komponenten.

Überprüfen mit einer minimalen API

Rufen Sie AddValidation im Serverprojekt auf, um die unterstützten Endpunktparameter zu validieren, bevor der Handler ausgeführt wird.

Die Microsoft.Extensions.Validation APIs, die für generierte Validierungsmetadaten verwendet werden, sind in .NET 10 experimentell. Ausführliche Informationen finden Sie unter "Überprüfung" in ASP.NET Core.

Wenn das Modell im .Client Projekt deklariert wird, registrieren Sie die generierten Validierungsmetadaten in beiden Projekten, wie in der Überprüfung in ASP.NET Core beschrieben.

Der Endpunkt fügt eine private Geschäftsregel hinzu und gibt Fehler zurück, die mit dem Namen des Modellelements als Schlüssel versehen sind:

app.MapPost("/api/starships/validate", (StarshipModel model) =>
{
    Dictionary<string, string[]> errors = [];

    if (model.Classification == "Defense" &&
        string.IsNullOrWhiteSpace(model.Description))
    {
        errors[nameof(model.Description)] =
            ["A defense ship requires a description."];
    }

    if (errors.Count > 0)
    {
        return Results.ValidationProblem(errors);
    }

    return Results.NoContent();
});

app.MapPost("/api/starships/validate", (StarshipModel model) =>
{
    Dictionary<string, string[]> errors = [];

    if (model.Classification == "Defense" &&
        string.IsNullOrWhiteSpace(model.Description))
    {
        errors[nameof(model.Description)] =
            ["A defense ship requires a description."];
    }

    if (errors.Count > 0)
    {
        return Results.ValidationProblem(errors);
    }

    return Results.NoContent();
});

Die automatische Überprüfung lehnt ungültige Datenanmerkungen ab, bevor der Handler ausgeführt wird. ValidationProblem gibt 400 Bad Request mit einer errors-Eigenschaft zurück, die feldschlüsselbezogene Meldungen enthält. Bei erfolgreicher Validierung wird 204 No Content zurückgegeben.

Überprüfen mit einem API-Controller

Platzieren Sie das gemeinsam genutzte Modell in einer gehosteten Blazor WebAssembly Lösung im Shared Projekt, und überprüfen Sie es mit einem API-Controller im Server Projekt. Das [ApiController] Attribut lehnt vor der Ausführung der Aktion automatisch ungültige Datenanmerkungen ab.

[ApiController]
[Route("api/starships/validate")]
public class StarshipValidationController : ControllerBase
{
    [HttpPost]
    public IActionResult Validate(StarshipModel model)
    {
        if (model.Classification == "Defense" &&
            string.IsNullOrWhiteSpace(model.Description))
        {
            ModelState.AddModelError(
                nameof(model.Description),
                "A defense ship requires a description.");
        }

        if (!ModelState.IsValid)
        {
            return ValidationProblem(ModelState);
        }

        return NoContent();
    }
}

Registrieren und Zuordnen von Controllern im Serverprojekt. Der Controller gibt bei fehlgeschlagener Validierung 400 Bad Request mit einer Antwort ValidationProblemDetails zurück und bei erfolgreicher Validierung 204 No Content.

builder.Services.AddScoped(sp =>
    new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

builder.Services.AddScoped(sp =>
    new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

@page "/"
@using System.Net
@using System.Net.Http.Json
@using BlazorWebAppRemoteValidation.Client.Models
@inject HttpClient Http

<PageTitle>Remote validation</PageTitle>

<h1>Remote validation</h1>

<p>Local validation runs before the form calls the remote endpoint. The endpoint validates the model again and applies a private business rule that requires a description for defense ships.</p>

<EditForm Model="Model" OnValidSubmit="Submit">
    <DataAnnotationsValidator />
    <CustomValidation @ref="remoteErrors" />
    <ValidationSummary />

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

    <p>
        <label>
            Classification:
            <InputSelect id="classification" @bind-Value="Model.Classification">
                <option value="">Select...</option>
                <option value="Exploration">Exploration</option>
                <option value="Defense">Defense</option>
            </InputSelect>
        </label>
        <ValidationMessage For="() => Model.Classification" />
    </p>

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

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

@if (accepted)
{
    <p id="accepted" role="status">The server accepted the form.</p>
}

@code {
    private StarshipModel Model { get; } = new();
    private CustomValidation? remoteErrors;
    private bool accepted;

    private async Task Submit()
    {
        accepted = false;

        using var response = await Http.PostAsJsonAsync(
            "api/starships/validate", Model);

        if (response.IsSuccessStatusCode)
        {
            accepted = true;
            return;
        }

        if (response.StatusCode == HttpStatusCode.BadRequest)
        {
            var problem = await response.Content
                .ReadFromJsonAsync<ValidationProblemResponse>()
                ?? throw new InvalidOperationException(
                    "The validation response didn't contain a response body.");

            remoteErrors!.DisplayErrors(problem.Errors);
            return;
        }

        response.EnsureSuccessStatusCode();
    }

    private sealed record ValidationProblemResponse(
        Dictionary<string, string[]> Errors);
}

@using System.Net
@using System.Net.Http.Json
@inject HttpClient Http

<EditForm Model="Model" OnValidSubmit="Submit">
    <DataAnnotationsValidator />
    <CustomValidation @ref="remoteErrors" />
    <ValidationSummary />

    ...
</EditForm>

@code {
    private StarshipModel Model { get; } = new StarshipModel();
    private CustomValidation? remoteErrors;

    private async Task Submit()
    {
        using var response = await Http.PostAsJsonAsync(
            "api/starships/validate", Model);

        if (response.IsSuccessStatusCode)
        {
            // Process or save the model.
            return;
        }

        if (response.StatusCode == HttpStatusCode.BadRequest)
        {
            var problem = await response.Content
                .ReadFromJsonAsync<ValidationProblemResponse>();

            if (problem is not null)
            {
                remoteErrors!.DisplayErrors(problem.Errors);
            }

            return;
        }

        response.EnsureSuccessStatusCode();
    }

    private sealed class ValidationProblemResponse
    {
        public Dictionary<string, string[]> Errors { get; set; } =
            new Dictionary<string, string[]>();
    }
}

Das vollständige Beispiel für die Remotevalidierung umfasst den Host-Endpunkt, das freigegebene Modell, die Registrierung der assemblyübergreifenden Validierung, die Validatorkomponente und das interaktive WebAssembly-Formular.

Das .NET 10-Beispiel für die Remoteüberprüfung veranschaulicht den gleichen Überprüfungsfluss in einer interaktiven Auto-App mit Authentifizierung und einem serverseitigen Proxy.

• Blazor ASP.NET Core Formularüberprüfung
• ASP.NET Core Blazor clientseitige Formularvalidierung bei statischem SSR
• Überprüfung in ASP.NET Core
• Minimal-APIs: Kurzreferenz

• Blazor ASP.NET Core Formularüberprüfung
• Überprüfung in ASP.NET Core
• Minimal-APIs: Kurzreferenz

Blazor ASP.NET Core Formularüberprüfung