CoreEx.Validation 4.0.0-preview-1

CoreEx.Validation

Provides a fluent, property-centric validation framework for .NET classes: composable rules, conditional clauses, strongly-typed error messages, and deep integration with the CoreEx execution and exception model.

Overview

CoreEx.Validation fills the gap between primitive data-annotation validation and a fully featured domain validation library. The framework is built around the concept of a Validator<TEntity> that owns a set of PropertyRule chains — one chain per property. Each chain is declared fluently using HasProperty/HasRuleFor, and individual rules are appended to the chain with extension methods defined in ValidationExtensions.

Every rule invoked on a property chain runs asynchronously and receives a PropertyContext<TEntity, TProperty> that carries the current entity, the resolved property value, the accumulated error list, and a reference to the owning ValidationContext<TEntity>. When a rule adds an error it does so through the context, which means all rules in the chain continue executing and all errors for all properties are collected before the framework decides to throw or return.

Validation is initiated by calling ValidateAsync on a validator instance and inspecting the returned IValidationContext<TEntity>, or by calling ValidateAndThrowAsync which converts errors to a CoreEx ValidationException automatically.

Motivation

• The standard .NET DataAnnotations model is attribute-only, non-composable, and cannot express cross-property rules or async checks cleanly.
• FluentValidation is a popular alternative but requires a separate NuGet dependency and has a different abstraction model; CoreEx.Validation integrates tightly with ExecutionContext, LText localisation, IValidatorEx, and the CoreEx exception hierarchy.
• Property rules and clauses are plain sealed classes; extension methods in ValidationExtensions are the only public API surface, making it trivial to discover and extend the rule set.
• Common validators (CommonValidator<TValue>) allow validation logic to be extracted from a specific entity and reused across validators without duplication.
• RuleSet<TEntity> groups multiple rules under a shared predicate, enabling scenario-specific validation blocks that only activate under defined conditions.

Key capabilities

• ✅ Fluent property-rule chains: properties are declared with HasProperty/HasRuleFor and rules are appended via extension methods; the chain executes every rule in order, collecting all errors before reporting.
• 📋 Rich built-in rule set: mandatory, string (length, regex), numeric, decimal/floating-point precision, between/range, comparison (value, property, values), enum, email, wildcard, null/none/empty, error, collection, dictionary, entity, common, reference data, and interop rules cover the vast majority of domain validation needs.
• 🧩 Conditional clauses: When/WhenValue/WhenHasValue and DependsOn clauses short-circuit a rule when a condition is not met, enabling context-sensitive rules without branching in the rule body.
• ⚡ Fully async: every rule and clause is async-capable; PredicateAsync<TEntity, TProperty> delegates allow awaiting external services within a clause.
• 🔧 Common and inline validators: CommonValidator<TValue> encapsulates reusable validation logic; InlineValidator<TValue> is the compositional base used by both CommonValidator and CommonRule.
• 📝 Localised error messages: every rule accepts an optional LText override; default messages are defined in ValidatorStrings and resolved through CoreEx localisation.
• 🔍 Context-aware property paths: PropertyContext tracks fully qualified property names (both .NET and JSON) so error messages map precisely to the correct field in API responses.
• 💬 RuleSet grouping: RuleSet<TEntity> collects a block of rules that only execute when a Predicate<ValidationContext<TEntity>> returns true.
• 🧩 Base-validator include: Validator<TEntity>/AbstractValidator<TEntity> and the fluent Include method allow a base validator to be composed into a derived validator.
• Interop bridge: InteropRule and the .Interop() extension forward validation to any IValidator/IValidator<T> (e.g. a FluentValidation validator) and merge errors into the CoreEx context.

Key types

Clauses

Clauses are conditional guards that run before the rule body. When a clause returns false the rule is skipped and no error is added. Clauses are appended to any IPropertyRule using the extension methods listed below.

Rules

Rules apply the actual validation logic to a property value. Each rule class is typically instantiated via the corresponding ValidationExtensions method(s). Rules inherit from PropertyRuleBase<TEntity, TProperty> and implement OnValidateAsync.

Namespaces

Related namespaces

• CoreEx - Defines ValidationException, MessageItem, IValidationResult, LText, ExecutionContext, and Wildcard consumed throughout.
• CoreEx.RefData - Provides IReferenceData and IReferenceDataCodeCollection validated by ReferenceDataRule, ReferenceDataCodeRule, and ReferenceDataCodeCollectionRule.
• CoreEx.AspNetCore - Converts ValidationException raised by ValidateAndThrowAsync into HTTP 400 responses with a structured error body.

AI Usage Guide

An AGENTS.md file is included with this package. AI coding assistants (GitHub Copilot, Claude, Cursor, etc.) that support workspace-injected package documentation will automatically surface concise usage guidance, code examples, and Do Not rules for this package without requiring a local CoreEx checkout.