Validação de formulários no ASP.NET Core Blazor

• Para escrever e configurar regras de validação baseadas em modelo, incluindo regras personalizadas e assíncronas, validação de objeto aninhada e localização, consulte Validação em ASP.NET Core.
• Para obter a validação em tempo real no navegador na renderização estática no servidor (SSR estático), consulte ASP.NET Core Blazor validação de formulários no lado do cliente no SSR estático.
• Para implementações completas de validador-componente e validação remota, consulte ASP.NET Core Blazor validação de formulário avançada.

• Para escrever e configurar regras de validação baseadas em modelo e validação de objeto aninhado, consulte Validação em ASP.NET Core.
• Para implementações completas de validador-componente e validação remota, consulte ASP.NET Core Blazor validação de formulário avançada.

• Para implementações completas de validador-componente e validação remota, consulte ASP.NET Core Blazor validação de formulário avançada.

Para um envio de formulário SSR estático, atribua um FormName exclusivo e receba o modelo enviado com [SupplyParameterFromForm]:

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

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

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

Para obter mais informações sobre envio de formulário e associação de modelo entre modos de renderização, consulte ASP.NET Core Blazor visão geral dos formulários e ASP.NET Core Blazor associação de formulários.

Um formulário SSR estático pode fornecer feedback imediato no navegador com a validação de formulário no lado do cliente do ASP.NET Core Blazor em SSR estático. O formulário é validado novamente com autorização no servidor quando postado.

Um formulário SSR estático é validado no servidor quando postado e não fornece validação de campo dinâmico entre solicitações.

Configurar validação de anotações de dados

DataAnnotationsValidator sempre habilita a validação do DataAnnotations para o formulário. Para usar os recursos de validação estendida fornecidos pelo Microsoft.Extensions.Validation pacote, chame o AddValidation método de extensão no Program arquivo:

builder.Services.AddValidation();

A AddValidation chamada registra os serviços de validação do pacote e ativa um gerador de origem que cria metadados de validação para tipos de modelo descobertos. O comportamento disponível depende se esses metadados incluem o modelo do formulário:

As APIs ValidatableTypeAttribute e SkipValidationAttribute são experimentais em .NET 10. Para obter detalhes e soluções alternativas disponíveis, consulte Validação no ASP.NET Core.

Ao usar Microsoft.Extensions.Validation, declare tipos de modelo em arquivos C# (.cs) em vez de Razor arquivos de componente (.razor). O gerador de código-fonte cria metadados de validação a partir do código-fonte C# e não pode incluir tipos de modelo declarados em componentes Razor.

Para requisitos de configuração, ordem de validação, regras personalizadas, grafos de objeto aninhados e metadados gerados, consulte Validação em ASP.NET Core.

Validar grafo de objetos aninhados

No .NET 9 ou em versões anteriores, DataAnnotationsValidator valida as propriedades de nível superior do modelo, mas não valida recursivamente propriedades de coleções ou de tipos complexos. Para validação recursiva, use ObjectGraphDataAnnotationsValidator e [ValidateComplexType] do pacote experimentalMicrosoft.AspNetCore.Components.DataAnnotations.Validation:

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

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

O pacote permanece experimental nessas versões da estrutura.

Atributo [CompareProperty]

Para .NET 5 ou anterior, use o pacote ComparePropertyAttribute experimental em vez de CompareAttribute. ComparePropertyAttribute associa o resultado da validação ao campo de forma consistente durante a validação de campo e a validação completa do formulário.

Escrever regras personalizadas baseadas em modelo

Quando os atributos integrados não forem suficientes para expressar uma regra, use um atributo personalizado ValidationAttribute ou IValidatableObject. Para obter diretrizes detalhadas, consulte Validação em ASP.NET Core.

Escrever regras personalizadas baseadas em modelo

Quando os atributos internos não puderem expressar uma regra, use um atributo de validação personalizado ou implemente IValidatableObject. Ambos são executados por DataAnnotationsValidator.

Ao retornar um ValidationResult de um atributo personalizado, inclua o nome do membro validado para que o resultado possa aparecer no componente ValidationMessage desse campo.

Atributos personalizados podem resolver serviços registrados por meio de GetService.

O SSR estático não fornece validação dinâmica de campo .NET entre solicitações.

Para validação assíncrona do formulário completo, chame e.AddAsyncValidator em um manipulador OnValidationRequested. Para validação assíncrona de campo em um formulário interativo, chame EditContext.RegisterAsyncFieldValidator em um manipulador OnFieldChanged. Uma nova validação assíncrona para o mesmo campo substitui e cancela a anterior.

Para atributos de validação assíncrona baseados em modelo, consulte Validação em ASP.NET Core. Para obter um componente de validador reutilizável completo, consulte ASP.NET Core Blazor validação de formulário avançada.

Entradas com validação de campo assíncrono usam pending ou faulted, opcionalmente, com modified, em vez de valid ou invalid enquanto o estado correspondente se aplica.

Para alterar as classes aplicadas aos componentes de entrada, derive 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";
    }
}

Um FieldCssClassProvider personalizado determina o valor completo da classe para cada campo. Se o formulário usar validação de campo assíncrono, manipule IsValidationPending(fieldIdentifier) e IsValidationFaulted(fieldIdentifier) no provedor quando forem necessárias classes pendentes ou com falha.

Atribua o provedor ao EditContext do formulário:

editContext.SetFieldCssClassProvider(
    new BootstrapFieldCssClassProvider());

Para marcação de entrada personalizada, chame FieldCssClass para obter a classe selecionada pelo provedor atual.

Quando um modelo é atribuído a um EditForm, seu conteúdo filho recebe o EditContext gerado. Capture o contexto por meio do Context parâmetro e chame FieldCssClass para aplicar as classes do campo à marcação ao redor:

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

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

Use IsValid(field) para determinar se um campo atualmente tem mensagens de validação.

Para um campo, a ausência de mensagens pode ser verificada com !editContext.GetValidationMessages(field).Any().

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

Use IsValidationPending(field) e IsValidationFaulted(field) para validação de campo assíncrono. Os métodos sem parâmetro descrevem passagens no nível ValidateAsync do formulário e não agregam o estado de cada campo.

Esses estados também incluem trabalho assíncrono executado por DataAnnotationsValidator. Um AsyncValidationAttribute aplicado a uma propriedade usa o estado do campo durante a validação de campo, incluindo as classes padrão pending e faulted CSS. Durante ValidateAsync, atributos assíncronos e IAsyncValidatableObject contribuem para o estado de nível de formulário relatado pelos métodos sem parâmetros.

Indicadores pendentes dinâmicos exigem um modo de renderização interativo. Durante uma postagem de formulário SSR estático, a validação do lado do servidor é concluída antes que a resposta seja renderizada.

EditForm usa ValidateAsync antes de invocar OnValidSubmit ou OnInvalidSubmit e, assim, aguarda validadores síncronos e assíncronos. Ao manipular OnSubmit, chame ValidateAsync antes de processar o formulário:

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

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

O método síncrono Validate é obsoleto no .NET 11. Não aguarda a validação assíncrona e lança uma exceção se um manipulador tentar registrar trabalho assíncrono.

Para formulários interativos, o estado pendente no nível do formulário pode ser usado para desabilitar o envio enquanto ValidateAsync estiver em execução:

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

Ao manipular OnSubmit, chame Validate antes de processar o formulário:

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

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

• Validação no ASP.NET Core

• ASP.NET Core Blazorvalidação de formulário no lado do cliente em SSR estático