RoslynRules Documentation
High-performance .NET rules engine with Roslyn compilation, typed delegates, and async support.
Migration Guide — Moving from Microsoft.RulesEngine
What Makes It Fast
| Feature | How It Works |
|---|---|
| Roslyn Compilation | Expressions compile to IL once, execute as native code |
| Typed Delegates | Direct Func<T,R> calls — no DynamicInvoke overhead |
| Single Parameter | One input, one output — no array allocation per call |
| Immutable Rules | Lock after compile — zero thread contention |
| Parallel Execution | Parallel.For for independent rule evaluation |
Extension Packages
RoslynRules.EntityFrameworkCore
Install: dotnet add package RoslynRules.EntityFrameworkCore
Provides EF Core entity models (RuleEntity, WorkflowEntity) with lazy loading support. Convert to sealed domain models for execution via ToDomainModel(). See the EF Core example.
RoslynRules.Json
Install: dotnet add package RoslynRules.Json
JSON serialization for workflows and rules. See JSON Serialization.
EF Core Integration Note
Rule is sealed to enforce immutability after compilation. This prevents EF Core lazy loading proxies from working (proxies require subclassing). Use eager loading (Include/ThenInclude) or explicit loading (Load()) instead. See the EF Core example.
When to Use Which Execution Mode
| Mode | Best For |
|---|---|
Execute() | Few simple rules, low latency requirements |
ExecuteParallel() | Many CPU-intensive rules |
ExecuteParallelAsync() | Rules with async I/O (DB, HTTP) |
ExecuteAsync() | Streaming results, async iterators |
Example
var rule = new Rule
{
Expression = "customer.Age >= 18",
Action = "customer.IsAdult = true"
};
var wf = new Workflow { Rules = new List<Rule> { rule } };
var compileParam = RuleParameter.ForCompile("customer", typeof(Customer));
var executeParam = RuleParameter.ForExecute("customer", typeof(Customer), customer);
wf.Validate();
wf.Compile(new[] { compileParam });
var results = wf.Execute(new[] { executeParam });
Dependency Injection
Register IRuleEngine in your DI container:
using RoslynRules.Abstractions;
services.AddSingleton<IRuleEngine, Workflow>();
API Reference
API Reference → — Complete API documentation organized by component:
| Section | Contents |
|---|---|
| Rule | Properties, compilation, execution, lifecycle |
| Localization | i18n, DescriptionKey, IRuleDescriptionProvider |
| Visualization | DOT/Mermaid dependency graphs |
| Metrics | Eval count, avg time, failure rate |
| Workflow | Execution modes, parallel, async |
| RuleContext | Dependency result access |
| IRuleEngine | DI registration, mocking |
| RuleBatch | Batch evaluation |
| ExpressionCompiler | Compile API, ALC recycling |
| Delegate Types | Supported signatures |
| JSON | Serialize/deserialize |
| Templates | Placeholder substitution |
| Predicates | 25+ built-in validation factories |
| Priority | Execution order |
| Lifecycle Events | OnRuleExecuting/OnRuleExecuted |
| Caching | Memoization, TTL |
| Exceptions | Typed exception hierarchy |
| Sandboxing | Assembly whitelist/blacklist |
| AOT | Native AOT compatibility |
Examples
| Topic | Description |
|---|---|
| Examples Index | All examples |
| Action Chaining | DependsOnRuleId patterns |
| EF Core | Persistence with Entity Framework |
| Testing | RuleTest and assertions |
| Streaming | IAsyncEnumerable results |
| Use Cases | Production patterns |
| When to Use What | Execution mode comparison |