Core API
Contracts
| Type | Purpose |
|---|---|
IValidator<T> |
Combined sync + async validator. |
ISyncValidator<T> |
Validate(instance) and Validate(instance, ruleSets). |
IAsyncValidator<T> |
ValidateAsync(instance, cancellationToken) and the rule-set overload. |
IValidationOptionsValidator<T> |
Executes a validator with ValidationCallOptions; implemented by fluent and generated validators. |
IValidatorSelector |
Per-call top-level rule selection; DefaultValidatorSelector, RulesetValidatorSelector, and CompositeValidatorSelector are built in. |
IValidationContextValidator<T> |
Executes a validator with an inherited ValidationContext<T>; used by nested, collection, and included validators. |
InheritanceValidator<T> |
Dispatches validation to the validator registered for the actual runtime type. |
IValidationDescriptorProvider |
Describe() metadata. |
IValidationDescriptor |
ValidatorName, ValidatedType, Members, RulesForMember. |
IValidationMemberDescriptor |
Name, Rules. |
IValidationRuleDescriptor |
Kind, MessageKey, Severity, ErrorCode, DisplayName, CustomState, HasCondition, Parameters. |
Value types
ValidationResult is a readonly struct:
public readonly struct ValidationResult
{
public bool IsValid { get; }
public IReadOnlyList<ValidationError> Errors { get; }
public static ValidationResult Success { get; }
public static ValidationResult FromErrors(ValidationErrorCollector errors);
}
ValidationError:
| Member | Type |
|---|---|
MemberName |
string |
MessageId |
MessageId |
MessageKey |
string? |
MessageParameters |
IDictionary<string, object>? |
Message |
string? |
ErrorCode |
string? |
Severity |
ValidationErrorSeverity |
CustomState |
object? |
Fluent API
public abstract class Validator<T> : ValidatorDefinition<T>, IValidator<T>
{
protected abstract void Configure(ValidatorRuleBuilder<T> builder);
public ValidationResult Validate(T instance);
public ValidationResult Validate(T instance, IEnumerable<string> ruleSets);
public ValidationResult Validate(T instance, ValidationCallOptions options);
public ValueTask<ValidationResult> ValidateAsync(T instance, CancellationToken cancellationToken = default);
public void ValidateAndThrow(T instance);
public ValueTask ValidateAndThrowAsync(T instance, CancellationToken cancellationToken = default);
}
ValidatorRuleBuilder<T> exposes RuleFor, RuleSet, Include, When/Unless, and async group
variants. IRuleBuilder<T, TProperty> exposes WithState(object?) and context-aware
WithState(Func<T, TProperty, ValidationContext<T>, TState>) overloads. Validator<T> exposes a
protected OnRuleAdded(IRuleDefinition) hook, and IRuleDefinitionOptions lets the hook change the
default message, error code, and severity. ValidationPath.GetParent, IsChildOf, and
GetParentChain handle member and indexer chains. The PropertyChain readonly record struct wraps a
path with FromPath, Add, GetParentChain, and IsChildChainOf for advanced rule authors.
Execution options
public sealed record ValidationCallOptions
{
public IEnumerable<string>? RuleSets { get; init; }
public bool IncludeAllRuleSets { get; init; }
public bool ThrowOnFailures { get; init; }
public CascadeMode? CascadeMode { get; init; }
public bool FailFast { get; init; }
public IReadOnlyCollection<string>? IncludeProperties { get; init; }
public IReadOnlyCollection<string>? ExcludeProperties { get; init; }
public IReadOnlyCollection<string>? ExcludeRuleSets { get; init; }
public IServiceProvider? ServiceProvider { get; init; }
}
RuleSets = null or an empty collection runs all rules, including named sets. Use ["default"] for
ungrouped rules only, or IncludeAllRuleSets = true to select every named set explicitly.
ThrowOnFailures = true throws ValidationException with all collected errors.
ValidationStrategy is the chained builder equivalent and adds IncludeAllRuleSets(),
IncludeRulesNotInRuleSet(), and ThrowOnFailures().
Both fluent (Validator<T>) and generated ([Validate]) validators implement
IValidationOptionsValidator<T>, so options, fail-fast, property/rule-set filtering, and
ClassLevelCascadeMode behave identically on both paths. ValidationOptionsExtensions exposes
the same overloads on IValidator<T> plus ValidateAndThrow/ValidateAndThrowAsync. A custom
validator that does not implement IValidationOptionsValidator<T> throws NotSupportedException
when options are supplied; the basic overloads continue to work.
Both paths also implement IValidationContextValidator<T>. Nested (SetValidator), collection
(ForEach), and included (Include) validators receive the parent context: Root,
RootData, ServiceProvider, RuleSets, FailFast, and the current MemberPath. Error fields
(MessageKey, MessageParameters, ErrorCode, Severity, CustomState) survive the boundary.
Exceptions
| Exception | When |
|---|---|
ValidationException |
ValidateAndThrow / ValidateAndThrowAsync; carries Errors. |
AsyncValidatorInvokedSynchronouslyException |
Sync Validate on an async-only validator. |
ValidationAssertionException |
Assertion helpers. |
Configuration
services.AddValidation(options => options with { ... }) registers container-scoped options:
DefaultCascadeMode/DefaultRuleLevelCascadeMode, DefaultClassLevelCascadeMode,
DisplayNameResolver, DisplayNameResolverForInstance, PropertyNameResolver,
ValidatorFactory. ASP.NET Core filters and any call that supplies
ValidationCallOptions.ServiceProvider use the container instance, so multiple containers in one
process stay isolated. The instance-aware resolver receives (Type, memberName, instance) and
takes precedence over the legacy resolver when it returns a non-empty name.
PropertyNameResolver changes the code-facing ValidationError.MemberName for rules without an
explicit override. ValidationConfiguration.CreateValidator<T>(services) asks ValidatorFactory
for a validator when DI has no IValidator<T> registration.
ValidationConfiguration.Configure(options => options with { ... }) remains the process-wide
fallback used when no service provider is available (for example direct new construction in a
unit test).