Class MatchesRegex

A rule which passes if the validated string is either null or is a match for the specified regular expression.

Inheritance

System.Object

MatchesRegex

Implements

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 MatchesRegex : IRuleWithMessage<string>, IRule<string>, IGetsFailureMessage<string>

Remarks

The Pattern property upon this rule must be set before the rule is used. Specifying RegexOptions is optional, as this property is initialised to System.Text.RegularExpressions.RegexOptions.None by default.

This rule will pass if the validated string is null. Combine this rule with NotNull if null strings are not permitted.

This rule will always return a synchronous result.

Properties

ExecutionTimeout

Gets or sets a timeout for the evaluation of the regular expression match.

Declaration

public TimeSpan ExecutionTimeout { get; set; }

Property Value

Type	Description
System.TimeSpan

Remarks

It is considered a potential security risk (DoS) to evaluate a regular expression without any timeout. An attacker could send maliciously-crafted data to force the regular expression engine to perform a lot of work and degrade system performance.

The default timeout is 50 milliseconds, which should be more than ample for matching typical regular expressions. If this is insufficient or if your own use-case expects a much faster match then you may alter this property or you may instead alter ExecutionTimeoutMs. Both of these two properties control the same underlying value. If, for example, you are using the Manifest Model then you may find the ExecutionTimeoutMs property easier to maintiain using a serializable value.

For more information and an example of such an attack, see https://www.regular-expressions.info/catastrophic.html. Another mitigation technique would be to include NonBacktracking amongst the RegexOptions. The non-backtracking option is only available from .NET 7 and onward, though.

See Also

ExecutionTimeoutMs

ExecutionTimeoutMs

Gets or sets a representation of ExecutionTimeout using only a number of milliseconds.

Declaration

public double ExecutionTimeoutMs { get; set; }

Property Value

Type	Description
System.Double

Remarks

It is considered a potential security risk (DoS) to evaluate a regular expression without any timeout. An attacker could send maliciously-crafted data to force the regular expression engine to perform a lot of work and degrade system performance.

The default timeout is 50 milliseconds, which should be more than ample for matching typical regular expressions. If this is insufficient or if your own use-case expects a much faster match then you may alter this property or you may instead alter ExecutionTimeout. Both of these two properties control the same underlying value. If, for example, you are using the Manifest Model then you may find this property easier to maintiain using a serializable value.

For more information and an example of such an attack, see https://www.regular-expressions.info/catastrophic.html. Another mitigation technique would be to include NonBacktracking amongst the RegexOptions. The non-backtracking option is only available from .NET 7 and onward, though.

See Also

ExecutionTimeout

Pattern

Gets or sets the regular expression pattern.

Declaration

public string Pattern { get; set; }

Property Value

Type	Description
System.String

Remarks

This property is mandatory when using this rule. If it is unset/has a value of null when the rule is executed then this rule will raise an exception.

RegexOptions

Gets or sets the regular expression options to be used in the match.

Declaration

public RegexOptions RegexOptions { get; set; }

Property Value

Type	Description
System.Text.RegularExpressions.RegexOptions

Remarks

This property defaults to a value of System.Text.RegularExpressions.RegexOptions.None.

If you are using .NET 7 or newer and your Pattern does not require regular expression backtracking then consider adding NonBacktracking to your options, to prevent a potential DoS attack upon the regular expression engine. For more information see the documentation comments upon the ExecutionTimeout property.

Methods

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(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>