Lifecycle Hooks
Fluent validators can run code before and after rule evaluation. Hooks are registered inside
Configure and are useful for loading context, short-circuiting, auditing, or shaping a failure.
Hook overview
| Hook | Path | When it runs | Return value |
|---|---|---|---|
PreValidate(Func<ValidationContext<T>, bool>) |
Sync and async | Before any rule. | false short-circuits with ValidationResult.Success. |
PreValidateAsync(Func<ValidationContext<T>, CancellationToken, ValueTask<bool>>) |
Async only | After PreValidate, before any rule. |
false short-circuits with success. |
OnFailure(Action<ValidationResult>) |
Sync and async | Once after rules, only when invalid. | — |
OnFailureAsync(Func<ValidationResult, CancellationToken, ValueTask>) |
Async only | After OnFailure, only when invalid. |
— |
A second registration of the same hook replaces the first.
Declarative hooks on generated validators
Attribute-driven validators can bind static methods on the model with [PreValidate] and
[OnFailure]:
using Jeninnet.Validation;
using Jeninnet.Validation.Attributes;
using Jeninnet.Validation.Core;
[Validate]
[PreValidate(nameof(BeforeValidate))]
[OnFailure(nameof(AfterFailure))]
public sealed class Order
{
[NotEmpty] public string? CustomerName { get; set; }
public static bool BeforeValidate(
Order instance,
ValidationContext<Order> context,
ValidationErrorCollector errors) {
if (instance.CustomerName == "blocked") {
errors.Add(nameof(CustomerName), "blocked");
return false;
}
return true;
}
public static void AfterFailure(ValidationResult result) {
// audit, metrics, or a domain event
}
}
PreValidateis static and returnsbool; it accepts(T, ValidationContext<T>)or(T, ValidationContext<T>, ValidationErrorCollector).OnFailureis staticvoid(ValidationResult)and runs once after the merged result is known to be invalid.- Errors added through the collector are merged with rule errors. Returning
falsestops rule evaluation; the collected errors still make the result invalid. - Generated validators call these hooks directly; no reflection is used. Declarative hooks have no
async variants—use fluent
PreValidateAsync/OnFailureAsyncfor async work.
Pre-validation
public sealed class OrderValidator : Validator<Order>
{
protected override void Configure(ValidatorRuleBuilder<Order> builder)
{
PreValidate(context =>
{
if (context.Instance.IsDeleted)
{
return false; // deleted orders are not validated
}
return true;
});
builder.RuleFor(x => x.CustomerName, nameof(Order.CustomerName)).NotEmpty();
}
}
When PreValidate returns false, the result is ValidationResult.Success and failure hooks do
not run. This is a deliberate “nothing to validate” signal, not an error.
The synchronous PreValidate runs on both paths. The async path runs it first, then
PreValidateAsync:
PreValidateAsync(async (context, cancellationToken) =>
{
var tenant = await LoadTenantAsync(context.Instance.TenantId, cancellationToken);
return tenant.IsActive;
});
If PreValidateAsync is configured, calling synchronous Validate throws
InvalidOperationException with a message telling you to call ValidateAsync. This is a different
exception from AsyncValidatorInvokedSynchronouslyException, which is about async rules.
Failure hooks
OnFailure(result =>
{
_audit.RecordFailure(result.Errors);
});
OnFailureAsync(async (result, cancellationToken) =>
{
await _metrics.RecordAsync(result.Errors.Count, cancellationToken);
});
OnFailureruns on both paths, after all errors are collected.OnFailureAsyncruns only on the async path, afterOnFailure.- Neither runs for a valid result or a short-circuited pre-validation.
ValidateAndThrowinvokes the hooks before throwing.
Context available to hooks
PreValidate receives a ValidationContext<T> with:
Instance— the root instance;MemberPath— empty at the root;RuleSetsandFailFast— the current call settings;Root,RootData, andServiceProvider— not populated for hooks.
If a pre-validation hook needs a service, inject it into the validator or perform the check inside a
custom rule where context.ServiceProvider is available.
Exceptions
A hook exception is wrapped in ValidationException with the original exception as InnerException:
try
{
validator.Validate(order);
}
catch (ValidationException exception) when (exception.InnerException is not null)
{
// A PreValidate or OnFailure hook failed.
}
OperationCanceledException is not wrapped; cancellation propagates to the caller.
Ordering summary
sync path: PreValidate -> rules -> OnFailure (if invalid)
async path: PreValidate -> PreValidateAsync -> sync rules -> async rules
-> OnFailure (if invalid) -> OnFailureAsync (if invalid)
Under FailFast or class-level Stop, a sync-phase failure skips the async phase; the failure hooks
still run for the errors that were collected.
When to use hooks
- PreValidate — skip validation for deleted, draft, or tenant-disabled entities; load cheap context that affects every rule.
- PreValidateAsync — load tenant/feature state from a service before validation.
- OnFailure — audit, metrics, or domain events; do not mutate the model.
- OnFailureAsync — async telemetry or notification after a failed validation.
For fluent validators, do not use hooks to add validation errors; use rules or Custom for that.
The declarative PreValidate overloads that accept a ValidationErrorCollector are the exception:
they exist to reject a request before rule evaluation with a precise member error.