Class Empty

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

Inheritance

System.Object

Empty

Implements

IRuleWithMessage<System.Collections.ICollection>

IRule<System.Collections.ICollection>

IGetsFailureMessage<System.Collections.ICollection>

IRuleWithMessage<System.Collections.IEnumerable>

IRule<System.Collections.IEnumerable>

IGetsFailureMessage<System.Collections.IEnumerable>

IRuleWithMessage<System.Array>

IRule<System.Array>

IGetsFailureMessage<System.Array>

IRuleWithMessage<System.String>

IRule<System.String>

IGetsFailureMessage<System.String>

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 : IRuleWithMessage<ICollection>, IRule<ICollection>, IGetsFailureMessage<ICollection>, IRuleWithMessage<IEnumerable>, IRule<IEnumerable>, IGetsFailureMessage<IEnumerable>, IRuleWithMessage<Array>, IRule<Array>, IGetsFailureMessage<Array>, IRuleWithMessage<string>, IRule<string>, IGetsFailureMessage<string>

Remarks

For a validated object which implements the non-generic System.Collections.ICollection, this validation rule makes use of the System.Collections.ICollection.Count property. For a validated object which derives from System.Array or is a System.String, this validation rule makes use of the System.Array.Length or System.String.Length property.

For an object which is simply System.Collections.IEnumerable, this validation rule will get and make use of the enumerator once, attempting to read a single item from the enumeration. This rule will return a pass result if System.Collections.IEnumerator.MoveNext returns false.

In some cases enumerating an enumerable in this way will not have undesirable consequences; for some implementations of System.Collections.IEnumerable though, it could. By way of an example of a common mistake, consider when using an System.Linq.IQueryable<T> which comes from an ORM such as Entity Framework or NHibernate. Whilst the generic queryable interface does implement the non-generic enumerable interface and this rule would operate with the correct results, it is not recommended to use it in this way. If a Linq queryable which comes from an ORM is treated as System.Collections.IEnumerable, enumerating it will cause that ORM to execute the full query in the database and load/fetch all of the results, similar to a SELECT * FROM .... This could incur significant performance degradation.

If treating the validated value as non-generic System.Collections.IEnumerable and enumerating it is unacceptable, it is recommended to use the generic Empty<T> rule instead. The generic rule works with System.Linq.IQueryable<T> in a way that avoids enumerating it as described above and thus provides superior performance when used with an ORM.

Note that when using this class to provide a failure message for an System.Collections.IEnumerable, the failure message will not indicate the actual count of elements exposed by the enumerable instance. This is for both performance reasons and because the System.Collections.IEnumerable interface does not guarantee that the collection is finite.

This rule will always return a synchronous result.

Methods

GetFailureMessageAsync(Array, ValidationRuleResult, CancellationToken)

Gets the validation failure message for the specified result.

Declaration

public ValueTask<string> GetFailureMessageAsync(Array value, ValidationRuleResult result, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
System.Array	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.

GetFailureMessageAsync(ICollection, ValidationRuleResult, CancellationToken)

Gets the validation failure message for the specified result.

Declaration

public ValueTask<string> GetFailureMessageAsync(ICollection value, ValidationRuleResult result, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
System.Collections.ICollection	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.

GetFailureMessageAsync(IEnumerable, ValidationRuleResult, CancellationToken)

Gets the validation failure message for the specified result.

Declaration

public ValueTask<string> GetFailureMessageAsync(IEnumerable value, ValidationRuleResult result, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
System.Collections.IEnumerable	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.

GetFailureMessageAsync(String, ValidationRuleResult, CancellationToken)

Gets the validation failure message for the specified result.

Declaration

public ValueTask<string> GetFailureMessageAsync(string value, ValidationRuleResult result, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
System.String	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.

GetResultAsync(Array, RuleContext, CancellationToken)

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

Declaration

public ValueTask<RuleResult> GetResultAsync(Array validated, RuleContext context, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
System.Array	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

GetResultAsync(ICollection, RuleContext, CancellationToken)

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

Declaration

public ValueTask<RuleResult> GetResultAsync(ICollection validated, RuleContext context, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
System.Collections.ICollection	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

GetResultAsync(IEnumerable, RuleContext, CancellationToken)

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

Declaration

public ValueTask<RuleResult> GetResultAsync(IEnumerable validated, RuleContext context, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
System.Collections.IEnumerable	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

GetResultAsync(String, RuleContext, CancellationToken)

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

Declaration

public ValueTask<RuleResult> GetResultAsync(string validated, RuleContext context, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
System.String	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

Implements

IRuleWithMessage<TValidated>

IRule<TValidated>

IGetsFailureMessage<TValidated>

IRuleWithMessage<TValidated>

IRule<TValidated>

IGetsFailureMessage<TValidated>

IRuleWithMessage<TValidated>

IRule<TValidated>

IGetsFailureMessage<TValidated>

IRuleWithMessage<TValidated>

IRule<TValidated>

IGetsFailureMessage<TValidated>