<img src="ExpressionBuilder\ExpressionBuilder.png" width="36" style="position: relative; top: 5px">Expression Builder

In short words, this library basically provides you with a simple way to create lambda expressions to filter lists and database queries by delivering an easy-to-use fluent interface that enables the creation, storage and transmission of those filters. That can be used to help to turn WebApi requests parameters into expressions, create advanced search screens with the capability to save and re-run those filters, among other things. If you would like more details on how it works, please, check out the article Build Lambda Expression Dynamically.

| | Badges | | -- | -- | Build | Quality | Nuget |

• Features
  • New on version 2.1
  • New on version 2
• How to use it
  • Convetions
  • Supported types/operations
  • Globalization support
  • Complex expressions
  • Custom operations
• License

Features:

• Ability to reference properties by their names
• Ability to reference properties from a property
• Ability to reference properties from list items
• Built-in null-checks
• Built-in XML serialization
• Globalization support [not available in .NetStandard 2.0 / .NetCore 2.0]
• Support for complex expressions (those that group up statements within parenthesis)
• Ability to create your own custom operations

Would this help you in anyway? Well, if your answer is 'yes', you just made my day a bit better. :smile:

Please, feel free to leave comments and to place issues if you find errors or realize there is any missing feature.

New on version 2.1:

• Added support for .NetStandard 2.0 (which should include support for .Net Core 2.0) (huge thanks to Joris Labie @labiej and Simon Cropp @SimonCropp)
• FilterFactory class added to offer a "non-generics" approach for creating filters
• Improved support for nested properties (issues #26 and #29)
• Added new 'NotIn' operator
• Fixed bug that used to throw an exception when using the In operator over a nullable property

New on version 2:

• Custom operations: create your own operations or overwrite the behaviour of the default operations
• Full support to Properties and Fields
• Enum renaming: FilterStatementConnector has changed to just Connector
• Other minor improvements

Upgrading to version 2:

Below are a few notes on things you must take into account when upgrading from version 1 to version 2:

• The Operation enum was substituted by a class. So, you'll need to add a reference to the new namespace in order to use it: using ExpressionBuilder.Operations;
• Obtaining operations by their names: <br />Before: (Operation)Enum.Parse(typeof(Operation), "EqualTo") <br />Now: Operation.GetByName("EqualTo")
• Getting the number of values expected by an operation: <br />Before: new OperationHelper().NumberOfValuesAcceptable(Operation.EqualTo) <br />Now: Operation.EqualTo.NumberOfValues
• Connecting filter statements: <br />Before: FilterStatementConnector.And <br />Now: Connector.And

New on version 1.1.2:

• New operation added: DoesNotContain
• Support for complex expressions (those that group up statements within parenthesis)
• Added tests using LINQ to SQL (along with a bug fix regarding the library usage with LINQ to SQL)

How to use it

Let us imagine we have classes like this...

public enum PersonGender
{
    Male,
    Female
}

public class Person
{
    public int Id { get; set; }
    public string Name { get; set; }
    public PersonGender Gender { get; set; }
    public BirthData Birth { get; set; }
    public List<Contact> Contacts { get; private set; }
    public Company Employer { get; set; }

    public class BirthData
    {
        public DateTime Date { get; set; }
        public string Country { get; set; }
    }

    public class Company {
        public string Name { get; set; }
        public string Industry { get; set; }
    }
}

public enum ContactType
{
    Telephone,
    Email
}

public class Contact
{
    public ContactType Type { get; set; }
    public string Value { get; set; }
    public string Comments { get; set; }
}

...and we have to build the code behind a form like this one to filter a list of Person objects:

Now, what about being able to do it in a way like this:

var filter = new Filter<Person>();
filter.By("Id", Operation.Between, 2, 4,  Connector.And);
filter.By("Contacts[Value]", Operation.EndsWith, "@email.com", default(string), Connector.And);
filter.By("Birth.Country", Operation.IsNotNull, default(string), default(string),  Connector.Or);
filter.By("Name", Operation.Contains, " John");
var people = People.Where(filter);

//or like this...

var filter = new Filter<Person>();
filter.By("Id", Operation.Between, 2, 4)
      .And.By("Birth.Country", Operation.IsNotNull)
      .And.By("Contacts[Value]", Operation.EndsWith, "@email.com")
      .Or.By("Name", Operation.Contains, " John ");
var people = People.Where(filter);

So that would generate an expression like this:

People.Where(p => (p.Id >= 2 && p.Id <= 4)
             && (p.Birth != null && p.Birth.Country != null)
             && (p.Contacts != null && p.Contacts.Any(c => c.Value.Trim().ToLower().EndsWith("@email.com")))
             || (p.Name != null  && p.Name.Trim().ToLower().Contains("john")));

Conventions

The convention around the properties names is, probably, the heart of this project. It defines the way in which the properties are addressed, how to reference a property, or the property of a property, or even the property of an item in a list property of the type being filtered.

How to address a property:

1. Any value property of the type being filtered: just mention its name (e.g. Id, Name, Gender, etc.)
2. Any value property of a reference property of the type being filtered: use the "dot notation" (e.g. Birth.Date, Company.Name, etc.)
3. Any value property of an item in a list property: mention the name of the list property followed by the name of its property between brackets (e.g. Contacts[Type], Contacts[Value])

Supported types/operations

The operations are grouped together into logical type groups to simplify the association of a type with an operation:

• Default
  • EqualTo
  • NotEqualTo
• Text
  • Contains
  • DoesNotContain
  • EndsWith
  • EqualTo
  • IsEmpty
  • IsNotEmpty
  • IsNotNull
  • IsNotNullNorWhiteSpace
  • IsNull
  • IsNullOrWhiteSpace
  • NotEqualTo
  • StartsWith
• Number
  • Between
  • EqualTo
  • GreaterThan
  • GreaterThanOrEqualTo
  • LessThan
  • LessThanOrEqualTo
  • NotEqualTo
• Boolean
  • EqualTo
  • NotEqualTo
• Date
  • Between
  • EqualTo
  • GreaterThan
  • GreaterThanOrEqualTo
  • LessThan
  • LessThanOrEqualTo
  • NotEqualTo

This way, when a type is associated with a type group, that type will "inherit" the list of supported operations from its group.

While compiling the filter into a lambda expression, the expression builder will validate if the selected operation is supported by the property's type and throw an exception if it's not. To overcome situations in which you would like to add support to a specific type, you may configure it by adding the following to your config file:

<configuration>
  ...
  <configSections>
    <section name="ExpressionBuilder" type="ExpressionBuilder.Configuration.ExpressionBuilderConfig, ExpressionBuilder" />
  </configSections>

  ...

  <ExpressionBuilder>
    <SupportedTypes>
      <add typeGroup="Date" type="System.DateTimeOffset" />
    </SupportedTypes>
  </ExpressionBuilder>
  ...
</configuration>

Globalization support

You just need to perform some easy steps to add globalization support to the UI:

1. Add a resource file to the project, naming it after the type you'll create your filter to (e.g. Person.resx);
2. Add one entry for each property you'd like to globalize following the conventions (previously mentioned), but replacing the dots (.) and the brackets ([, ]) by underscores (_):
   Person.resx

Person.pt-BR.resx
   
3. You can globalize the operations on a similar way as well by adding a resources file named Operations.resx:
   Operations.resx

Operations.pt-BR.resx
   
4. For the properties, you'll instantiate a PropertyCollection : `new PropertyCollection(typeof(Person), Resources.Person.Resou