ExpressionQueryBuilder<T> Class

Builds expression-based queries from query strings for use with IQueryable and EF Core.

public sealed class ExpressionQueryBuilder<T>

Type parameters

T
The type of object to query against.

Remarks

Unlike QueryBuilder<T> which uses Predicate<T> for in-memory evaluation, this builder creates Expression<TDelegate> objects that can be translated to SQL by EF Core.

Example

var queryBuilder = new ExpressionQueryBuilder<Person>();
queryBuilder.AddHandler("name", item => item.FullName);
queryBuilder.AddHandler<int>("age", item => item.Age);
var query = queryBuilder.Build("name:John AND age>=21");

// Apply works on any IQueryable<T>, such as an Entity Framework Core DbSet<T>
var people = new[] { new Person("John Doe", 30), new Person("John Smith", 18), new Person("Jane Doe", 25) }.AsQueryable();
var results = query.Apply(people).ToList();
Assert.Equal("John Doe", Assert.Single(results).FullName);

Constructors

NameDescription
ExpressionQueryBuilder()Initializes a new instance of ExpressionQueryBuilder<T> using the system time provider.
ExpressionQueryBuilder(TimeProvider?)Initializes a new instance of ExpressionQueryBuilder<T> with a specific time provider for date-related range keywords.
ExpressionQueryBuilder(TimeProvider?, TimeZoneInfo?)Initializes a new instance of ExpressionQueryBuilder<T> with a specific time provider and time zone for date-related range keywords.

ExpressionQueryBuilder overloads

ExpressionQueryBuilder()

ExpressionQueryBuilder.cs

Initializes a new instance of ExpressionQueryBuilder<T> using the system time provider.

public ExpressionQueryBuilder()

ExpressionQueryBuilder(TimeProvider?)

ExpressionQueryBuilder.cs

Initializes a new instance of ExpressionQueryBuilder<T> with a specific time provider for date-related range keywords.

public ExpressionQueryBuilder(TimeProvider? timeProvider)
Parameters
timeProvider TimeProvider?
The time provider to use, or null to use TimeProvider.System.

ExpressionQueryBuilder(TimeProvider?, TimeZoneInfo?)

ExpressionQueryBuilder.cs

Initializes a new instance of ExpressionQueryBuilder<T> with a specific time provider and time zone for date-related range keywords.

public ExpressionQueryBuilder(TimeProvider? timeProvider, TimeZoneInfo? timeZone)
Parameters
timeProvider TimeProvider?
The time provider to use, or null to use TimeProvider.System.
timeZone TimeZoneInfo?
The time zone that gives the day boundaries of date keywords, such as today and @today-3d, or null to use TimeZoneInfo.Utc.

Properties

NameDescription
StrictGets or sets whether ExpressionQueryBuilder<T>.Build throws when the query has diagnostics.

Gets or sets whether ExpressionQueryBuilder<T>.Build throws when the query has diagnostics.

public bool Strict { get; set; }

Property value

bool true to throw an InvalidQueryException for a query with diagnostics, such as an unbalanced parenthesis or an unknown key; false (the default) to read the query leniently and report the diagnostics in ExpressionQuery<T>.Diagnostics.

Methods

NameDescription
AddHandler(string, KeyValueOperator, Func<string, Expression<Func<T, bool>>>)Registers a custom expression handler for a property key and operator.
AddHandler(string, Func<string, Expression<Func<T, bool>>>)Registers a custom expression handler for a property key with equality operator.
AddHandler(string, Expression<Func<T, string?>>, StringMatchMode, StringComparison?)Registers a handler for a string property using the specified match mode.
AddHandler(string, Expression<Func<T, string?>>, StringComparison?)Registers a handler for a string property using a "contains" comparison.
AddHandler<TValue>(string, Expression<Func<T, TValue>>, ScalarParser<TValue>?)Registers a handler for a property with automatic comparison operators.
Build(string)Builds a query from a query string.
SetFreeTextHandler(FreeTextExpressionHandler<T>?)Sets the handler for free-text search terms without a property key.
SetUnhandledPropertyHandler(UnhandledPropertyExpressionHandler<T>?)Sets the handler for property keys that don't have a registered handler.

AddHandler overloads

AddHandler(string, KeyValueOperator, Func<string, Expression<Func<T, bool>>>)

ExpressionQueryBuilder.cs

Registers a custom expression handler for a property key and operator.

public void AddHandler(string key, KeyValueOperator op, Func<string, Expression<Func<T, bool>>> handler)
Parameters
key string
The property key to handle.
op KeyValueOperator
The operator to handle.
handler Func<string, Expression<Func<T, bool>>>
Function that creates the filter expression from the query value.

AddHandler(string, Func<string, Expression<Func<T, bool>>>)

ExpressionQueryBuilder.cs

Registers a custom expression handler for a property key with equality operator.

public void AddHandler(string key, Func<string, Expression<Func<T, bool>>> handler)
Parameters
key string
The property key to handle.
handler Func<string, Expression<Func<T, bool>>>
Function that creates the filter expression from the query value.

AddHandler(string, Expression<Func<T, string?>>, StringMatchMode, StringComparison?)

ExpressionQueryBuilder.cs

Registers a handler for a string property using the specified match mode.

public void AddHandler(string key, Expression<Func<T, string?>> selector, StringMatchMode matchMode, StringComparison? comparisonType = null)
Parameters
key string
The property key to handle.
selector Expression<Func<T, string?>>
Expression selecting the string property.
matchMode StringMatchMode
How the property matches the value of the query.
comparisonType StringComparison?
The string comparison to use, or null to emit the overload without a StringComparison (or the == operator for StringMatchMode.Exact). Most LINQ providers, including Entity Framework Core, cannot translate the StringComparison overloads, so passing a value here makes the query usable in memory only. When left null, the comparison is decided by the underlying provider — the database collation for EF Core. For LINQ to Objects, StringMatchMode.Contains and StringMatchMode.Exact are ordinal, while StringMatchMode.StartsWith and StringMatchMode.EndsWith use the current culture, as String.StartsWith and String.EndsWith do.

AddHandler(string, Expression<Func<T, string?>>, StringComparison?)

ExpressionQueryBuilder.cs

Registers a handler for a string property using a "contains" comparison.

public void AddHandler(string key, Expression<Func<T, string?>> selector, StringComparison? comparisonType = null)
Parameters
key string
The property key to handle.
selector Expression<Func<T, string?>>
Expression selecting the string property.
comparisonType StringComparison?
The string comparison to use, or null to emit a plain String.Contains call. Most LINQ providers, including Entity Framework Core, cannot translate the StringComparison overload of String.Contains, so passing a value here makes the query usable in memory only. When left null, case sensitivity is decided by the underlying provider — the database collation for EF Core, and an ordinal comparison for LINQ to Objects.

AddHandler<TValue>(string, Expression<Func<T, TValue>>, ScalarParser<TValue>?)

ExpressionQueryBuilder.cs

Registers a handler for a property with automatic comparison operators.

public void AddHandler<TValue>(string key, Expression<Func<T, TValue>> selector, ScalarParser<TValue>? tryParseValue = null)
Type parameters
TValue
The type of the property.
Parameters
key string
The property key to handle.
selector Expression<Func<T, TValue>>
Expression selecting the property.
tryParseValue ScalarParser<TValue>?
Custom parser for the value, or null to use the default parser.

Builds a query from a query string.

public ExpressionQuery<T> Build(string query)

Parameters

query string
The query string to parse.

Returns

ExpressionQuery<T> A compiled expression query that can be applied to an IQueryable<T>.

Exceptions

QueryTooComplexException
The query is too complex to be evaluated.
InvalidQueryException
ExpressionQueryBuilder<T>.Strict is true and the query has diagnostics.

SetFreeTextHandler(FreeTextExpressionHandler<T>?)

ExpressionQueryBuilder.cs

Sets the handler for free-text search terms without a property key.

public void SetFreeTextHandler(FreeTextExpressionHandler<T>? handler)

Parameters

handler FreeTextExpressionHandler<T>?
The function to create filter expressions for free-text queries.

SetUnhandledPropertyHandler(UnhandledPropertyExpressionHandler<T>?)

ExpressionQueryBuilder.cs

Sets the handler for property keys that don't have a registered handler.

public void SetUnhandledPropertyHandler(UnhandledPropertyExpressionHandler<T>? handler)

Parameters

handler UnhandledPropertyExpressionHandler<T>?
The function to create filter expressions for unhandled properties.