TagBites.Expressions 1.3.0

TagBites.Expressions

TagBites.Expressions is a Roslyn-based C# expression parser and evaluator for .NET. It compiles runtime string expressions into strongly typed Func<> delegates or LambdaExpression expression trees, without creating a new assembly.

var options = new ExpressionParserOptions { Parameters = { (typeof(int), "a"), (typeof(int), "b") } };
var func = ExpressionParser.Compile<Func<int, int, int>>("(a + b) / 2", options);
int r = func(2, 4); // 3

Because Roslyn does the parsing, expressions use real C# syntax: operators, precedence, numeric promotion, implicit conversions, pattern matching, tuples, lambdas, LINQ and generics behave like they do in the C# compiler. If C# accepts the expression, TagBites.Expressions accepts it; if C# rejects it, so does the parser.

Try it online - type an expression and evaluate it in the browser.

Install

dotnet add package TagBites.Expressions

Targets netstandard2.0. Only dependency is Microsoft.CodeAnalysis.CSharp.

Usage

Evaluate once:

ExpressionParser.Invoke("5 / 2.5");                              // 2d
ExpressionParser.Invoke<int>("new [] { 1, 2, 3 }.Sum()");        // 6
ExpressionParser.Invoke<int>("(a + b) / 2", ("a", 2), ("b", 4)); // 3

Compile once, run many times:

var options = new ExpressionParserOptions { Parameters = { (typeof(double), "x"), (typeof(double), "y") } };
var func = ExpressionParser.Compile<Func<double, double, double>>("Math.Pow(x, y) + 5", options);
func(2, 10); // 1029
func(2, 2);  // 9

Bind an object as this:

var options = new ExpressionParserOptions
{
    Parameters = { (typeof(TestModel), "this") },
    UseFirstParameterAsThis = true
};

ExpressionParser.Invoke("X + Y", options, new TestModel { X = 1, Y = 2 }); // 3

Expose named values and delegates with GlobalMembers:

var options = new ExpressionParserOptions
{
    Parameters = { (typeof(int), "a") },
    GlobalMembers = { { "b", (null, 2) } }
};

var func = ExpressionParser.Compile<Func<int, int>>("a switch { 1 => b, 2 => b * 2, _ => b + a }", options);
func(3); // 5

String interpolation, including alignment and format specifiers (formatting follows the current culture):

ExpressionParser.Invoke(@"$""sum = {1 + 2}""");                          // sum = 3
ExpressionParser.Invoke(@"$""{5,-4}|""");                                // "5   |"   (left aligned)
ExpressionParser.Invoke(@"$""{5,6:000}""");                              // "   005"  (alignment + format)
ExpressionParser.Invoke(@"$""{255:X}""");                                // FF
ExpressionParser.Invoke(@"$""{new DateTime(2021, 8, 14):yyyy-MM-dd}"""); // 2021-08-14
ExpressionParser.Invoke(@"$""{(1 < 2 ? ""yes"" : ""no"")}""");           // yes

Anonymous objects (new { ... }) work like a real anonymous type without generating a new one, by internally mapping it to DynamicObject:

var script = "new[] { 1, 2, 3 }.Select(v => new { Value = v, Doubled = v * 2 }).Sum(v => v.Value + v.Doubled)";
dynamic result = ExpressionParser.Invoke(script);
Console.WriteLine(result); // 18

Get the expression tree, or parse without throwing:

LambdaExpression lambda = ExpressionParser.Parse("x * 2 + 1", options);

if (!ExpressionParser.TryParse("a + ", options, out var expr, out var error))
    Console.WriteLine(error);

Use cases

Use TagBites.Expressions when you need to parse, validate, evaluate or compile C# expressions from strings at runtime:

• dynamic business rules and predicates
• user-defined formulas and calculations
• configurable filters and scoring logic
• compile-once/run-many Func<> delegates
• LambdaExpression trees for expression-based APIs
• LINQ-style runtime logic with real C# expression syntax

Why TagBites.Expressions?

• Real C# expression syntax - parsed by Roslyn, not by a custom C#-like grammar.
• Runtime expression evaluation - evaluate once or compile once and invoke many times.
• Delegates or expression trees - compile to Func<> delegates or parse to LambdaExpression.
• Modern C# expressions - supports LINQ, lambdas, pattern matching, switch expressions, tuples, generics, interpolated strings, etc.
• No generated assembly - expressions are compiled without creating a new assembly.

Supported C# expression syntax

• Operators: arithmetic, bitwise, shifts, comparison, && || !, ?:, ??, ?./?[], is/as, x!.
• User-defined operator overloads and user-defined implicit/explicit conversions.
• Literals: all numeric types, char, string, verbatim, raw and interpolated strings, hex, digit separators.
• Members and calls: properties, fields, indexers (including index-from-end x[^1]), generic and extension methods, params.
• new: constructors, object and collection initializers, arrays (jagged, multidimensional and sized), target-typed new().
• Anonymous objects (new { X = 1, Y = 2 } - see Usage above).
• Lambdas and LINQ (Select, Where, GroupBy, ...), including nested and multi-argument lambdas.
• Tuples, including element-wise equality.
• typeof, default(T), nameof, sizeof, checked, unchecked.
• Pattern matching in is and switch: type, constant, relational, and/or/not, property, positional and var patterns, when guards.

Not currently supported:

• The range operator (1..2, arr[1..^1]).
• Target-typed new() as a method call argument (obj.Method(new())) - use an explicit type there for now.
• Named arguments (Method(value: 1, digits: 2)) are parsed but not matched by name - they're passed to parameters positionally, as if the names weren't there.
• Named tuple elements are not preserved - (Name: "Bob", Age: 30).Name fails, only .Item1/.Item2 work.
• The bare default literal (as opposed to default(T)) is only resolved when the whole expression's ExpressionParserOptions.ResultType is set; inside a method argument or ?? it fails with "Default keyword is not supported."

Not supported:

• Statements (like if), async/await, and declarations (methods, types) are out of scope - this is an expression parser.
• Compound assignment and increment/decrement (x += 1, x++, --x, ??=) - this is an expression parser, expressions don't mutate variables.
• ref/out arguments, including out var declarations (e.g. int.TryParse(s, out var n)).

Supported expressions examples

// Switch expression
1 switch { 1 => 10, 2 => 20, _ => 0 }

// Switch expression with a `when` guard
5 switch { 5 when 1 > 2 => 1, 5 => 2, _ => 0 }

// Relational and logical patterns
5 is > 0 and < 10

// List pattern with a slice
new[] { 1, 2, 3 } is [1, .., 3]

// Tuple deconstruction pattern
(1, 2) is (int a, int b) && a < b

// Property pattern
"ab" is { Length: 2 }

// Target-typed new() in nested collection initializers
new List<List<int>> { new() { 1, 2 }, new() { 3, 4 } }[1][0]

// Raw string literal
"""hello world""".Length

// Digit separators
1_000_000

// Index from end
new[] { 1, 2, 3 }[^1]

// Null-forgiving operator
"a"!.Length

// Unchecked integer overflow, same wraparound as C#
unchecked(2147483647 + 1)

// Generic method call with an explicit type argument
new[] { 1, 2, 3 }.OfType<int>().Count()

// User-defined operator overload (DateTime.op_Addition / op_GreaterThan)
DateTime.Now + TimeSpan.FromDays(1) > DateTime.Now

// Tuple equality
(1, 2) == (1, 2)

Configuration

ExpressionParserOptions:

CustomPropertyResolver:
It is only called for instance.Member, it needs an instance to work on. That can be an ordinary parameter, accessed explicitly - p.Age works for any parameter name. A bare name like Age also works, but it is then resolved implicitly as this.Age, so a this must be set up first: UseFirstParameterAsThis, or a this entry in GlobalMembers.

Result type:
ResultType is a contract: the expression must produce this type. A C# implicit conversion (like int → long) is applied automatically; anything else is a parse error. Use it to require, for example, that a filter is a bool.
ResultCastType forces the return type with an explicit cast, so unrelated expressions can share one delegate signature. It also allows casts that are not implicit, such as double → int.

The two combine: to run many rules through a single Func<object> while still requiring each to be boolean, set ResultType = typeof(bool) (reject anything non-boolean) together with ResultCastType = typeof(object).

Non-standard options

These opt-in options (all default to false) make the parser accept syntax or semantics that real C# does not:

Advanced usage

FastExpressionCompiler

ExpressionParser.Parse() returns a plain LambdaExpression, so it can be compiled with any compiler instead of the built-in Compile(). FastExpressionCompiler is a drop-in, dependency-free replacement for LambdaExpression.Compile() that produces the same delegate much faster:

dotnet add package FastExpressionCompiler

using FastExpressionCompiler;

var lambda = ExpressionParser.Parse("Math.Pow(x, y) + 5", options);
var func = (Func<double, double, double>)lambda.CompileFast();

Benchmark

The more complex the expression tree, the bigger the gap, since most of the reflection-emit overhead Compile() pays per node is avoided by CompileFast().

Benchmark source: CompileToDelegate.cs.

Dynamic / Runtime-defined types

CustomPropertyResolver lets an expression navigate types whose shape only exists at runtime - a database row, a CMS content type, a value that lives in another process.

The pattern:

1. Represent every runtime-shaped value with one real, fixed .NET type (not object, not a type generated per shape). Keep the actual field names/types in a separate schema object. (in example: Value/Instance = DynamicRecord, ValueType = DynamicRecordSchema)
2. In CustomPropertyResolver, look up the requested member by name against that schema, and build a call to read it.
3. Attach the schema to the result with context.IncludeTypeInfo(expression, schema), so a later .Member further down the chain can retrieve it again through context.InstanceTypeInfo.

// Schema (DynamicRecordSchema and DynamicRecord are example types)
var personSchema = new TypeSchema(new Dictionary<string, TypeSchema> { ["Name"] = new(typeof(string)), ["Age"] = new(typeof(int)) });
var rootSchema = new TypeSchema(new Dictionary<string, TypeSchema> { ["People"] = new("Person", true) });
var dataSourceSchema = new DynamicRecordSchema { ["Person"] = personSchema, ["this"] = rootSchema };

// Source
var alice = new DynamicRecord { ["Name"] = "Alice", ["Age"] = 30 };
var root = new DynamicRecord { ["People"] = new List<DynamicRecord> { alice } };

// Parse
var options = new ExpressionParserOptions
{
    Parameters = { (typeof(DynamicRecord), "this") },
    UseFirstParameterAsThis = true,
    CustomPropertyResolver = x => Resolver(dataSourceSchema, x)
};
var expression = "People.Where(p => p.Age > 18).Select(x => x.Name).First()";
var result = ExpressionParser.Invoke<string>(expression, options, root); // Alice

// Resolver
Expression? Resolver(DynamicRecordSchema dataSourceSchema, IExpressionMemberResolverContext context)
{
    if (context.Instance.Type != typeof(DynamicRecord))
        return null;

    // Member type
    var instanceSchema = context.InstanceTypeInfo as TypeSchema
        ?? (context.MemberFullPath == "this." + context.MemberName ? dataSourceSchema.GetValueOrDefault("this") : null);
    if (instanceSchema == null)
        return null;

    if (instanceSchema.Fields == null && instanceSchema.Name != null)
    {
        instanceSchema = dataSourceSchema.GetValueOrDefault(instanceSchema.Name);
        if (instanceSchema == null)
            return null;
    }

    // Value
    if (instanceSchema.Fields?.TryGetValue(context.MemberName, out var fieldTypeScheme) != true)
        return null;

    var fieldType = fieldTypeScheme!.Type;
    var isKnownType = fieldType != null;
    if (fieldType == null)
    {
        fieldType = typeof(DynamicRecord);
        if (fieldTypeScheme.IsCollection)
            fieldType = typeof(IList<DynamicRecord>);
    }

    var method = typeof(DynamicRecord).GetMethod(nameof(DynamicRecord.GetValue))!.MakeGenericMethod(fieldType);
    var result = Expression.Call(context.Instance, method, Expression.Constant(context.MemberName));

    return !isKnownType
        ? context.IncludeTypeInfo(result, fieldTypeScheme) // Wrap expression to include a type info
        : result;
}

// Sample value and schema types
class DynamicRecord : Dictionary<string, object>
{
    public T GetValue<T>(string name) => TryGetValue(name, out var value) && value is T v ? v : default;
}
class DynamicRecordSchema : Dictionary<string, TypeSchema>;
class TypeSchema { /* ... */ }

LINQ over a dynamic collection works without any extra code, as long as the collection itself is exposed as a real, closed type - IEnumerable<DynamicRecord>. Because it's a real type, extensions like Where or Select, Sum, Count resolve as ordinary LINQ extension methods. CustomPropertyResolver never has to intercept a method call, only plain member access. And the element parameter of a lambda passed to one of those methods automatically inherits the collection's InstanceTypeInfo, so it's correctly typed too.

Parameters and global members have no type info, so every "dynamic" object must by resolved by resolver.

People resolves through CustomPropertyResolver and is tagged via context.IncludeTypeInfo(call, PersonSchema). Inside the lambda, p "knows" it's a Person too, because parser extracts that same type info from the collection and applies it to p, so p.Age is resolved by the very same resolver branch that resolved People.
Type info is propagated through method chains only for collections. The receiver has to be an IEnumerable<X>, and the info flows to a result that keeps the same element type: another IEnumerable<X> (Where, Select, OrderBy, ...) or a single X (First, FirstOrDefault, ...). That's why People.Where(...).First().Name still knows the element is a Person.

Full example: CustomPropertyResolverTests.cs.

Alternatives

TagBites.Expressions fits between lightweight expression evaluators and full C# scripting engines: it supports real C# expression syntax through Roslyn, returns delegates or expression trees, and avoids generating a new assembly.

Comparison

The table below is generated by LibraryFeatureComparer.cs (run the benchmarks project with the feature-comparer argument). Rows are ordered by how many of the three libraries support each feature, most first:

✅/❌ is based on parsing and evaluating each expression to the expected result, not just on whether parsing throws.

Benchmark

Parsing expressions: "Math.Pow(x, y) + 5" and list.Where(x => x > limit).Select(x => Math.Pow(x, y)).Sum(). The table below is generated by Program.cs.

SharedEnv = shared options/interptreter/config.
SharedOptions for TagBites.Expressions uses UseMemberCache = true.

Benchmark source: ParseToExpression.cs.

Links

• Changelog
• Security policy
• License (MIT)