Masterly.BusinessRules 3.0.1

Masterly.BusinessRules

A composable business rule engine for .NET.

Full documentation: a7mdfre7at.github.io/Masterly.BusinessRules

Overview

Masterly.BusinessRules is a business rule engine for .NET. You write each rule, such as "an order must contain at least one item", as a small named unit with a code and a message. You then check one rule or many, and you get back a clear list of every rule that failed.

Every feature works with both synchronous and asynchronous rules. The core package has no dependencies. Five optional packages add text expressions, logging and tracing, dependency injection, feature management and test tools.

What you can do

• Write a rule as a small class, or build one inline from a lambda. See Writing rules and Building rules without classes.
• Write one stateless rule that validates whichever order you pass to it. See Subject-typed rules.
• Combine rules with And, Or and Not, or with groups such as "all", "any" and "at least 2 of". See Combining rules.
• Check many rules in one call, and either collect every failure or stop at the first one. See Running many rules.
• See exactly which part of a combined rule failed, as a printable tree. See Understanding failures.
• Run a rule only when a condition holds, and cache the verdict of a slow rule. See Conditional and cached rules.
• Ship a new rule in shadow mode behind a feature flag, then enforce it for a percentage of callers. See Feature flags and shadow rollout.
• Give each tenant its own limits, such as a maximum order amount, without changing rule code. See Per-tenant rules and parameters.
• Use the same rule to check one object in memory and to query the database for every violating row. See Specifications and database queries.
• Write a condition as text, such as amount > @maxOrderAmount, and see the values it was evaluated with. See Rule expressions.
• Log, trace and measure every rule evaluation with ILogger, OpenTelemetry and metrics. See Logging, tracing and metrics.
• Register your rules in a DI container and inject a runner, and test your rules with coverage, boundary and property checks. See Dependency injection and Testing your rules.

Installation

Install the core package first. Then add only the companion packages you need. All six packages ship together with the same version number.

Every companion package also depends on the core package. The versions shown are the minimum versions each package references.

dotnet add package Masterly.BusinessRules
dotnet add package Masterly.BusinessRules.Expressions
dotnet add package Masterly.BusinessRules.Diagnostics
dotnet add package Masterly.BusinessRules.DependencyInjection
dotnet add package Masterly.BusinessRules.FeatureManagement
dotnet add package Masterly.BusinessRules.Testing

Or, in the Visual Studio Package Manager Console, run Install-Package Masterly.BusinessRules, and the same for each companion package you need.

Note: netstandard2.1 runs on .NET Core 3.0 or later and on .NET 5 or later. It does not run on .NET Framework. The Testing package needs a test project that targets .NET 8 or later.

Quick Start

This example defines two rules for an order, checks one of them, and then checks both together.

1. Define a rule. Derive from BaseBusinessRule and supply a code, a message and the condition. A rule is broken when IsBroken() returns true. Write the condition that describes the violation, not the valid state.

using Masterly.BusinessRules;

// Order and Customer are your own domain classes.
// Here Order.Items is a List<OrderLine> and Customer.IsActive is a bool.
public sealed class OrderMustHaveItemsRule : BaseBusinessRule
{
    private readonly Order _order;

    public OrderMustHaveItemsRule(Order order)
    {
        _order = order;
    }

    public override string Code => "ORDER.NO_ITEMS";

    public override string Message => "An order must contain at least one item.";

    public override bool IsBroken() => _order.Items.Count == 0;
}

public sealed class CustomerMustBeActiveRule : BaseBusinessRule
{
    private readonly Customer _customer;

    public CustomerMustBeActiveRule(Customer customer)
    {
        _customer = customer;
    }

    public override string Code => "CUSTOMER.INACTIVE";

    public override string Message => "The customer account must be active.";

    public override bool IsBroken() => !_customer.IsActive;
}

2. Check one rule. IsBroken() answers the question. Check() throws a BusinessRuleValidationException when the rule is broken and does nothing when it passes.

// order comes from your application
OrderMustHaveItemsRule rule = new OrderMustHaveItemsRule(order);

bool isBroken = rule.IsBroken();

rule.Check();

3. Check several rules. BusinessRuleChecker.CheckAll evaluates every rule you pass. If any are broken, it throws one exception that lists all of them.

// order and customer come from your application
try
{
    BusinessRuleChecker.CheckAll(
        new OrderMustHaveItemsRule(order),
        new CustomerMustBeActiveRule(customer));
}
catch (BusinessRuleValidationException exception)
{
    foreach (BusinessRuleResult broken in exception.BrokenRules)
    {
        Console.WriteLine($"{broken.Code} ({broken.Severity}): {broken.Message}");
    }
}

With an empty order and an inactive customer, this prints:

ORDER.NO_ITEMS (Error): An order must contain at least one item.
CUSTOMER.INACTIVE (Error): The customer account must be active.

Next steps

• To get the results without an exception, call BusinessRuleChecker.EvaluateAll instead. See Check all or evaluate all.
• For rules that call a database or a web service, see Async rules.
• To combine rules, see Combining Rules.

Documentation

Upgrading from 2.x? Most code compiles against 3.0 without changes, but 3.0 is a binary break: rebuild every assembly that references Masterly.BusinessRules. A few behaviours changed too. See Upgrading from 2.x.

If this library helps you, please give it a star on GitHub.

License

MIT - use it freely in your projects. See LICENSE.txt.