Interface IRule<TValue, TParent>

A service for a validation rule which validates a value of a specified type and also makes use of a contextual 'parent' value, typically the object from which the first value was retrieved.

Namespace: CSF.Validation.Rules

Assembly: CSF.Validation.Abstractions.dll

Syntax

public interface IRule<in TValue, in TParent>

Type Parameters

Name	Description
TValue	The type of the value which this rule validates
TParent	The type of the parent value used by this rule

Remarks

A validation rule should be a single piece of logic which tests a value against a business rule/requirement to determine whether it is valid according to that business rule or not. Whilst it is possible to write dependencies between validation rules (EG: Don't run this rule if that other rule failed), validation rules should aim to be as independent as possible.

Both generic types of this interface are contravariant. That means that (for example) an IRule<Animal,Person> may be used as if it were an IRule<Dog,Customer>.

Rules run until they complete and in the majority of cases this is not a problem. When designing a rule class which has the potential to be long-running then there are a few best practices to consider, as noted in the article linked below. One of these is that you should consider implementing IHasRuleTimeout.

You are encouraged to read more at the documentation for writing rule classes & best practices for writing rules.

Methods

GetResultAsync(TValue, TParent, RuleContext, CancellationToken)

Performs the validation logic asynchronously and returns a task of RuleResult.

Declaration

ValueTask<RuleResult> GetResultAsync(TValue value, TParent parentValue, RuleContext context, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
TValue	value	The value being validated
TParent	parentValue	The parent value
RuleContext	context	Contextual information about the validation
System.Threading.CancellationToken	token	An object which may be used to cancel the process

Returns

Type	Description
System.Threading.Tasks.ValueTask<RuleResult>	A task which provides a result object, indicating the result of validation

Remarks

This method receives the value to be validated as well as an object which represents the context in which this rule is running. It should return a task of RuleResult.

In order to create the result object, particularly if your rule logic will run synchronously, consider using the CommonResults class via using static CSF.Validation.Rules.CommonResults; in your rule logic. The common results class has helper methods such as PassAsync(IDictionary<String, Object>) and FailAsync(IDictionary<String, Object>) which include optimisations for flyweight task instances that avoid allocating additional resources needlessly.

It is acceptable to throw an uncaught exception from this method, as the validation framework will catch it and automatically convert it into an error result. Generally, developers do not need to manually return a result of outcome Errored manually. This would be appropriate only in an unusual scenario that is considered an error, but which does not involve the throwing of an exception. Error results are generally harder for the consumer to deal with than failure results.

The context parameter may be used, amongst other things, to access 'ancestor' values.

Exceptions

Type	Condition
System.Exception	This method may raise any exception type