Evaluator Class
Assembly: CodeEffects.Rule.Engine.dll
Namespace: CodeEffects.Rule.Engine
Summary
Provides core functionality for the evaluation of business rules when the exact type of the source object is known only at run time. When the type is known at design time, use Evaluator<TSource> instead.
Syntax
public class Evaluator : CodeEffects.Rule.Engine.EvaluatorBase
Inheritance
The evaluator parses the Rule XML and compiles every rule of the ruleset once, when the instance is created. Create one instance and reuse it to evaluate any number of source objects. A ruleset rule that declares a source type is compiled only if that type is assignable from the source type of the evaluator; the other rules are skipped. If no rule is compiled, the constructor throws an EvaluationException. If AssemblyWhitelist of the EvaluationParameters is an empty collection, the constructor throws a CodeEffects.Rule.Common.SecurityException.
Constructors
Evaluator(..)
public Evaluator(string rulesetXml, IFlexDataProvider provider, EvaluationParameters parameters = null)
Initializes a new instance of the evaluator to be used with the FlexSource. The source type of the evaluator is System.Object; the values of the rule fields are supplied by the data provider.
Parameters
Evaluator(..)
public Evaluator(Type sourceType, string rulesetXml, EvaluationParameters parameters = null)
Initializes a new instance of the evaluator for the specified source type and evaluation parameters.
Parameters
Example
// Patient is your source object class, rulesetXml holds the Rule XML
var parameters = new EvaluationParameters
{
PerformNullChecks = true,
ShortCircuit = false
};
var evaluator = new Evaluator(typeof(Patient), rulesetXml, parameters);
Evaluator(..)
public Evaluator(Type sourceType, string rulesetXml, GetRuleDelegate getRule = null, int maxIterations = -1)
Initializes a new instance of the evaluator for the specified source type. A delegate of type GetRuleDelegate is used to request any rule that is referenced by another rule.
Parameters
- sourceType (
System.Type) - The type of the source object used by all rules referenced in the Rule XML of the ruleset being evaluated.
- rulesetXml (
System.String) - The Rule XML document as a string.
- 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.
- maxIterations (
System.Int32) - The maximum number of rule iterations in the Loop mode of the Rule Editor. The default value is -1, which means no limit.
This overload and the overload that takes EvaluationParameters both have optional trailing parameters, so a call such as new Evaluator(type, rulesetXml) is ambiguous and does not compile. Pass at least one of the optional arguments explicitly.
Methods
Evaluate(..)
Returns: System.Boolean - Returns a Boolean value indicating the result of the rule evaluation: true if the evaluation succeeded; otherwise, false.
public bool Evaluate(object source, string ruleId = null)
Evaluates the rule against the specified source object. If no rule ID is provided, the first rule in the ruleset is evaluated by default.
Parameters
- source (
System.Object) - Specifies the object to be evaluated. This object serves as the data source for the rule.
- 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, a System.Collections.Generic.KeyNotFoundException is thrown.
The evaluator invokes the compiled rule through a delegate, so an exception that is thrown while the rule runs (for example by a rule action) reaches your code wrapped in a System.Reflection.TargetInvocationException. Read its InnerException for the original error.
Example
var evaluator = new Evaluator(typeof(Patient), rulesetXml, new EvaluationParameters());
var patient = new Patient { Age = 42 };
bool first = evaluator.Evaluate(patient); // the first rule of the ruleset
bool byId = evaluator.Evaluate(patient, "your-rule-id"); // a specific rule
Evaluate(..)
Returns: System.Boolean - Returns a Boolean value indicating the result of the rule evaluation: true if the evaluation succeeded; otherwise, false.
public bool Evaluate(object source, int ruleIndex)
Evaluates the specific rule selected by its zero-based index from the ruleset against the specified source object. The index refers to the order in which the evaluator compiled the rules, which is the order of the rules in the ruleset, not counting the rules that were skipped because of their source type.
Parameters
- source (
System.Object) - Specifies the object to be evaluated. This object serves as the data source for the rule.
- 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, a System.ArgumentOutOfRangeException is thrown.
Evaluate(..)
Returns: System.Boolean - Returns a Boolean value indicating the result of the rule evaluation: true if the evaluation succeeded; otherwise, false.
public bool Evaluate(object source, EvaluationScope scope, bool shortCircuit = true)
Evaluates all rules in the ruleset within the defined scope against the specified source object. The rules are evaluated in the order of the ruleset.
Parameters
- source (
System.Object) - Specifies the object to be evaluated. This object serves as the data source for the rules.
- scope (
CodeEffects.Rule.Common.Models.EvaluationScope) - Specifies the logical operator used when combining the results of the rules in the ruleset: All combines them with AND, AtLeastOne combines them with OR.
- shortCircuit (
System.Boolean) - Specifies whether short-circuit evaluation is enabled. When set to true, the evaluator stops execution as soon as the rule scope is satisfied. When set to false, all rules are evaluated even if the final result is already determined. See Remarks in EvaluationParameters topic for details. The default value is true.
Example
var evaluator = new Evaluator(typeof(Patient), rulesetXml, new EvaluationParameters());
// true if at least one rule of the ruleset passes
bool any = evaluator.Evaluate(patient, EvaluationScope.AtLeastOne);
// true only if all rules pass; every rule runs even after one fails
bool all = evaluator.Evaluate(patient, EvaluationScope.All, false);
Filter(..)
Returns: System.Collections.IEnumerable - Returns a new collection that contains all source objects that satisfied the rule.
public IEnumerable Filter(IEnumerable source)
Filters a collection of source objects by applying a business rule. The evaluator evaluates the rule selected by the RuleID property of the EvaluationParameters (the first rule of the ruleset if it is not set) against each object right away. Source objects that satisfy the rule are returned as a new collection of type System.Collections.IEnumerable.
Parameters
- source (
System.Collections.IEnumerable) - Specifies the collection to be filtered.
Inherited Members
These members are declared by EvaluatorBase. They are static, so you call them on the type, for example Evaluator.Log.