RuleExtensions Class
Assembly: CodeEffects.Rule.Engine.dll
Namespace: CodeEffects.Rule.Engine
Summary
Provides a set of static methods for evaluating business rules against individual source objects and for filtering collections that implement one of the following interfaces: System.Collections.IEnumerable or System.Collections.Generic.IEnumerable<T>. These methods internally use either the Evaluator<TSource> or Evaluator class to apply business rules.
Syntax
public static class RuleExtensions
Each call creates a new evaluator, parses the ruleset and compiles its rules. That is convenient for a one-time evaluation. If you evaluate many objects against the same ruleset, create one Evaluator<TSource> and reuse it.
The Filter overload that selects a rule by its index in the ruleset is deprecated: use the overload that takes a ruleId instead. See Data Filtering.
Extension Methods
Evaluate<TSource>(..)
Returns: System.Boolean - Returns a Boolean value indicating the result of the rule evaluation: true if the evaluation succeeded; otherwise, false.
public static bool Evaluate<TSource>(this TSource source, string rulesetXml, string ruleId = null, GetRuleDelegate getRule = null)
Evaluates a rule from the specified ruleset against the given source object. This extension method serves as a shortcut for calling the Evaluator<TSource>.Evaluate(..) method. Use the Evaluator<TSource> class directly when executing multiple evaluations with the same ruleset, as the evaluator compiles rules once per instantiation.
Type Parameters
- TSource - The underlying source type of the object against which the rule is evaluated. It is inferred from the compile-time type of
source.
Parameters
- this source (
TSource) - Specifies the object to be evaluated. This object serves as the data source for the rule. A System.ArgumentNullException is thrown if it is null.
- rulesetXml (
System.String) - The Rule XML document as a string.
- ruleId (
System.String) - Specifies an optional ID of the rule to be evaluated. If the ruleset contains multiple rules, you can evaluate a specific rule by providing its ID. Do not confuse this with external rules referenced within other rules. The specified rule must exist as a top-level rule within the ruleset; otherwise, an exception is thrown. The default value is null, which selects the first rule of the ruleset.
- getRule (
CodeEffects.Rule.Common.Models.GetRuleDelegate) - Specifies a delegate to a method used for retrieving external rules referenced by other rules. If this parameter is null, the evaluator attempts to locate any referenced rules within the ruleset itself. If no referenced rules are found, an exception is thrown. The default value is null.
Example
// Patient is your source object class, rulesetXml holds the Rule XML
var patient = new Patient { Age = 42 };
bool first = patient.Evaluate(rulesetXml); // the first rule of the ruleset
bool byId = patient.Evaluate(rulesetXml, "your-rule-id"); // a specific rule
Evaluate<TSource>(..)
Returns: System.Boolean - Returns a Boolean value indicating the result of the rule evaluation: true if the evaluation succeeded; otherwise, false.
public static bool Evaluate<TSource>(this TSource source, string rulesetXml, int ruleIndex, GetRuleDelegate getRule)
Evaluates the rule at the specified zero-based index of the ruleset against the given source object. This extension method serves as a shortcut for calling the Evaluator<TSource>.Evaluate(..) method. Use the Evaluator<TSource> class directly when executing multiple evaluations with the same ruleset, as the evaluator compiles rules once per instantiation.
Type Parameters
- TSource - The underlying source type of the object against which the rule is evaluated. It is inferred from the compile-time type of
source.
Parameters
- this source (
TSource) - Specifies the object to be evaluated. This object serves as the data source for the rule. A System.ArgumentNullException is thrown if it is null.
- rulesetXml (
System.String) - The Rule XML document as a string.
- ruleIndex (
System.Int32) - Specifies the zero-based index of the rule to be executed. Do not confuse this with external rules referenced within other rules. The specified rule must exist as a top-level rule within the ruleset; otherwise, an exception is thrown.
- getRule (
CodeEffects.Rule.Common.Models.GetRuleDelegate) - Specifies a delegate to a method used for retrieving external rules referenced by other rules. If this parameter is null, the evaluator attempts to locate any referenced rules within the ruleset itself. If no referenced rules are found, an exception is thrown. This parameter has no default value; pass null if you do not need it.
Example
bool second = patient.Evaluate(rulesetXml, 1, null); // the second rule of the ruleset
Filter<TSource>(..)
Returns: System.Collections.Generic.IEnumerable<TSource> - Returns a new collection that contains all source objects that satisfied the rule evaluation.
public static IEnumerable<TSource> Filter<TSource>(this IEnumerable<TSource> source, string rulesetXml, string ruleId = null, GetRuleDelegate getRule = null)
Filters a collection of source objects by applying a business rule. The specified ruleset Xml is loaded into the Evaluator class, where its rules are compiled and stored in memory. The evaluator then applies the rule named by ruleId, or the first rule of the ruleset, to each object in the collection. Source objects that satisfy the rule are returned as a new collection.
Type Parameters
- TSource - The underlying source type of the collection.
Parameters
- this source (
System.Collections.Generic.IEnumerable<TSource>) - Specifies the collection to be filtered.
- rulesetXml (
System.String) - The Rule XML document as a string to be evaluated against source objects.
- ruleId (
System.String) - An optional ID of a rule. If the ruleset contains multiple rules, you can apply a specific rule by providing its ID. The default value is null, which selects the first rule of the ruleset.
- getRule (
CodeEffects.Rule.Common.Models.GetRuleDelegate) - Specifies a delegate to a method used for retrieving external rules referenced by other rules. If this parameter is null, the evaluator attempts to locate any referenced rules within the ruleset itself. If no referenced rules are found, an exception is thrown. The default value is null.
Example
List<Patient> patients = GetPatients();
IEnumerable<Patient> adults = patients.Filter(rulesetXml);
Filter<TSource>(..)
Returns: System.Collections.Generic.IEnumerable<TSource> - Returns a new collection that contains all source objects that satisfied the rule evaluation.
public static IEnumerable<TSource> Filter<TSource>(this IEnumerable<TSource> source, string rulesetXml, int ruleIndex, GetRuleDelegate getRule = null)
Deprecated. Consider using a Filter overload with the ruleId parameter instead.
Filters a collection of source objects by applying the rule at the specified zero-based index of the ruleset.
Type Parameters
- TSource - The underlying source type of the collection.
Parameters
- this source (
System.Collections.Generic.IEnumerable<TSource>) - Specifies the collection to be filtered.
- rulesetXml (
System.String) - The Rule XML document as a string to be evaluated against source objects.
- ruleIndex (
System.Int32) - Specifies the zero-based index of the rule to be executed. Do not confuse this with external rules referenced within other rules. The specified rule must exist as a top-level rule within the ruleset; otherwise, an exception is thrown.
- getRule (
CodeEffects.Rule.Common.Models.GetRuleDelegate) - Specifies a delegate to a method used for retrieving external rules referenced by other rules. If this parameter is null, the evaluator attempts to locate any referenced rules within the ruleset itself. If no referenced rules are found, an exception is thrown. The default value is null.
Filter(..)
Returns: System.Collections.IEnumerable - Returns a new collection that contains all source objects that satisfied the rule evaluation.
public static IEnumerable Filter(this IEnumerable source, Type type, string rulesetXml, string ruleId = null, GetRuleDelegate getRule = null)
Filters a collection of source objects by applying a business rule. The specified ruleset Xml is loaded into the Evaluator class, where its rules are compiled and stored in memory. The evaluator then applies the rule named by ruleId, or the first rule of the ruleset, to each object in the collection. Source objects that satisfy the rule are returned as a new collection.
Parameters
- this source (
System.Collections.IEnumerable) - Specifies the collection to be filtered.
- type (
System.Type) - Specifies the underlying source type of the collection.
- rulesetXml (
System.String) - The Rule XML document as a string to be evaluated against source objects.
- ruleId (
System.String) - An optional ID of a rule. If the ruleset contains multiple rules, you can apply a specific rule by providing its ID. The default value is null, which selects the first rule of the ruleset.
- getRule (
CodeEffects.Rule.Common.Models.GetRuleDelegate) - Specifies a delegate to a method used for retrieving external rules referenced by other rules. If this parameter is null, the evaluator attempts to locate any referenced rules within the ruleset itself. If no referenced rules are found, an exception is thrown. The default value is null.