NetRuleEngine

NetRuleEngine

C# simple Rule Engine. High performance object rule matching. Support various complex grouped predicates. available on nuget.

(Input) An Object + Rule(s) => (Output) Is Match

Use cases

• Business rules that are dynamically generated by a user interface, to determine Yes/No conditions
• Audience Matching
• Dynamic Alerts detection

Common Usage Scenario

flowchart LR
    User((Rules Admin<br/>User))
    Editor[Rule<br/>Editor UI]
    DB[(Rules DB)]
    Event[Business Event<br/><i>real time</i>]
    Logic[Business Logic]
    Engine[NetRuleEngine]
    
    User -->|configures rules| Editor
    Editor -->|SAVE AS JSON| DB
    Event -->|trigger| Logic
    Logic -->|1.fetch rules| DB
    Logic -->|2.check event<br/>against rules| Engine
    Engine -->|matching rules| Logic

• Rules Admin - Actor Role - that sets the rules on design time to identify an event or desired state.
• Rules DB - Database to store the rules
• Business Event - an Event that occurs on the business flow, and changes a state on your backend, or a standalone event that needs to be tested for rule matching. can be anything as a site Visit, transaction, UI event, Login, Registration or whatever.
• Business LOGIC - this is the backend that reference the NetRuleEngine package, consumes the Rules from DB, and for each Event, run the Rule matching and acts according to the result

Features and Capabilities

Nested Rules Support

The engine supports unlimited nesting of rule groups, allowing for complex logical expressions. RulesGroups can contain both individual Rules and other RulesGroups, enabling sophisticated rule combinations like:

• (A AND (B OR C))
• (A OR B) AND (C OR (D AND E))
• ((A OR B) AND C) OR (D AND (E OR F))

Example of a complex nested rule:

var config = new RulesConfig {
    RulesOperator = Rule.InterRuleOperatorType.And,
    RulesGroups = [
        new RulesGroup {
            Operator = Rule.InterRuleOperatorType.Or,
            Rules = [
                new Rule { 
                    ComparisonOperator = Rule.ComparisonOperatorType.Equal,
                    ComparisonValue = "example",
                    ComparisonPredicate = "TextField"
                },
                new RulesGroup {
                    Operator = Rule.InterRuleOperatorType.And,
                    Rules = [
                        new RulesGroup {
                            Operator = Rule.InterRuleOperatorType.Or,
                            Rules = [
                                new Rule {
                                    ComparisonOperator = Rule.ComparisonOperatorType.GreaterThan,
                                    ComparisonValue = "10",
                                    ComparisonPredicate = "NumericField"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
};

Other Features

• composite objects
• enums
• string
• numbers
• datetime
• Dictionaries
• collections

and many more. See units test for full usage scenarios.

Simple usage:

    IRulesService<TestModel> engine = RulesService<TestModel>.CreateDefault();
            
    var matching = engine.GetMatchingRules(
        new TestModel { NumericField = 5 },
        new[] {
            new RulesConfig {
                Id = Guid.NewGuid(),
                RulesOperator = Rule.InterRuleOperatorType.And,
                RulesGroups = new RulesGroup[] {
                    new RulesGroup {
                        Operator = Rule.InterRuleOperatorType.And,
                        // every TestModel instance with NumericField Equal to 5 will match this rule
                        Rules = new[] {
                            new Rule { 
                            ComparisonOperator = Rule.ComparisonOperatorType.Equal,
                            ComparisonValue = 5.ToString(),
                            ComparisonPredicate = nameof(TestModel.NumericField) 
                            }
                        }
                    }
                }
            }
        });

Technical Details

• depenent on LazyCache to store compiled rules for best performance.
• compiles Expression Trees into dynamic cached code to support high performance usage.
• dependency injection ready, inject Either IRulesService<> or its dependencies.
• as the RulesService is statefull and is dependent on cache, it must be configured as singleton on your IOC (or at least, its cache dependency must be singleton)

Rule Editor UI Example (not included in this project):

Rule Config JSON Format Example:

{
    "Id": "123000000-0000-0000-0000-000000000000",
    "RulesOperator": "And",
    "RulesGroups": [
        {
            "Operator": "Or",
            "Rules": [
                {
                    "ComparisonPredicate": "TextField",
                    "ComparisonOperator": "StringStartsWith",
                    "ComparisonValue": "NOT MATCHING PREFIX",                    
                },
                {
                    "Operator": "And",
                    "Rules": [
                        {
                            "ComparisonPredicate": "NumericField",
                            "ComparisonOperator": "GreaterThan",
                            "ComparisonValue": "10",                            
                        },
                        {
                            "ComparisonPredicate": "TextField",
                            "ComparisonOperator": "Equal",
                            "ComparisonValue": "example",
                        }
                    ]
                }
            ]
        }
    ]
}

This example demonstrates a nested rule structure where:

• The top level uses an AND operator
• First group has an OR operator and contains:
  • A simple string matching rule
  • A nested group with an AND operator containing two conditions

Decoupling properties names from the rule engine

Best practice would be to decouple the Property names from the way they would be used within the rules (the same concept that JsonPropertyAttribute follows when (de)serializing from/to json). this way, renaming the properties will not break the existing rules.
use RulePredicatePropertyAttribute to name the rule predicate property, otherwise the property name will be used as predicate name.

[RulePredicateProperty("first_name")]
public string FirstName { get; set; }

first_name will be used as predicate name instead of the property name (FirstName), and you will be able to rename the property name (FirstName) without breaking the rules.
as your rule will be written as:

{
    "ComparisonPredicate": "first_name",
    "ComparisonOperator": "Equal",
    "ComparisonValue": "John"
}

for example
see TestModelWithComparisonPredicateNameAttribute for more examples