CoreSuite.ValidationProvider 1.1.0

ValidationProvider

Centralized, designer-friendly validation for .NET 8 Windows Forms, included in CoreSuite.

Overview

ValidationProvider centralizes form validation in one non-visual component. After the component is added to a form, every Windows Forms control receives validation properties in the designer, including Required, MinimumLength, MaximumLength, RegularExpression, CompareWith, ValidationGroup, and validation-indicator placement.

The provider evaluates the configured rules, displays errors through the familiar ErrorProvider icon, and returns a single Boolean result. This removes repeated If blocks from Save and Confirm buttons while keeping each field's rules close to that field in the designer.

Because ValidationProvider inherits from ErrorProvider, inherited settings such as Icon, BlinkStyle, IconAlignment, IconPadding, and ContainerControl remain available. The provider also adds per-field indicator placement so feedback can be displayed relative to a different control.

Key features

• Non-visual component with designer extender properties on every control.
• Required-value validation for text, selection, date, numeric, Boolean, and collection values.
• Minimum- and maximum-length rules.
• Regular-expression validation with a one-second safety timeout.
• MaskedTextBox.MaskCompleted validation.
• Value comparison between two controls, useful for password and e-mail confirmation.
• Named validation groups for multi-step forms and tabbed screens.
• Automatic validation during each control's Validating event.
• Optional focus cancellation for invalid fields.
• Optional focus on the first invalid control after batch validation.
• Automatic clearing of stale feedback as values change.
• Configurable participation of disabled and hidden controls.
• Custom display names and fully configurable default messages.
• Application-defined value resolution and custom validation rules through events.
• Explicit inclusion of controls that use custom-only validation rules.
• Nested value paths for custom controls, such as Frozen.IsFrozen.
• Per-control validation results and complete batch results.
• Designer-configurable validation indicator control, alignment, and padding per validated field.
• Configurable validation icon through the inherited Icon property and the provider smart tag.
• Smart-tag actions for the most common provider settings.
• XML documentation and NuGet symbol generation.

Requirements

• Windows Forms
• .NET 8 for Windows (net8.0-windows)
• A reference to CoreSuite.ValidationProvider

The component has no runtime dependency on another CoreSuite package.

Installation

dotnet add package CoreSuite.ValidationProvider

Or add ValidationProvider/ValidationProvider.vbproj as a project reference when working directly with the CoreSuite solution.

Quick start

Add ValidationProvider to the form through the toolbox. The designer associates its inherited ContainerControl property with the form and adds validation properties to the other controls.

Configure the fields in the designer or in code:

Imports CoreSuite.Controls
Private Sub ConfigureValidation()
    ValidationProvider1.SetRequired(NameTextBox, True)
    ValidationProvider1.SetValidationDisplayName(NameTextBox, "Name")
    ValidationProvider1.SetMinimumLength(NameTextBox, 3)
    ValidationProvider1.SetRequired(EmailTextBox, True)
    ValidationProvider1.SetValidationDisplayName(EmailTextBox, "E-mail")
    ValidationProvider1.SetRegularExpression(EmailTextBox, "^[^@\s]+@[^@\s]+\.[^@\s]+$")
End Sub

Validate before saving:

Private Sub SaveButton_Click(Sender As Object, E As EventArgs) Handles SaveButton.Click
    If Not ValidationProvider1.Validate() Then Return
    SaveCustomer()
End Sub

When validation fails, the provider focuses the first invalid control by default and displays its message using the inherited ErrorProvider icon.

Designer extender properties

These properties appear under the ValidationProvider category of every control on the form.

The designer serializes these settings through methods such as:

ValidationProvider1.SetRequired(NameTextBox, True)
ValidationProvider1.SetValidationGroup(NameTextBox, "Customer")

Validation indicator placement

Validation rules, focus behavior, events, and ValidationResult.TargetControl always remain associated with the validated control. The visual feedback can be redirected to another control through ValidationIndicatorControl.

This is useful for layouts where an input reaches the edge of the form and the error icon should appear beside a label instead:

ValidationProvider1.SetRequired(NameTextBox, True)
ValidationProvider1.SetValidationDisplayName(NameTextBox, "Name")
ValidationProvider1.SetValidationIndicatorControl(NameTextBox, NameLabel)
ValidationProvider1.SetValidationIndicatorAlignment(NameTextBox, ErrorIconAlignment.MiddleRight)
ValidationProvider1.SetValidationIndicatorPadding(NameTextBox, 5)

All three indicator properties are extender properties and can be configured directly from the Windows Forms designer by selecting the validated control. In the example above, NameTextBox is still the field that is validated and receives focus when invalid, while the icon and tooltip are displayed relative to NameLabel.

Use a different indicator control for each field when multiple validation errors must remain visible at the same time.

The provider inherits the standard ErrorProvider.Icon property, so a custom .ico can be selected from the Properties window. Icon is also exposed in the provider smart tag for faster design-time access.

Validation groups

Groups allow one provider to validate independent sections of the same form.

ValidationProvider1.SetValidationGroup(NameTextBox, "Customer")
ValidationProvider1.SetValidationGroup(EmailTextBox, "Customer")
ValidationProvider1.SetValidationGroup(CardNumberTextBox, "Payment")

Validate only the current section:

If Not ValidationProvider1.ValidateGroup("Customer") Then Return

Group names are compared without case sensitivity. Calling ValidateGroup(String.Empty) validates configured controls that do not belong to a named group.

Compare two fields

CompareWith compares the represented text of both controls. It is useful for confirmation fields:

ValidationProvider1.SetRequired(PasswordTextBox, True)
ValidationProvider1.SetRequired(ConfirmPasswordTextBox, True)
ValidationProvider1.SetCompareWith(ConfirmPasswordTextBox, PasswordTextBox)
ValidationProvider1.SetValidationDisplayName(ConfirmPasswordTextBox, "Password confirmation")

Comparison is case-sensitive by default. Set CaseSensitiveComparison to False for values where character casing is not significant.

Custom messages and localization

Set ValidationMessage when one control needs a specific message:

ValidationProvider1.SetValidationMessage(NameTextBox, "Enter the customer's full name.")

The provider also exposes default message templates:

This allows the component to be fully localized without changing its source code:

ValidationProvider1.RequiredErrorMessage = "{0} é obrigatório."
ValidationProvider1.InvalidFormatErrorMessage = "O formato de {0} é inválido."
ValidationProvider1.ComparisonErrorMessage = "{0} deve ser igual a {1}."

Automatic validation

AutomaticValidation is enabled by default. Each configured control is validated when its Validating event occurs, normally when focus moves to another control.

CancelValidationOnError is disabled by default so users are not trapped in a field. Enable it only when the form workflow should prevent focus from leaving invalid input.

Custom validation rules

Handle ValidatingControl for business rules that cannot be represented by the built-in properties:

Private Sub ConfigureUserNameValidation()
    ValidationProvider1.SetCustomValidationEnabled(UserNameTextBox, True)
End Sub
Private Sub ValidationProvider1_ValidatingControl(Sender As Object, E As ValidatingControlEventArgs) Handles ValidationProvider1.ValidatingControl
    If E.TargetControl Is UserNameTextBox AndAlso String.Equals(CStr(E.Value), "admin", StringComparison.OrdinalIgnoreCase) Then
        E.IsValid = False
        E.FailureReason = ValidationFailureReason.Custom
        E.ErrorMessage = "This user name is reserved."
    End If
End Sub

The event receives the result of the built-in rules. A handler may reject an otherwise valid value, replace the error message, or accept a built-in failure when application logic explicitly permits it.

Custom value resolution

The provider automatically recognizes common WinForms values:

• Text for text-based controls.
• SelectedValue or selection state for list controls.
• Checked for check boxes and radio buttons.
• Value for DateTimePicker, NumericUpDown, and compatible custom controls.
• HasDate, HasTime, HasDateTime, or HasValue when exposed by a custom control.
• Checked item collections for CheckedListBox.

Use ValuePropertyName when the desired value is exposed through another property:

ValidationProvider1.SetRequired(CustomerQueriedBox, True)
ValidationProvider1.SetValuePropertyName(CustomerQueriedBox, "Frozen.IsFrozen")

Dot-separated nested paths are supported. A missing property is treated as a configuration error and raises InvalidOperationException, making misspelled paths visible during testing.

For controls that need code-based resolution, handle ValidationValueRequested:

Private Sub ValidationProvider1_ValidationValueRequested(Sender As Object, E As ValidationValueRequestedEventArgs) Handles ValidationProvider1.ValidationValueRequested
    If E.TargetControl Is TagsControl Then
        E.Value = TagsControl.SelectedTags
        E.Handled = True
    End If
End Sub

CoreSuite control integration

The package remains independent from other CoreSuite projects, but its convention-based value resolution supports them naturally.

Methods

Disabled and hidden controls are excluded by default. Change ValidateDisabledControls or ValidateHiddenControls when those controls must participate.

Events and results

Private Sub ValidationProvider1_ValidationCompleted(Sender As Object, E As ValidationCompletedEventArgs) Handles ValidationProvider1.ValidationCompleted
    StatusLabel.Text = If(E.IsValid, "Ready to save", $"{E.InvalidControlCount} invalid field(s)")
End Sub

Each ValidationResult contains the target control, group name, final message, validity, and a ValidationFailureReason value.

ErrorProvider appearance

Because the component inherits ErrorProvider, standard appearance configuration remains available:

ValidationProvider1.BlinkStyle = ErrorBlinkStyle.NeverBlink
ValidationProvider1.SetIconAlignment(NameTextBox, ErrorIconAlignment.MiddleRight)
ValidationProvider1.SetIconPadding(NameTextBox, 4)

License

CoreSuite is licensed under the MIT License.