Vue d’ensemble des formulaires Blazor ASP.NET Core

Cet article explique comment utiliser des formulaires dans Blazor.

Formulaires et composants d’entrée

L’infrastructure Blazor prend en charge les formulaires et fournit des composants d’entrée intégrés :

• Lier à un objet ou un modèle pouvant utiliser des annotations de données
  • Formulaires HTML avec l’élément <form>
  • Composants EditForm
• Composants d’entrée intégrés

Remarque

Les fonctionnalités de validation ASP.NET Core non prises en charge sont traitées dans la section Fonctionnalités de validation non prises en charge.

L’espace de noms Microsoft.AspNetCore.Components.Forms fournit :

• Des classes de gestion des éléments de formulaire, de l’état et de la validation.
• Accéder aux composants Input* intégrés.

Un projet, créé à partir du modèle de projet Blazor, comprend l’espace de noms dans le fichier _Imports.razor de l’application, ce qui rend l’espace de noms disponible pour les composants Razor de l’application.

Les formulaires HTML standard sont pris en charge. Créez un formulaire à l’aide de la balise HTML <form> normale et spécifiez un gestionnaire @onsubmit pour gérer la requête du formulaire envoyée.

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

Dans le composant StarshipPlainForm précédent :

• Le formulaire est affiché où l’élément <form> apparaît. Le formulaire est nommé avec l’attribut de directive @formname, qui identifie de façon unique le formulaire dans l’infrastructure Blazor.
• Le modèle est créé dans le bloc @code du composant et conservé dans une propriété publique (Model). L’attribut [SupplyParameterFromForm] indique que la valeur de la propriété associée doit être fournie à partir des données du formulaire. Les données de la requête, correspondant au nom de la propriété, sont liées à la propriété.
• InputText est un composant d’entrée permettant de modifier des valeurs de chaîne. L’attribut de directive @bind-Value lie la propriété de modèle Model.Id à la propriété Value du composant InputText.
• La méthode Submit est inscrite en tant que gestionnaire pour le rappel @onsubmit. Le gestionnaire est appelé lorsque le formulaire est envoyé par l’utilisateur.

Important

Utilisez toujours l’attribut de directive @formname avec un nom de formulaire unique.

Blazor améliore la navigation entre les pages et la gestion des formulaires en interceptant la requête, afin d’appliquer la réponse au DOM existant, en conservant autant que possible le formulaire rendu. L’amélioration évite la nécessité de charger entièrement la page et propose une expérience utilisateur beaucoup plus fluide, similaire à une application monopage (SPA), bien que le composant soit rendu sur le serveur. Pour plus d’informations, consultez Routage et navigation ASP.NET Core Blazor.

Le rendu de la diffusion en continu est pris en charge pour les formulaires HTML standard.

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

L’exemple précédent inclut la prise en charge antiforgery en incluant un composant AntiforgeryToken dans le formulaire. La prise en charge antiforgery est expliquée plus loin dans la section Prise en charge antiforgery de cet article.

Pour envoyer un formulaire basé sur les événements DOM d’un autre élément, par exemple oninput ou onblur, utilisez JavaScript pour envoyer le formulaire (submit (documentation MDN)).

Au lieu d’utiliser des formulaires standard dans les applications Blazor, un formulaire est généralement défini avec la prise en charge intégrée du formulaire de Blazor à l’aide du composant EditForm du framework. Le composant Razor suivant illustre les éléments, les composants et le code Razor classiques pour afficher un formulaire web à l’aide d’un composant EditForm.

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

Dans le composant Starship1 précédent :

• Le composant EditForm est affiché à l’endroit où l’élément <EditForm> s’affiche. Le formulaire est nommé avec l’attribut de directive @formname, qui identifie de façon unique le formulaire dans l’infrastructure Blazor.
• Le modèle est créé dans le bloc @code du composant et conservé dans une propriété publique (Model). La propriété est affectée au paramètre EditForm.Model. L’attribut [SupplyParameterFromForm] indique que la valeur de la propriété associée doit être fournie à partir des données du formulaire. Les données de la requête, correspondant au nom de la propriété, sont liées à la propriété.
• InputText est un composant d’entrée permettant de modifier des valeurs de chaîne. L’attribut de directive @bind-Value lie la propriété de modèle Model.Id à la propriété Value du composant InputText.
• La méthode Submit est inscrite en tant que gestionnaire pour le rappel OnSubmit. Le gestionnaire est appelé lorsque le formulaire est envoyé par l’utilisateur.

Important

Utilisez toujours l’attribut de directive @formname avec un nom de formulaire unique.

Blazor améliore la navigation de page et la gestion des formulaires pour les composants EditForm. Pour plus d’informations, consultez Routage et navigation ASP.NET Core Blazor.

Le rendu de la diffusion en continu est pris en charge pour EditForm.

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

†Pour plus d’informations sur la liaison de propriétés, consultez Liaison de données Blazor ASP.NET Core.

Dans l’exemple suivant, le composant précédent est modifié pour créer le formulaire dans le composant Starship2 :

• OnSubmit est remplacé par OnValidSubmit, qui traite le gestionnaire d’événements affecté si le formulaire est valide lors de l’envoi par l’utilisateur.
• Un composant ValidationSummary est ajouté pour afficher les messages de validation lorsque le formulaire n’est pas valide lors de l’envoi du formulaire.
• Le validateur d’annotations de données (composant† DataAnnotationsValidator) assure la prise en charge de la validation à l’aide d’annotations de données :
  • Si le champ de formulaire <input> est vide lorsque le bouton Submit est sélectionné, une erreur s’affiche dans le résumé de validation (composant‡ ValidationSummary) (« The Id field is required. ») et Submit n’est pas appelé.
  • Si le champ de formulaire <input> contient plus de dix caractères, lorsque le bouton Submit est sélectionné, une erreur s’affiche dans le résumé de validation (« Id is too long. »). Submit n’est pas appelé.
  • Si le champ de formulaire <input> contient une valeur valide lorsque le bouton Submit est sélectionné, Submit est appelé.

†Le composant DataAnnotationsValidator est abordé dans la section Composant validateur. ‡Le composant ValidationSummary est abordé dans la section Composants du résumé de validation et du message de validation.

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

Gérer l’envoi du formulaire

Le EditForm fournit les rappels suivants pour la gestion de la soumission du formulaire :

• Utilisez OnValidSubmit pour affecter un gestionnaire d’événements à exécuter lorsqu’un formulaire avec des champs valides est envoyé.
• Utilisez OnInvalidSubmit pour affecter un gestionnaire d’événements à exécuter lorsqu’un formulaire avec des champs non valides est envoyé.
• Utilisez OnSubmit pour affecter un gestionnaire d’événements à exécuter, quel que soit l’état de validation des champs du formulaire. Le formulaire est validé en appelant EditContext.Validate dans la méthode du gestionnaire d’événements. Si Validate renvoie true, le formulaire est valide.

Effacer un formulaire ou un champ

Réinitialisez un formulaire en désactivant son modèle à son état par défaut, qui peut être effectué à l’intérieur ou à l’extérieur d’un balisage de EditForm :

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

...

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

Vous pouvez également utiliser une expression Razor explicite :

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

Réinitialiser un champ en ramenant la valeur de son modèle à son état par défaut :

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

...

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

Vous pouvez également utiliser une expression Razor explicite :

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

Il n’est pas nécessaire d’appeler StateHasChanged dans les exemples précédents, car StateHasChanged est automatiquement appelé par l’infrastructure de Blazor pour renvoyer le composant après l’appel d’un(e) gestionnaire d’événements. Si un(e) gestionnaire d’événements n’est pas utilisé pour appeler les méthodes qui effacent un formulaire ou un champ, le code du développeur doit appeler StateHasChanged pour renvoyer le composant.

Prise en charge d’Antiforgery

Les services anti-falsification sont automatiquement ajoutés aux applications Blazor lorsqu’ils AddRazorComponents sont appelés dans le fichier Program.

L’application utilise l’intergiciel Antiforgery en appelant UseAntiforgery dans son pipeline de traitement des requêtes dans le fichier Program. UseAntiforgery est appelé après l’appel à UseRouting. S’il y a des appels vers UseRouting et UseEndpoints, l’appel vers UseAntiforgery doit passer entre eux. Un appel à UseAntiforgery doit être placer après les appels à UseAuthentication et UseAuthorization.

Le composant AntiforgeryToken restitue un jeton antiforgery en tant que champ masqué et l’attribut [RequireAntiforgeryToken] active la protection antiforgery. Si une vérification antiforgery échoue, une réponse 400 - Bad Request est levée et le formulaire n’est pas traité.

Pour les formulaires basés sur EditForm, le composant AntiforgeryToken et l’attribut [RequireAntiforgeryToken] sont automatiquement ajoutés afin de fournir une protection antiforgery.

Pour les formulaires basés sur l’élément <form> HTML, ajoutez manuellement le composant AntiforgeryToken au formulaire :

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

Warning

Pour les formulaires basés sur EditForm ou sur l’élément HTML <form>, la protection antiforgery peut être désactivée en transmettant required: false à l’attribut [RequireAntiforgeryToken]. L’exemple suivant désactive antiforgery et n’est pas recommandé pour les applications publiques :

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

Pour plus d’informations, consultez ASP.NET Core Blazor Authentification et autorisation.

Atténuer les attaques par surcharge POST

Les formulaires côté serveur dont le rendu est statique, par exemple ceux généralement utilisés dans les composants qui créent et modifient des enregistrements dans une base de données avec un modèle de formulaire, peuvent être vulnérables à une attaque par surcharge POST, également appelée attaque par affectation de masse. Une attaque par surcharge POST se produit quand un utilisateur malveillant soumet un formulaire HTML via la méthode POST au serveur de traitement des données, en ajoutant des données correspondant à des propriétés qui ne font pas partie du formulaire affiché, et que le développeur ne souhaite pas que les utilisateurs modifient. L’expression « surcharge POST » signifie littéralement que l’utilisateur malveillant a surchargé le formulaire de données POST.

La surcharge POST n’est pas un problème quand le modèle n’inclut pas de propriétés restreintes pour les opérations de création et de mise à jour. Toutefois, il est important de garder à l’esprit la surcharge POST quand vous utilisez et gérez des formulaires Blazor statiques avec rendu côté serveur (SSR).

Si vous souhaitez atténuer la surcharge POST, nous vous recommandons d’utiliser un modèle vue/objet DTO (objet de transfert de données) distinct pour le formulaire et la base de données durant les opérations de création (insertion) et de mise à jour. Quand le formulaire est envoyé, seules les propriétés du modèle vue/de l’objet DTO sont utilisées par le composant et le code C# pour modifier la base de données. Toutes les données supplémentaires incluses par un utilisateur malveillant sont abandonnées, ce qui empêche l’utilisateur malveillant de mener une attaque par surcharge POST.

Gestion améliorée des formulaires

La navigation améliorée pour les requêtes POST de formulaire avec le paramètre Enhance pour les formulaires EditForm ou l’attribut data-enhance pour les formulaires HTML (<form>) :

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

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

❌Non pris en charge : vous ne pouvez pas définir la navigation améliorée sur l’élément ancêtre d’un formulaire pour activer la gestion améliorée des formulaires.

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

Les publications de formulaire améliorées fonctionnent uniquement avec les points de terminaison Blazor. La publication d’un formulaire amélioré sur un point de terminaison non-Blazor entraîne une erreur.

Pour désactiver la gestion améliorée des formulaires :

• Pour un EditForm, supprimez le paramètre Enhance de l’élément de formulaire (ou définissez-le sur false : Enhance="false").
• Pour un code HTML <form>, supprimez l’attribut data-enhance de l’élément de formulaire (ou définissez-le sur false : data-enhance="false").

La navigation améliorée et la gestion des formulaires de Blazor peuvent annuler les modifications dynamiques apportées au DOM si le contenu mis à jour ne fait pas partie du rendu du serveur. Pour conserver le contenu d’un élément, utilisez l’attribut data-permanent.

Dans l’exemple suivant, le contenu de l’élément <div> est mis à jour dynamiquement par un script lorsque la page se charge :

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

Pour désactiver globalement la navigation améliorée et la gestion des formulaires, consultez Démarrage de ASP.NET Core Blazor.

Pour obtenir des conseils sur l’utilisation de l’événement enhancedload pour écouter les mises à jour de page améliorées, consultez Routage et navigation ASP.NET Core Blazor.

Exemples

Les exemples n’adoptent pas la gestion améliorée des formulaires pour les requêtes POST de formulaire, mais tous les exemples peuvent être mis à jour pour adopter les fonctionnalités améliorées en suivant les instructions de la section Gestion améliorée des formulaires.

Pour montrer comment les formulaires fonctionnent avec la validation des annotations de données, les exemples de composants s’appuient sur l’API System.ComponentModel.DataAnnotations. Si vous souhaitez éviter une ligne de code supplémentaire dans les composants qui utilisent des annotations de données, rendez l’espace de noms disponible dans les composants de l’application avec le fichier d’importation (_Imports.razor) :

@using System.ComponentModel.DataAnnotations

Des exemples de formulaires référencent des aspects de l’univers Star Trek. Star Trek est une œuvre sous droits d’auteur ©1966-2023 de CBS Studios et Paramount.

La validation côté client nécessite un circuit

Dans les Blazor Web App, la validation côté client nécessite un circuit actif BlazorSignalR. La validation côté client n’est pas disponible pour les formulaires dans les composants qui ont adopté un rendu côté serveur statique (SSR statique). Les formulaires qui adoptent le SSR statique sont validés sur le serveur après l’envoi du formulaire.

Fonctionnalités de validation non prises en charge

Tous les validateurs intégrés d’annotation de données sont pris en charge dans Blazor à l’exception de l’attribut de validation [Remote].

La validation jQuery n’est pas prise en charge dans les Razor composants. Nous vous recommandons l’une des approches suivantes :

• Suivez les instructions de ASP.NET validation des formulaires Core Blazor pour :
  • Validation côté serveur dans un Blazor Web App mode de rendu interactif.
  • Validation côté client dans une application d’assembly web autonome Blazor .
• Utilisez des attributs de validation HTML natifs (consultez la validation de formulaire côté client (documentation MDN)).
• Adoptez une bibliothèque JavaScript de validation tierce.

Pour les formulaires rendus statiquement sur le serveur, un nouveau mécanisme de validation côté client est pris en compte pour .NET 10 à la fin de 2025. Pour plus d’informations, consultez Créer des formulaires rendus par le serveur avec validation Blazor du client sans circuit (dotnet/aspnetcore #51040).

Ressources supplémentaires

• Chargements de fichiers Blazor ASP.NET Core
• Blazor exemples de référentiel GitHub (dotnet/blazor-samples) (comment télécharger)
• Ressources de formulaires de test du référentiel GitHub ASP.NET Core (dotnet/aspnetcore)