validación de formularios de ASP.NET Core Blazor

Nota

Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión .NET 10 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulte la Política de soporte de .NET y .NET Core. Para la versión actual, consulte la versión .NET 10 de este artículo.

En este artículo se explica cómo validar la entrada del usuario en Blazor formularios.

Para la mayoría de los formularios, el enfoque más sencillo y recomendado es agregar atributos de validación de anotaciones de datos al modelo y colocar un DataAnnotationsValidator componente en .EditForm Blazor también admite la validación personalizada a través del EditContextformulario , ya sea directamente en el componente del formulario o en un componente de validador reutilizable.

Los artículos relacionados proporcionan más detalles:

Validación con anotaciones de datos

El modelo siguiente usa RequiredAttribute y 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; }
}

Agregue el modelo a un EditForm, incluya DataAnnotationsValidator y muestre errores con ValidationMessage<TValue> o ValidationSummary. El OnValidSubmit callback solo se invoca cuando la validación se realiza correctamente:

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

Para un envío de formulario con SSR estático, asigne un único FormName y reciba el modelo enviado con [SupplyParameterFromForm]:

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

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

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

Para obtener más información sobre el envío de formularios y el enlace de modelos en los modos de representación, consulte ASP.NET Core Blazor información general sobre formularios y enlace de formularios ASP.NET CoreBlazor.

Sin un DataAnnotationsValidator componente, los atributos de validación del modelo no participan en la validación del formulario.

Cuando se ejecuta la validación

Blazor realiza la validación de campos y la validación de formulario completo:

  • La validación de campos se ejecuta después de que un campo cambie. En un formulario interactivo, esto se produce en .NET mientras el usuario edita el formulario.
  • Normalmente, la validación completa del formulario se ejecuta cuando EditForm gestiona el envío a través de OnValidSubmit o OnInvalidSubmit. Un OnSubmit controlador toma el control de la validación, como se describe en Envío de formulario de control.

Un formulario SSR estático puede proporcionar comentarios de explorador dinámicos con ASP.NET Core Blazor validación de formularios del lado cliente en SSR estático. El formulario se valida de nuevo de forma autoritativa en el servidor cuando se publica.

Un formulario SSR estático se valida en el servidor cuando se publica y no proporciona validación de campo activo entre solicitudes.

Resultados de validación que identifican a un miembro están asociados a ese campo. Los resultados sin un nombre de miembro están asociados al modelo y aparecen en un resumen de validación en lugar de en el componente de ValidationMessage un campo.

Configuración de la validación de anotaciones de datos

DataAnnotationsValidator siempre habilita la validación de DataAnnotations para el formulario. Para usar las capacidades de validación extendidas que proporciona el paquete Microsoft.Extensions.Validation, llame al método de extensión AddValidation en el archivo Program:

builder.Services.AddValidation();

La AddValidation llamada registra los servicios de validación del paquete y activa un generador de origen que crea metadatos de validación para los tipos de modelo detectados. El comportamiento disponible depende de si esos metadatos incluyen el modelo del formulario:

Configuration Behavior
Los metadatos generados están disponibles Valida los objetos y colecciones anidados y admite la localización de mensajes.
Los metadatos generados no están disponibles Valida las propiedades de nivel superior, pero no valida los objetos o colecciones anidados y no usa la Microsoft.Extensions.Validation canalización de localización de mensajes.
Configuration Behavior
Los metadatos generados están disponibles Valida los objetos y colecciones anidados.
Los metadatos generados no están disponibles Valida solo las propiedades de nivel superior.

Las ValidatableTypeAttribute API y SkipValidationAttribute son experimentales en .NET 10. Para obtener más información y soluciones alternativas disponibles, consulte Validación en ASP.NET Core.

Al usar Microsoft.Extensions.Validation, declare tipos de modelo en archivos de C# (.cs) en lugar de archivos de Razor componentes (.razor). El generador de código fuente crea metadatos de validación a partir del código fuente de C# y no puede incluir tipos de modelo declarados en componentes Razor.

Para conocer los requisitos de configuración, el orden de validación, las reglas personalizadas, los gráficos de objetos anidados y los metadatos generados, consulte Validación en ASP.NET Core.

Validar gráficos de objetos anidados

En .NET 9 o versiones anteriores, valida las propiedades del modelo de nivel superior, DataAnnotationsValidator pero no valida de forma recursiva las propiedades de colección o de tipo complejo. Para la validación recursiva, use ObjectGraphDataAnnotationsValidator y [ValidateComplexType] desde el paquete experimentalMicrosoft.AspNetCore.Components.DataAnnotations.Validation:

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

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

El paquete permanece experimental en estas versiones del marco.

[CompareProperty] Atributo

Para .NET 5 o versiones anteriores, use el paquete ComparePropertyAttribute experimental en lugar de CompareAttribute. ComparePropertyAttribute asocia el resultado de la validación al campo de forma coherente durante la validación de campo y del formulario completo.

Escritura de reglas personalizadas basadas en modelos

Cuando los atributos integrados no pueden expresar una regla, use un personalizado ValidationAttribute o IValidatableObject. Para obtener instrucciones detalladas, consulte Validación en ASP.NET Core.

Escritura de reglas personalizadas basadas en modelos

Cuando los atributos integrados no pueden expresar una regla, use un atributo de validación personalizado o implemente IValidatableObject. Ambos se ejecutan a través de DataAnnotationsValidator.

Al devolver un ValidationResult desde un atributo personalizado, incluya el nombre del miembro validado para que el resultado pueda aparecer en el componente ValidationMessage de ese campo.

Los atributos personalizados pueden resolver los servicios registrados a través de GetService.

Añadir validación mediante EditContext

EditForm crea un objeto EditContext automáticamente cuando se asigna su Model parámetro. Para usar las API de validación directamente, cree usted mismo el EditContext y asígnelo a EditContext. No asigne Model y EditContext al mismo formulario.

La validación personalizada usa normalmente:

El siguiente patrón de formulario interactivo agrega una regla de negocio de nivel de formulario junto con la validación de anotaciones de datos y vuelve a comprobar la regla cuando cambia cualquiera de los campos pertinentes:

@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 controlador recibe el campo modificado en e.FieldIdentifier. Borre o reemplace los mensajes afectados y llame a NotifyValidationStateChanged, como se muestra en el ejemplo anterior.

Static SSR no proporciona validación de campo de .NET dinámica entre solicitudes.

Para la validación asincrónica de formulario completo, llame e.AddAsyncValidator desde un OnValidationRequested controlador. Para la validación asincrónica de campos en un formulario interactivo, llame a EditContext.RegisterAsyncFieldValidator desde un controlador de OnFieldChanged. Una nueva validación asincrónica para el mismo campo reemplaza y cancela la anterior.

Para obtener atributos de validación asincrónica basados en modelos, consulte Validación en ASP.NET Core. Para obtener un componente de validador reutilizable completo, consulte ASP.NET Core Blazor validación avanzada de formularios.

Para obtener una implementación reutilizable que encapsula las suscripciones de eventos y su almacén de mensajes, consulte ASP.NET Core Blazor validación avanzada de formularios.

Mostrar mensajes de validación

Use ValidationMessage<TValue> para mostrar mensajes asociados a un campo:

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

Use ValidationSummary para mostrar mensajes para el formulario:

<ValidationSummary />

Asigne el parámetro del Model resumen para restringirlo a los mensajes asociados a un modelo determinado:

<ValidationSummary Model="Model" />

Para inspeccionar los mensajes actuales en el código, llame a GetValidationMessages:

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

Estos métodos leen el estado de validación actual. No inician la validación.

Personalización de la apariencia de validación

Blazor aplica clases CSS que representan el estado de campo y mensaje:

Elemento Las clases
Input valid o invalid, más modified después de que el usuario edite el campo
Mensaje de validación validation-message
Resumen de validación validation-summary-errors o validation-summary-valid

Las entradas con validación de campos asincrónicas usan pending o faulted, opcionalmente con modified, en lugar de valid o invalid mientras se aplica el estado correspondiente.

Las Blazor plantillas de proyecto incluyen estilos para las clases válidas y no válidas comunes. Agregue estilos para otras clases según sea necesario. ValidationMessage y ValidationSummary también aceptan atributos HTML arbitrarios. Proporcionar un class atributo reemplaza la clase predeterminada del componente.

Para cambiar las clases aplicadas a los 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";
    }
}

Un personalizado FieldCssClassProvider determina el valor de clase completo para cada campo. Si el formulario usa la validación de campos asincrónicas, controle IsValidationPending(fieldIdentifier) y IsValidationFaulted(fieldIdentifier) en el proveedor cuando se requieran clases pendientes o con errores.

Asigne el proveedor al EditContext del formulario:

editContext.SetFieldCssClassProvider(
    new BootstrapFieldCssClassProvider());

Para el marcado de entrada personalizado, llame FieldCssClass a para obtener la clase seleccionada por el proveedor actual.

Reaccionar ante el estado de validación

EditContext expone el estado de validación actual sin iniciar la validación.

  • Use IsModified(field) o IsModified() para determinar si un campo o cualquier campo del formulario ha cambiado.
  • Use GetValidationMessages(field) o GetValidationMessages() para inspeccionar los mensajes de formulario o campo actuales.

Use IsValid(field) para determinar si un campo tiene actualmente mensajes de validación.

Para un campo, la ausencia de mensajes se puede comprobar con !editContext.GetValidationMessages(field).Any().

En el ejemplo siguiente se muestra la interfaz de usuario personalizada solo después de modificar un campo y no es válida:

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

Los componentes de entrada, ValidationMessagey ValidationSummary se actualizan a sí mismos cuando cambia el estado de validación. Un componente que renderiza otros elementos de la interfaz de usuario de validación condicional debe suscribirse a StateHasChanged y llamar a OnValidationStateChanged:

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

Anular la suscripción a OnValidationStateChanged cuando se desecha el componente.

Use IsValidationPending(field) y IsValidationFaulted(field) para la validación asincrónica de campos. Los métodos sin parámetros describen las validaciones a nivel de formulario ValidateAsync y no agregan el estado de todos los campos.

Estos estados también incluyen el trabajo asincrónico realizado por DataAnnotationsValidator. Cuando se aplica un AsyncValidationAttribute a una propiedad, se usa el estado del campo durante la validación del campo, incluidas las clases CSS predeterminadas pending y faulted. Durante ValidateAsync, los atributos asincrónicos y IAsyncValidatableObject contribuyen al estado de nivel de formulario notificado por los métodos sin parámetros.

Los indicadores pendientes dinámicos requieren un modo de representación interactivo. Durante un envío de formulario con SSR estático, la validación del lado del servidor se completa antes de que se renderice la respuesta.

Control del envío de formularios

EditForm proporciona tres funciones de devolución de llamada de envío:

Callback Behavior
OnValidSubmit Se ejecuta después de que la validación automática se realice correctamente.
OnInvalidSubmit Se ejecuta después de que se produzca un error en la validación automática.
OnSubmit Proporciona al controlador el control de validación y envío.

OnValidSubmit y OnInvalidSubmit se pueden usar juntos. No combines OnSubmit con ninguno de ellos.

EditForm usa ValidateAsync antes de invocar OnValidSubmit o OnInvalidSubmit, por lo que espera validadores sincrónicos y asincrónicos. Al gestionar OnSubmit, llame ValidateAsync antes de procesar el formulario:

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

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

El método sincrónico Validate está obsoleto en .NET 11. No espera la validación asíncrona y lanza una excepción si un manejador intenta registrar trabajo asíncrono.

Para los formularios interactivos, el estado pendiente del formulario puede usarse para deshabilitar el envío mientras se ejecuta ValidateAsync:

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

Al gestionar OnSubmit, llame a Validate antes de procesar el formulario:

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

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

Recursos adicionales

  • Last updated on