Class Empty<T>

A validation rule which passes if the value being validated is either null or is a collection that has no items.

Inheritance
System.Object
Empty<T>
Implements
IRuleWithMessage<System.Collections.Generic.ICollection<T>>
IRule<System.Collections.Generic.ICollection<T>>
IGetsFailureMessage<System.Collections.Generic.ICollection<T>>
IRuleWithMessage<System.Collections.Generic.IReadOnlyCollection<T>>
IRule<System.Collections.Generic.IReadOnlyCollection<T>>
IGetsFailureMessage<System.Collections.Generic.IReadOnlyCollection<T>>
IRuleWithMessage<System.Linq.IQueryable<T>>
IRule<System.Linq.IQueryable<T>>
IGetsFailureMessage<System.Linq.IQueryable<T>>
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: CSF.Validation.Rules
Assembly: CSF.Validation.StandardRules.dll
Syntax
public class Empty<T> : IRuleWithMessage<ICollection<T>>, IRule<ICollection<T>>, IGetsFailureMessage<ICollection<T>>, IRuleWithMessage<IReadOnlyCollection<T>>, IRule<IReadOnlyCollection<T>>, IGetsFailureMessage<IReadOnlyCollection<T>>, IRuleWithMessage<IQueryable<T>>, IRule<IQueryable<T>>, IGetsFailureMessage<IQueryable<T>>
Type Parameters
Name Description
T
Remarks

This rule is very similar to the non-generic Empty rule in that it passes if the collection itself is either null or has no items. This generic rule avoids some of the disadvantages of the non-generic empty rule. The disadvantage of this rule is that the generic type of the collection items must be specified. This can make this rule more difficult to use it with The Manifest Model, which requires all rule types to be specified as a string (where it is more difficult to consisely specify generic types).

This rule will never enumerate the collection when operating upon any validated value which implements any of the following interfaces.

  • System.Collections.Generic.ICollection<T>
  • System.Collections.Generic.IReadOnlyCollection<T>
  • System.Collections.Generic.IList<T>
  • System.Collections.Generic.IReadOnlyList<T> (by virtue of implementing System.Collections.Generic.IReadOnlyCollection<T>)

This rule may also be used with a Linq System.Linq.IQueryable<T> without treating it as simply System.Collections.IEnumerable (and thus enumerating it). When operating upon a queryable, this rule makes use of the Linq Any() extension method. This makes it friendly to systems such as ORMs and other implementations of queryable, without causing undesirable side-effects such as performance degradation.

Note that when using this class to provide a failure message for an System.Linq.IQueryable<T>, the failure message will not indicate the actual count of elements exposed by the queryable. This is for performance reasons; the validation rule makes use of System.Linq.Queryable.Any``1(System.Linq.IQueryable{``0}), which does not read the count from the queryable, only determines if at least one element is present. The message-generation logic does not further interrogate the queryable, as doing so may incur further undesired computational cost.

If you do not wish to (or cannot) specify the generic type of the validated value then you may instead use the non-generic Empty rule.

This rule will always return a synchronous result.

Methods

| Improve this Doc View Source

GetFailureMessageAsync(ICollection<T>, ValidationRuleResult, CancellationToken)

Gets the validation failure message for the specified result.

Declaration
public ValueTask<string> GetFailureMessageAsync(ICollection<T> value, ValidationRuleResult result, CancellationToken token = default(CancellationToken))
Parameters
Type Name Description
System.Collections.Generic.ICollection<T> value
ValidationRuleResult result

A validation result, typically indicating failure.
System.Threading.CancellationToken token

An optional cancellation token.
Returns
Type Description
System.Threading.Tasks.ValueTask<System.String>

A human-readable message.
| Improve this Doc View Source

GetFailureMessageAsync(IReadOnlyCollection<T>, ValidationRuleResult, CancellationToken)

Gets the validation failure message for the specified result.

Declaration
public ValueTask<string> GetFailureMessageAsync(IReadOnlyCollection<T> value, ValidationRuleResult result, CancellationToken token = default(CancellationToken))
Parameters
Type Name Description
System.Collections.Generic.IReadOnlyCollection<T> value
ValidationRuleResult result

A validation result, typically indicating failure.
System.Threading.CancellationToken token

An optional cancellation token.
Returns
Type Description
System.Threading.Tasks.ValueTask<System.String>

A human-readable message.
| Improve this Doc View Source

GetFailureMessageAsync(IQueryable<T>, ValidationRuleResult, CancellationToken)

Gets the validation failure message for the specified result.

Declaration
public ValueTask<string> GetFailureMessageAsync(IQueryable<T> value, ValidationRuleResult result, CancellationToken token = default(CancellationToken))
Parameters
Type Name Description
System.Linq.IQueryable<T> value
ValidationRuleResult result

A validation result, typically indicating failure.
System.Threading.CancellationToken token

An optional cancellation token.
Returns
Type Description
System.Threading.Tasks.ValueTask<System.String>

A human-readable message.
| Improve this Doc View Source

GetResultAsync(ICollection<T>, RuleContext, CancellationToken)

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

Declaration
public ValueTask<RuleResult> GetResultAsync(ICollection<T> validated, RuleContext context, CancellationToken token = default(CancellationToken))
Parameters
Type Name Description
System.Collections.Generic.ICollection<T> validated
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. However, if this rule only needs access to an immediate parent value then consider using IRule<TValue, TParent> instead.

Exceptions
Type Condition
System.Exception

This method may raise any exception type
| Improve this Doc View Source

GetResultAsync(IQueryable<T>, RuleContext, CancellationToken)

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

Declaration
public ValueTask<RuleResult> GetResultAsync(IQueryable<T> validated, RuleContext context, CancellationToken token = default(CancellationToken))
Parameters
Type Name Description
System.Linq.IQueryable<T> validated
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. However, if this rule only needs access to an immediate parent value then consider using IRule<TValue, TParent> instead.

Exceptions
Type Condition
System.Exception

This method may raise any exception type

Explicit Interface Implementations

| Improve this Doc View Source

IRule<IReadOnlyCollection<T>>.GetResultAsync(IReadOnlyCollection<T>, RuleContext, CancellationToken)

Declaration
ValueTask<RuleResult> IRule<IReadOnlyCollection<T>>.GetResultAsync(IReadOnlyCollection<T> validated, RuleContext context, CancellationToken token)
Parameters
Type Name Description
System.Collections.Generic.IReadOnlyCollection<T> validated
RuleContext context
System.Threading.CancellationToken token
Returns
Type Description
System.Threading.Tasks.ValueTask<RuleResult>

Implements