validation des formulaires ASP.NET Core Blazor

Note

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 10 de cet article.

Warning

Cette version de ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la politique de support de .NET et .NET Core. Pour la version actuelle, consultez la version .NET 10 de cet article.

Cet article explique comment valider l’entrée utilisateur dans les Blazor formulaires.

Pour la plupart des formulaires, l’approche la plus simple et recommandée consiste à ajouter des attributs de validation d’annotations de données au modèle et à placer un DataAnnotationsValidator composant dans le EditForm. Blazor prend également en charge la validation personnalisée par le biais du EditContextformulaire , directement dans le composant de formulaire ou dans un composant de validateur réutilisable.

Les articles connexes fournissent plus de détails :

Valider avec des annotations de données

Le modèle suivant utilise RequiredAttribute et 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; }
}

Ajoutez le modèle à un EditForm, incluez DataAnnotationsValidatoret affichez des erreurs avec ValidationMessage<TValue> ou ValidationSummary. Le OnValidSubmit rappel est appelé uniquement lorsque la validation réussit :

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

Pour une soumission de formulaire SSR statique, attribuez un FormName unique et recevez le modèle soumis avec [SupplyParameterFromForm] :

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

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

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

Pour plus d’informations sur la soumission de formulaires et la liaison de modèle entre les modes de rendu, consultez ASP.NET Core Blazor vue d’ensemble des formulaires et ASP.NET Core Blazor liaison de formulaires.

DataAnnotationsValidator Sans composant, les attributs de validation sur le modèle ne participent pas à la validation du formulaire.

Lorsque la validation s’exécute

Blazor effectue la validation de champ et la validation de formulaire complet :

  • La validation de champ s’exécute après la modification d’un champ. Dans un formulaire interactif, cela se produit dans .NET pendant que l’utilisateur modifie le formulaire.
  • La validation du formulaire complet s’exécute normalement lorsque EditForm gère la soumission via OnValidSubmit ou OnInvalidSubmit. Un OnSubmit gestionnaire prend le contrôle de la validation, comme décrit dans la soumission du formulaire de contrôle.

Un formulaire SSR statique peut fournir un retour instantané dans le navigateur avec ASP.NET Core Blazor validation côté client des formulaires en SSR statique. Le formulaire est à nouveau validé de manière faisant autorité sur le serveur lors de la publication.

Un formulaire SSR statique est validé sur le serveur lorsqu’il est publié et ne fournit pas de validation de champ en direct entre les requêtes.

Les résultats de validation qui identifient un membre sont associés à ce champ. Les résultats sans nom de membre sont associés au modèle et apparaissent dans un résumé de validation plutôt que dans le composant d’un ValidationMessage champ.

Configurer la validation des annotations de données

DataAnnotationsValidator active toujours la validation DataAnnotations pour le formulaire. Pour utiliser les fonctionnalités de validation étendue fournies par le Microsoft.Extensions.Validation package, appelez la AddValidation méthode d’extension dans le Program fichier :

builder.Services.AddValidation();

L’appel AddValidation inscrit les services de validation du package et active un générateur source qui crée des métadonnées de validation pour les types de modèles découverts. Le comportement disponible varie selon que ces métadonnées incluent le modèle du formulaire :

Configuration Comportement
Les métadonnées générées sont disponibles Valide les objets et collections imbriqués et prend en charge la localisation des messages.
Les métadonnées générées ne sont pas disponibles Valide les propriétés de niveau supérieur, mais ne valide pas les objets ou collections imbriqués et n'utilise pas le Microsoft.Extensions.Validation pipeline de localisation des messages.
Configuration Comportement
Les métadonnées générées sont disponibles Valide les objets et collections imbriqués.
Les métadonnées générées ne sont pas disponibles Valide uniquement les propriétés de niveau supérieur.

Les API ValidatableTypeAttribute et SkipValidationAttribute sont expérimentales dans .NET 10. Pour plus d’informations et les solutions de contournement disponibles, consultez Validation dans ASP.NET Core.

Lors de l’utilisation Microsoft.Extensions.Validation, déclarez des types de modèles dans des fichiers C# (.cs) plutôt que des Razor fichiers de composant (.razor). Le générateur source crée des métadonnées de validation à partir de la source C# et ne peut pas inclure de types de modèle déclarés dans Razor les composants.

Pour connaître les exigences de configuration, l’ordre de validation, les règles personnalisées, les graphiques d’objets imbriqués et les métadonnées générées, consultez Validation dans ASP.NET Core.

Valider les graphiques d’objets imbriqués

Dans .NET 9 ou version antérieure, DataAnnotationsValidator valide les propriétés de modèle de niveau supérieur, mais ne valide pas de manière récursive les propriétés de collection ou de type complexe. Pour la validation récursive, utilisez ObjectGraphDataAnnotationsValidator et [ValidateComplexType] à partir du package expérimental Microsoft.AspNetCore.Components.DataAnnotations.Validation:

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

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

Le package reste expérimental dans ces versions de framework.

Attribut [CompareProperty]

Pour .NET 5 ou une version antérieure, utilisez le package ComparePropertyAttribute expérimental au lieu de CompareAttribute. ComparePropertyAttribute associe le résultat de validation au champ de manière cohérente pendant la validation de champ et de formulaire complet.

Écrire des règles personnalisées basées sur des modèles

Lorsque les attributs intégrés ne peuvent pas exprimer une règle, utilisez une règle personnalisée ValidationAttribute ou IValidatableObject. Pour obtenir des instructions détaillées, consultez Validation dans ASP.NET Core.

Écrire des règles personnalisées basées sur des modèles

Lorsque les attributs intégrés ne peuvent pas exprimer une règle, utilisez un attribut de validation personnalisé ou implémentez IValidatableObject. Les deux passent par DataAnnotationsValidator.

Lors du renvoi d’un ValidationResult à partir d’un attribut personnalisé, incluez le nom du membre validé afin que le résultat puisse apparaître dans le composant ValidationMessage de ce champ.

Les attributs personnalisés peuvent résoudre les services inscrits via GetService.

Ajouter une validation via EditContext

EditForm crée automatiquement EditContext quand son Model paramètre est affecté. Pour utiliser directement les API de validation, créez le contexte vous-même et affectez-le au EditContext paramètre de EditForm. N’affectez pas Model et EditContext au même formulaire.

La validation personnalisée utilise couramment :

Le modèle interactif suivant ajoute une règle métier au niveau du formulaire en même temps que la validation des annotations de données et revérifie la règle lorsque les modifications de champ pertinentes sont apportées :

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

Un OnFieldChanged gestionnaire reçoit le champ modifié dans e.FieldIdentifier. Effacez ou remplacez les messages affectés et appelez NotifyValidationStateChanged, comme l’illustre l’exemple précédent.

Le SSR statique ne fournit pas de validation de champ de .NET dynamique entre les requêtes.

Pour la validation asynchrone de l’ensemble du formulaire, appelez e.AddAsyncValidator depuis un gestionnaire OnValidationRequested. Pour la validation asynchrone des champs dans un formulaire interactif, appelez EditContext.RegisterAsyncFieldValidator depuis un gestionnaire OnFieldChanged. Une nouvelle validation asynchrone pour le même champ remplace et annule la précédente.

Pour connaître les attributs de validation asynchrone basés sur un modèle, consultez Validation dans ASP.NET Core. Pour obtenir un composant de validateur réutilisable complet, consultez ASP.NET Core Blazor validation avancée du formulaire.

Pour une implémentation réutilisable qui encapsule les abonnements aux événements et son magasin de messages, consultez ASP.NET Core Blazor validation avancée du formulaire.

Afficher les messages de validation

Permet ValidationMessage<TValue> d’afficher les messages associés à un champ :

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

L’expression For identifie le champ par son instance de modèle et sa propriété. Blazor représente cette identité avec un FieldIdentifier, de sorte que les propriétés portant le même nom sur différentes instances de modèle sont traitées comme des champs différents. L’utilisation d’une expression au lieu d’une chaîne permet également aux outils de refactorisation de mettre à jour la référence de propriété.

Permet ValidationSummary d’afficher des messages pour le formulaire :

<ValidationSummary />

Affectez le paramètre du Model résumé pour le restreindre aux messages associés à un modèle particulier :

<ValidationSummary Model="Model" />

Pour examiner les messages actuels dans le code, appelez GetValidationMessages :

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

Ces méthodes lisent l’état de validation actuel. Ils ne lancent pas la validation.

Personnaliser l’apparence de validation

Blazor applique des classes CSS qui représentent l’état du champ et du message :

Élément Cours
Input valid ou invalid, plus modified après que l’utilisateur modifie le champ
Message de validation validation-message
Résumé de la validation validation-summary-errors ou validation-summary-valid

Les champs de saisie avec validation de champ asynchrone utilisent pending ou faulted, éventuellement avec modified, au lieu de valid ou invalid lorsque l’état correspondant s’applique.

Les Blazor modèles de projet incluent des styles pour les classes valides et non valides courantes. Ajoutez des styles pour d’autres classes si nécessaire. ValidationMessage et ValidationSummary acceptent également des attributs HTML arbitraires. L’approvisionnement d’un class attribut remplace la classe par défaut du composant.

Pour modifier les classes appliquées aux composants d’entrée, dérivez de 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";
    }
}

Un FieldCssClassProvider personnalisé détermine la valeur complète de classe pour chaque champ. Si le formulaire utilise la validation de champ asynchrone, gérez IsValidationPending(fieldIdentifier) et IsValidationFaulted(fieldIdentifier) dans le fournisseur lorsque des classes en attente ou défectueuses sont requises.

Affectez le fournisseur au formulaire EditContext:

editContext.SetFieldCssClassProvider(
    new BootstrapFieldCssClassProvider());

Pour le balisage d’entrée personnalisé, appelez FieldCssClass pour obtenir la classe sélectionnée par le fournisseur actuel.

Lorsqu’un modèle est attribué à EditForm, son contenu enfant reçoit le EditContext généré. Capturez le contexte par le biais du Context paramètre et appelez FieldCssClass pour appliquer les classes du champ au balisage environnant :

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

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

Répondre à l’état de validation

EditContext expose l’état de validation actuel sans lancer la validation.

  • Utilisez IsModified(field) ou IsModified() déterminez si un champ ou un champ du formulaire a changé.
  • Utilisez GetValidationMessages() ou GetValidationMessages(field) pour inspecter les messages actuels du champ ou du formulaire.

Permet IsValid(field) de déterminer si un champ contient actuellement des messages de validation.

Pour un champ, l’absence de messages peut être vérifiée avec !editContext.GetValidationMessages(field).Any().

L’exemple suivant affiche l’interface utilisateur personnalisée uniquement une fois qu’un champ est modifié et non valide :

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

Les composants d’entrée, ValidationMessage et ValidationSummary, se mettent à jour eux-mêmes lorsque l’état de validation change. Un composant qui affiche d’autres éléments d’interface utilisateur de validation conditionnelle doit s’abonner à OnValidationStateChanged et appeler StateHasChanged :

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

Se désinscrire de OnValidationStateChanged lorsque le composant est détruit.

Utilisez IsValidationPending(field) et IsValidationFaulted(field) pour la validation de champ asynchrone. Les méthodes sans paramètre décrivent les passes au niveau ValidateAsync du formulaire et n’agrègent pas l’état de chaque champ.

Ces états incluent également le travail asynchrone effectué par DataAnnotationsValidator. Un AsyncValidationAttribute appliqué à une propriété utilise l’état du champ lors de la validation du champ, y compris les classes CSS par défaut faulted et pending. Lors de ValidateAsync, les attributs asynchrones et IAsyncValidatableObject contribuent à l’état du formulaire renvoyé par les méthodes sans paramètre.

Les indicateurs en attente dynamique nécessitent un mode de rendu interactif. Pendant une publication de formulaire SSR statique, la validation côté serveur se termine avant le rendu de la réponse.

Soumission de formulaire de contrôle

EditForm fournit trois fonctions de rappel de soumission :

Callback Comportement
OnValidSubmit S’exécute après la validation automatique.
OnInvalidSubmit S’exécute après l’échec de la validation automatique.
OnSubmit Donne au gestionnaire le contrôle de validation et de soumission.

OnValidSubmit et OnInvalidSubmit peut être utilisé ensemble. Ne combinez OnSubmit pas avec l’un d’eux.

EditForm utilise ValidateAsync avant d’appeler OnValidSubmit ou OnInvalidSubmit, il attend donc des validateurs synchrones et asynchrones. Lors du traitement de OnSubmit, appelez ValidateAsync avant de traiter le formulaire :

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

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

La méthode synchrone Validate est obsolète dans .NET 11. Elle n’attend pas la validation asynchrone et lève une exception si un gestionnaire tente d’enregistrer une opération asynchrone.

Pour les formulaires interactifs, l’état en attente au niveau du formulaire peut être utilisé pour désactiver la soumission pendant l’exécution ValidateAsync :

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

Lors du traitement de OnSubmit, appelez Validate avant de traiter le formulaire :

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

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

Ressources additionnelles

  • Last updated on