Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Note
Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 11 deste artigo.
Aviso
Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, consulte a Política de Suporte do .NET e do .NET Core. Para a versão atual, consulte a versão do .NET 10 deste artigo.
Este artigo demonstra componentes de validador reutilizáveis e validação remota. Para apIs comuns de validação de formulário, incluindo anotações de dados, validação diretaEditContext, exibição de mensagem, estilo, estado e comportamento de envio, consulte ASP.NET Core Blazor validação de formulários.
Para regras de validação baseadas em modelo compartilhadas por Blazor e APIs mínimas, consulte Validação em ASP.NET Core.
Para validação do navegador na renderização estática do lado do servidor (SSR estático), consulte ASP.NET Core Blazor validação de formulário do lado do cliente no SSR estático.
Criar um componente de validador
Um componente de validação encapsula a validação que usa EditContext e ValidationMessageStore de um formulário. Isso é útil quando o mesmo comportamento de validação é usado por vários formulários ou quando os erros chegam de um serviço em vez de atributos de validação no modelo.
O componente:
- Recebe o formulário
EditContextcomo um parâmetro em cascata. - Cria um repositório de mensagens para seus erros.
- Limpa erros de formulário obsoletos quando a validação é solicitada.
- Limpa os erros obsoletos de um campo quando o campo é alterado.
- Expõe métodos para exibir e limpar erros.
- Cancela a assinatura de seus identificadores de eventos quando descartados.
CustomValidation.razor:
@implements IDisposable
@code {
[CascadingParameter]
private EditContext? CurrentEditContext { get; set; }
private ValidationMessageStore messages = default!;
protected override void OnInitialized()
{
if (CurrentEditContext is null)
{
throw new InvalidOperationException(
"CustomValidation requires a cascading EditContext.");
}
messages = new ValidationMessageStore(CurrentEditContext);
CurrentEditContext.OnValidationRequested +=
HandleValidationRequested;
CurrentEditContext.OnFieldChanged += HandleFieldChanged;
}
public void DisplayErrors(IDictionary<string, string[]> errors)
{
foreach (var error in errors)
{
messages.Add(
CurrentEditContext!.Field(error.Key),
error.Value);
}
CurrentEditContext!.NotifyValidationStateChanged();
}
public void ClearErrors()
{
messages.Clear();
CurrentEditContext!.NotifyValidationStateChanged();
}
private void HandleValidationRequested(
object? sender, ValidationRequestedEventArgs e) =>
ClearErrors();
private void HandleFieldChanged(
object? sender, FieldChangedEventArgs e)
{
messages.Clear(e.FieldIdentifier);
CurrentEditContext!.NotifyValidationStateChanged();
}
public void Dispose()
{
if (CurrentEditContext is not null)
{
CurrentEditContext.OnValidationRequested -=
HandleValidationRequested;
CurrentEditContext.OnFieldChanged -= HandleFieldChanged;
}
}
}
Coloque o componente dentro de um EditForm e capture uma referência ao componente quando o formulário ou um serviço precisar exibir erros:
<EditForm Model="Model" OnValidSubmit="Submit">
<DataAnnotationsValidator />
<CustomValidation @ref="customValidation" />
<ValidationSummary />
...
</EditForm>
@code {
private CustomValidation? customValidation;
}
O componente pode ser usado junto com DataAnnotationsValidator. Cada validador tem seu próprio armazenamento de mensagens associado ao mesmo EditContext, e ValidationMessage e ValidationSummary exibem mensagens de ambos os validadores.
Para implementar uma regra de negócios dentro do componente validador em vez de aceitar erros externos, execute a regra de HandleValidationRequested ou HandleFieldChanged adicione suas mensagens a messages. Para obter um exemplo menor que execute isso diretamente em um componente de formulário, consulte ASP.NET Core Blazor validação de formulários.
Adicionar validação assíncrona
O mesmo padrão de componente dá suporte ao trabalho assíncrono:
- Em um manipulador
OnValidationRequested, chamee.AddAsyncValidatorpara registrar o processamento em nível de formulário.EditFormaguarda-o antes de invocarOnValidSubmitouOnInvalidSubmit. - Em um
OnFieldChangedmanipulador, chameEditContext.RegisterAsyncFieldValidatorpara iniciar a validação para esse campo. Iniciar outra validação para o mesmo campo substitui e cancela a operação anterior.
Para validação assíncrona no nível do formulário:
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();
}
Para validação assíncrona no nível do campo:
private void HandleFieldChanged(
object? sender, FieldChangedEventArgs e)
{
CurrentEditContext!.RegisterAsyncFieldValidator(
e.FieldIdentifier,
token => ValidateFieldAsync(e.FieldIdentifier, token));
}
Passe o token de cancelamento fornecido para E/S. Desmarque mensagens anteriores antes de iniciar a operação, evite publicar resultados parciais após uma exceção e chame NotifyValidationStateChanged depois de atualizar mensagens.
Uma operação cancelada porque foi substituída ou porque o passe de validação foi cancelado é descartado. Outras exceções colocam o campo ou o formulário no estado com falha. Para exibir o estado pendente e com falha, consulte ASP.NET Core Blazor validação de formulários.
Para obter um componente completo que combina validação assíncrona de nível de formulário e por campo, consulte o seguinte exemplo:
@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;
}
}
}
Para obter atributos de validação assíncrona no modelo, consulte Validação em ASP.NET Core.
O código do componente validador é executado onde o componente é executado. No modo Interactive WebAssembly, é executado no navegador, enquanto no modo Interactive Server é executado no servidor por meio do circuito.
No SSR estático, o código do componente do validador é executado no servidor durante a postagem de formulário e não fornece validação dinâmica de campo .NET entre solicitações.
Validação remota a partir do WebAssembly interativo
A validação remota envia os dados do formulário de um componente WebAssembly interativo para um ponto de extremidade do servidor e adiciona os erros de campo retornados ao EditContext do formulário. É útil quando uma regra requer dados de servidor privado, um serviço externo ou outra lógica que não deve ser executada no navegador.
O formulário:
- Executa a validação de anotações de dados localmente.
- Envia dados de entrada válidos localmente para o endpoint de
OnValidSubmit. - Recebe erros de validação com chave de campo do servidor.
- Adiciona erros remotos ao formulário por meio do componente do validador.
OnValidSubmit significa apenas que a validação local foi bem-sucedida. Processe ou salve o modelo somente depois que a validação remota também for bem-sucedida.
Importante
Não envie dados de validação privados ou regras de negócios para o navegador. O servidor deve validar cada solicitação de forma independente porque a validação do lado do cliente pode ser ignorada.
Este exemplo valida remotamente quando o formulário é enviado. Para verificações remotas dinâmicas por campo, use o padrão de validação de campo assíncrono de Adicionar validação assíncrona.
Se o formulário WebAssembly for pré-gerado, seus serviços do lado do cliente também deverão estar disponíveis durante a pré-geração. Para obter as abordagens disponíveis, consulte Prerender ASP.NET Core Razor componentes.
Validar com uma API Mínima
Chame AddValidation no projeto do servidor para validar os parâmetros de endpoint compatíveis antes que o handler seja executado.
As Microsoft.Extensions.Validation APIs usadas para metadados de validação gerados são experimentais em .NET 10. Para obter detalhes, consulte Validação no ASP.NET Core.
Se o modelo for declarado no .Client projeto, registre os metadados de validação gerados em ambos os projetos, conforme descrito na Validação em ASP.NET Core.
O endpoint adiciona uma regra de negócio privada e retorna erros indexados pelo nome do membro do modelo:
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();
});
A validação automática rejeita anotações de dados inválidas antes da execução do manipulador.
ValidationProblem retorna 400 Bad Request com uma errors propriedade que contém mensagens com chave de campo. A validação bem-sucedida retorna 204 No Content.
Validar com um controlador de API
Em uma solução hospedada Blazor WebAssembly, coloque o modelo compartilhado no projeto Shared e valide-o com um controlador de API no projeto Server. O [ApiController] atributo rejeita automaticamente anotações de dados inválidas antes da execução da ação.
[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();
}
}
Registre e mapeie controladores no projeto do servidor. O controlador retorna 400 Bad Request com uma ValidationProblemDetails resposta quando a validação falha e 204 No Content quando ela é bem-sucedida.
Chamar o endpoint e exibir erros
Registre um HttpClient no projeto WebAssembly com o endereço base do aplicativo:
builder.Services.AddScoped(sp =>
new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });
builder.Services.AddScoped(sp =>
new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });
Coloque o CustomValidation componente de Criar um componente de validador no formulário:
@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[]>();
}
}
O componente do validador limpa um erro de campo remoto quando esse campo é alterado, para que o usuário possa corrigir o valor e enviar novamente. Proteja o endpoint de acordo com os requisitos de segurança da aplicação; a autenticação e a autorização estão fora do escopo deste exemplo de validação.
O exemplo completo de validação remota inclui o endpoint do host, o modelo compartilhado, o registro da validação entre assemblies, o componente validador e o formulário interativo do WebAssembly.
O exemplo de validação remota do .NET 10 demonstra o mesmo fluxo de validação em um aplicativo Interativo Automático com autenticação e um proxy do lado do servidor.