Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Observação
Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 11 deste artigo.
Warning
Esta versão do ASP.NET Core já não é suportada. 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 .NET 10 deste artigo.
Este artigo demonstra componentes reutilizáveis do validador e validação remota. Para APIs comuns de validação de formulários, incluindo anotações de dados, validação diretaEditContext, exibição de mensagens, estilo, estado e comportamento de submissão, consulte validação de formulários ASP.NET CoreBlazor.
Para regras de validação baseadas no modelo partilhadas por Blazor e APIs mínimas, consulte Validação no ASP.NET Core.
Para validação de navegador em renderização estática do lado do servidor (SSR estático), veja ASP.NET Core Blazor validação de formulários do lado do cliente em SSR estático.
Construir um componente validador
Um componente de validação encapsula a validação que utiliza os EditContext e ValidationMessageStore de um formulário. Isto é útil quando o mesmo comportamento de validação é usado por várias formas ou quando surgem erros de um serviço em vez de atributos de validação no modelo.
O componente:
- Recebe o
EditContextdo formulário como um parâmetro em cascata. - Cria um repositório para as respetivas mensagens de erro.
- Elimina erros de formulário obsoletos quando é solicitada validação.
- Elimina os erros obsoletos de um campo quando o campo muda.
- Expõe métodos para mostrar e corrigir erros.
- Cancela a subscrição dos seus gestores de eventos quando eliminados.
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 de componente quando o formulário ou um serviço deve apresentar erros:
<EditForm Model="Model" OnValidSubmit="Submit">
<DataAnnotationsValidator />
<CustomValidation @ref="customValidation" />
<ValidationSummary />
...
</EditForm>
@code {
private CustomValidation? customValidation;
}
O componente pode ser usado juntamente com DataAnnotationsValidator. Cada validador tem o seu próprio repositório de mensagens associado ao mesmo EditContext, e ValidationSummary e ValidationMessage exibem mensagens de ambos os validadores.
Para implementar uma regra de negócio dentro do componente validador em vez de aceitar erros externos, execute a regra a partir de HandleValidationRequested ou HandleFieldChanged e adicione as suas mensagens a messages. Para um exemplo mais pequeno que executa isto diretamente num componente de formulário, veja validação de formulários ASP.NET CoreBlazor.
Adicionar validação assíncrona
O mesmo padrão de componentes suporta trabalho assíncrono:
- Num manipulador
OnValidationRequested, chamee.AddAsyncValidatorpara registar processamento ao nível do formulário.EditFormaguarda-o antes de invocarOnValidSubmitouOnInvalidSubmit. - Num
OnFieldChangedhandler, chameEditContext.RegisterAsyncFieldValidatorpara iniciar a validação desse campo. Iniciar outra validação para o mesmo campo substitui e cancela a operação anterior.
Para validação assíncrona ao nível da forma:
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 ao nível de campo:
private void HandleFieldChanged(
object? sender, FieldChangedEventArgs e)
{
CurrentEditContext!.RegisterAsyncFieldValidator(
e.FieldIdentifier,
token => ValidateFieldAsync(e.FieldIdentifier, token));
}
Transmita o token de cancelamento fornecido às operações de E/S. Limpe as mensagens anteriores antes de iniciar a operação, evite publicar resultados parciais após uma exceção e ligue NotifyValidationStateChanged após atualizar as mensagens.
Uma operação cancelada porque foi substituída ou porque a passagem de validação foi cancelada é descartada. Outras exceções colocam o campo ou forma no estado falhado. Para mostrar o estado pendente e com falha, veja validação de formulários ASP.NET CoreBlazor.
Para um componente completo que combina validação assíncrona ao nível da forma e por campo, veja 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 atributos de validação assíncrona no modelo, veja Validação no ASP.NET Core.
O código do componente validador é executado onde o componente é executado. No Interactive WebAssembly, corre no navegador, enquanto corre no servidor através do circuito no Interactive Server.
No SSR estático, o código do componente do validador corre no servidor durante a publicação do formulário e não fornece validação de campo .NET em tempo real entre pedidos.
Validação remota a partir do Interactive WebAssembly
A validação remota envia os dados do formulário de um componente WebAssembly interativo para um endpoint no servidor e adiciona os erros de campo devolvidos ao EditContext do formulário. É útil quando uma regra exige dados privados de servidor, um serviço externo ou outra lógica que não deveria correr no navegador.
O formulário:
- Executa a validação de anotações de dados localmente.
- Envia entrada localmente válida para o endpoint a partir de
OnValidSubmit. - Recebe erros de validação por chave de campo do servidor.
- Adiciona erros remotos ao formulário através do componente validador.
OnValidSubmit significa apenas que a validação local teve sucesso. Processe ou guarde o modelo apenas depois de a validação remota também ter sucesso.
Importante
Não envie dados de validação privada ou regras de negócio para o navegador. O servidor deve validar cada pedido de forma independente porque a validação do lado do cliente pode ser contornada.
Este exemplo valida remotamente quando o formulário é submetido. Para verificações remotas em tempo real por campo, utilize o padrão assíncrono de validação de campo do Add asynchronous validation.
Se o formulário WebAssembly for pré-renderizado, os seus serviços do lado do cliente também devem estar disponíveis durante a pré-renderização. Para as abordagens disponíveis, veja Pré-processar componentes do ASP.NET Core Razor.
Validar com uma API Mínima
Chame AddValidation o projeto servidor para validar os parâmetros de endpoint suportados antes de o handler ser executado.
As Microsoft.Extensions.Validation APIs usadas para os metadados de validação gerados são experimentais no .NET 10. Para mais detalhes, consulte Validação no ASP.NET Core.
Se o modelo for declarado no .Client projeto, regista os metadados de validação gerados em ambos os projetos, conforme descrito em Validação no ASP.NET Core.
O endpoint adiciona uma regra de negócio privada e devolve erros indicados 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 handler.
ValidationProblem retorna 400 Bad Request com uma errors propriedade contendo mensagens com chave de campo. A validação bem-sucedida retorna 204 No Content.
Validar com um controlador de API
Numa solução alojada Blazor WebAssembly , coloque o modelo partilhado no Shared projeto e valide-o com um controlador de API no Server projeto. O [ApiController] atributo rejeita automaticamente anotações de dados inválidas antes da ação ser executada.
[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();
}
}
Registar e mapear controladores no projeto servidor. O controlador devolve 400 Bad Request com uma resposta ValidationProblemDetails quando a validação falha e 204 No Content quando é bem-sucedida.
Chame o endpoint e apresente os erros
Registe um HttpClient no projeto WebAssembly com o endereço de base da aplicação:
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 Construir um componente 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 validador elimina um erro de campo remoto quando esse campo muda, para que o utilizador possa corrigir o valor e submeter novamente. Proteger o endpoint de acordo com os requisitos de segurança da aplicação; autenticação e autorização estão fora do âmbito deste exemplo de validação.
O exemplo completo de validação remota inclui o ponto final do anfitrião, o modelo partilhado, o registo da validação entre assemblies, o componente de validação e o formulário WebAssembly interativo.
A amostra de validação remota do .NET 10 demonstra o mesmo fluxo de validação numa aplicação Interactive Auto com autenticação e um proxy do lado do servidor.