Gridify 2.4.5-alpha5

This is a prerelease version of Gridify.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Gridify --version 2.4.5-alpha5                
NuGet\Install-Package Gridify -Version 2.4.5-alpha5                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Gridify" Version="2.4.5-alpha5" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Gridify --version 2.4.5-alpha5                
#r "nuget: Gridify, 2.4.5-alpha5"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Gridify as a Cake Addin
#addin nuget:?package=Gridify&version=2.4.5-alpha5&prerelease

// Install Gridify as a Cake Tool
#tool nuget:?package=Gridify&version=2.4.5-alpha5&prerelease                

Gridify (A Modern Dynamic LINQ library)

GitHub Nuget Nuget Nuget (with prereleases) GitHub branch checks state

Easy and optimized way to apply Filtering, Sorting and pagination using text-based data.

Gridify is a dynamic LINQ library that converts your strings to a LINQ query in the easiest way possible with excellent performance.

The best use case of this library is Asp-net APIs. When you need to get some string base filtering conditions to filter data or sort it by a field name or apply pagination concepts to your lists and return a pageable, data grid ready information, from any repository or database. Although, we are not limited to Asp.net projects and we can use this library on any .Net projects and on any collections.

You can find the version 1.x documentation on the Version1 Branch


WebApi Simple Usage example

// ApiController

public Paging<Person> GetPersons([FromQuery] GridifyQuery gQuery)
{
    // Gridify => Filter,Sort & Apply Paging
    // in short, Gridify returns data especially for data Grids.
    return myDbContext.Persons.Gridify(gQuery);
}

complete request sample:

http://exampleDomain.com/api/GetPersons?
          pageSize=100&
          page=1&
          orderBy=FirstName&
          filter=Age>10

// to make the example readable this not encoded url,
// make sure to always encode the query strings before passing it to your APIs

Also, we can totally ignore GridifyQuery

http://exampleDomain.com/api/GetPersons

What is GridifyQuery (basic usage example)

GridifyQuery is a simple class for configuring Filtering,Paging,Sorting.

// usually, we don't need to create this object manually
// for example, we get this object as a parameter from our API Controller
var gQuery = new GridifyQuery()
{
    Filter = "FirstName=John",
    Page = 1,
    PageSize = 20,
    OrderBy = "LastName"
};

Paging<Person> pData =
         myDbContext.Persons  // we can use Any list or repository or EntityFramework context
          .Gridify(gQuery); // Filter,Sort & Apply Paging


// pData.Count => Count persons with 'John', First name
// pData.Data      => First 20 Persons with 'John', First Name

ApplyFiltering

Also, if you don't need paging and sorting features simply use ApplyFiltering extension instead of Gridify.

var query = myDbContext.Persons.ApplyFiltering("name = John");
// this is equal to :
// myDbContext.Persons.Where(p => p.Name == "John");

see more examples in the tests


Performance comparison

Filtering is the most expensive feature in gridify. the following benchmark is comparing filtering in the most known dynamic linq libraries. As you can see, gridify has the closest result to the native linq. Also, i Should note other features like Pagination and Sorting have almost zero overhead in Gridify.

BenchmarkDotNet=v0.13.0, OS=Windows 10.0.19043.1237 (21H1/May2021Update) 11th Gen Intel Core i5-11400F 2.60GHz, 1 CPU, 12 logical and 6 physical cores .NET SDK=5.0.301 [Host] : .NET 5.0.7 (5.0.721.25508), X64 RyuJIT DefaultJob : .NET 5.0.7 (5.0.721.25508), X64 RyuJIT

| Method | Mean | Error | StdDev | Ratio | Gen 0 | Gen 1 | Allocated | |------------ |-----------:|---------:|---------:|------:|--------:|--------:|----------:| | Native LINQ | 740.9 us | 7.80 us | 6.92 us | 1.00 | 5.8594 | 2.9297 | 37 KB | | Gridify | 762.6 us | 10.06 us | 9.41 us | 1.03 | 5.8594 | 2.9297 | 39 KB | | DynamicLinq | 902.1 us | 11.56 us | 10.81 us | 1.22 | 19.5313 | 9.7656 | 122 KB | | Sieve | 977.9 us | 6.80 us | 6.37 us | 1.32 | 7.8125 | 3.9063 | 54 KB | | Fop | 2,959.8 us | 39.11 us | 36.58 us | 3.99 | 46.8750 | 23.4375 | 306 KB |

Installation

Install the Gridify NuGet Package.

Package Manager Console

Install-Package Gridify

.NET Core CLI

dotnet add package Gridify

Extensions

The library adds below extension methods to IQueryable:

Extension Description
ApplyFiltering (string) Apply filtering using a raw string and returns an IQueryable<T>
ApplyFiltering (GridifyQuery) Apply filtering using string Filter property of GridifyQuery class and returns an IQueryable<T>
ApplyOrdering Apply ordering using string OrderBy and bool IsSortAsc properties of GridifyQuery class and returns an IQueryable<T>
ApplyPaging Apply paging using short Page and int PageSize properties of GridifyQuery class and returns an IQueryable<T>
ApplyOrderingAndPaging Apply both Ordering and paging and returns an IQueryable<T>
ApplyFilteringAndOrdering Apply both filtering and ordering and returns an IQueryable<T>
ApplyFilteringOrderingPaging Apply filtering,ordering and paging and returns an IQueryable<T>
GridifyQueryable Like ApplyFilteringOrderingPaging but it returns a QueryablePaging<T> that have an extra int Count property to use for pagination
Gridify Receives a GridifyQuery , loads All requested data and returns Paging<T>

TIP:

Gridify function is an ALL-IN-ONE package, that applies filtering and ordering and paging to your data and returns a Paging<T>.

But for example, if you need to just filter your data without paging or sorting options you can use ApplyFiltering function instead.


Supported Filtering Operators

Name Operator Usage example
Equal = "FieldName = Value"
NotEqual != "FieldName !=Value"
LessThan < "FieldName < Value"
GreaterThan > "FieldName > Value"
GreaterThanOrEqual >= "FieldName >=Value"
LessThanOrEqual <= "FieldName <=Value"
Contains - Like =* "FieldName =*Value"
NotContains - NotLike !* "FieldName !*Value"
StartsWith ^ "FieldName ^ Value"
NotStartsWith !^ "FieldName !^ Value"
EndsWith $ "FieldName $ Value"
NotEndsWith !$ "FieldName !$ Value"
AND - && , "FirstName = Value, LastName = Value2"
OR - || <code>|</code> <code>"FirstName=Value|LastName=Value2"</code>
Parenthesis () <code>"(FirstName=*Jo,Age<30)|(FirstName!=Hn,Age>30)"</code>

We can easily create complex queries using parenthesis() with AND (,) + OR (|) operators.

Also, If you don't specify any value after = or != operators, gridify search for the default and null values.

   var gq = new GridifyQuery() { Filter = "Name=" };
   // this is equal to :
   // Persons.Where(p => p.Name is null || p.Name == string.Empty() )

The '/i' operator can be use after string values for case insensitive search:

var gq = new GridifyQuery() { Filter = "FirstName=John/i" };
// this is matched by => JOHN - john - John - jOHn - ...

Escape character

Filtering has five special character , | ( ) /i to handle complex queries and case-insensitive search. If you want to use these characters in your query values (after operator), you should add a backslash <code>\ </code> before them. having bellow regex could be helpfull ([(),|]|\/i).

JavaScript escape example:

let esc = (v) => v.replace(/([(),|]|\/i)/g, '\\$1')

Csharp escape example:

var value = "(test,test2)";
var esc = Regex.Replace(value, "([(),|]|\/i)", "\\$1" ); // esc = \(test\,test2\)

Multiple OrderBy

OrderBy accepts comma-separated field names followed by asc or desc keyword. by default, if you don't add these keywords, gridify assumes you need Ascending ordering.

e.g

// asc - desc
var gq = new GridifyQuery() { OrderBy = "Id" }; // default assending its equal to "Id asc"
var gq = new GridifyQuery() { OrderBy = "Id desc" }; // use desending ordering

// multiple orderings example
var gq = new GridifyQuery() { OrderBy = "Id desc, FirstName asc, LastName" };

Custom Mapping Support

By default Gridify is using a GridifyMapper object that automatically maps your string based field names to actual properties in your entities but if you have a custom DTO (Data Transfer Object) you can create a custom instance of GridifyMapper and use it to create your mappings.

// example Entities
public class Person
{
    public string FirstName {get;set;}
    public string LastName {get;set;}
    public Contact Contact {get;set;}

}
public class Contact
{
    public string Address {get;set;}
    public int PhoneNumber {get;set;}
}

// example DTO
public class PersonDTO
{
   public string FirstName {get;set;}
   public string LastName {get;set;}

   public string Address {get;set;}
   public int PhoneNumber {get;set;}
}

//// GridifyMapper Usage example -------------

var customMappings = new GridifyMapper<Person>()
        // because FirstName and LastName is exists in both DTO and Entity classes we can Generate them
        .GenerateMappings()
        // add custom mappings
        .AddMap("address", q => q.Contact.Address )
        .AddMap("PhoneNumber", q => q.Contact.PhoneNumber );


// as i mentioned before. usually we don't need create this object manually.
var gQuery = new GridifyQuery()
{
    Filter = "FirstName=John,Address=*st",
    OrderBy = "PhoneNumber"
};

// myRepository: could be entity framework context or any other collections
var gridifiedData = myRepository.Persons.Gridify(gQuery, customMappings);


By default GridifyMapper is Case-insensitive but you can change this behavior if you need Case-Sensitive mappings.

var customMappings = new GridifyMapper<Person>( q =>
{
   q.CaseSensitive = true;    // enalbe case-sensitvity.
   q.AllowNullSearch = false; // disable searching for null values
});

Value Convertor

If you need to change your search values before the filtering operation you can use this feature, the third parameter of the GridifyMapper AddMap method accepts a function that you can use to convert the input values. eg:

// convert values to lower case
var gm = new GridifyMapper<Person>()
       .AddMap("name" , q => q.FullName , v => v.ToLower() )

Filtering on Nested Collections

You can use LINQ Select and SelectMany methods to filter your data using its nested collections.

In this example, we have 3 nested collections, but filtering will apply to the Property1 of the third level.

var gm = new GridifyMapper<Level1>()
    .AddMap("prop1", l1 => l1.Level2List.SelectMany(l2 => l2.Level3List).Select(l3 => l3.Property1);

if you have only two-level nesting, you don't need to use SelectMany.


EntityFramework integration

If you need to use the async feature for entityFramework core, use Gridify.EntityFramework package instead.

This package have two additional GridifyAsync() and GridifyQueryableAsync() functions.

dotnet add package Gridify.EntityFramework

Also, I recommended to Enable EntityFramework compatibility layer if you using gridify on EF context.

 // You should use this configuration in your startup class or main method.
 GridifyGlobalConfiguration.EnableEntityFrameworkCompatibilityLayer();

QueryBuilder

The QueryBuilder class is really useful if you want to manually build your query, also when you don't want to use the extension methods.

Method Description
AddCondition Adds a string base Filtering query
AddOrderBy Adds a string base Ordering query
ConfigurePaging Configure Page and PageSize
AddQuery Accepts a GridifyQuery object to configure filtering,ordering and paging
UseCustomMapper Accepts a GridifyMapper to use in build methods
UseEmptyMapper Setup an Empty new GridifyMapper without auto generated mappings
AddMap Add a single Map to existing mapper
RemoveMap Remove a single Map from existing mapper
ConfigureDefaultMapper Configuring default mapper when we didn't use AddMapper method
Build Applies filtering ordering and paging to a queryable context
BuildCompiled Compiles the expressions and returns a delegate for applying filtering ordering and paging to a enumerable collection
BuildFilteringExpression Returns filtering expression that can be compiled for later use for enumerable collections
BuildEvaluator Returns an evaluator delegate that can be use to evaluate an queryable context
BuildCompiledEvaluator Returns an compiled evaluator delegate that can be use to evaluate an enumerable collection
BuildWithPaging Applies filtering ordering and paging to a context, and returns paging result
BuildWithPagingCompiled Compiles the expressions and returns a delegate for applying filtering ordering and paging to a enumerable collection, that returns paging result
BuildWithQueryablePaging Applies filtering ordering and paging to a context, and returns queryable paging result
Evaluate Directly Evaluate a context to check if all conditions are valid or not

usage eg:

var builder = new QueryBuilder<Person>()
        .AddCondition("name=John")
        .AddOrderBy("age, id");

 var query = builder.build(persons);

Compile and Reuse

You can access Gridify generated expressions using the GetFilteringExpression of GridifyQuery or BuildCompiled methods of QueryBuilder class, by storing an expression you can use it multiple times without having any overheads, also if you store a compiled expression you get a massive performance boost.

Important note: you should only use a compiled expression if you are not using Gridify alongside an ORM like Entity-Framework.

// eg.1 - using GridifyQuery - Compield - where only ----------------------
var gq = new GridifyQuery() { Filter = "name=John" };
var expression = gq.GetFilteringExpression<Person>();
var compiledExpression = expression.Compile();
var result = persons.Where(compiledExpression);

// eg.2 - using QueryBuilder - Compield - where only ----------------------
var compiledExpression = new QueryBuilder<Person>()
                         .AddCondition("name=John")
                         .BuildFilteringExpression()
                         .Compile();
var result = persons.Where(compiledExpression);

// eg.3 - using QueryBuilder - BuildCompiled ------------------------------
var func = new QueryBuilder<Person>()
          .AddCondition("name=John")
          .BuildCompiled();
var result = func(persons);

This is the performance improvement example when you use a compiled expression

| Method | Mean | Error | StdDev | Ratio | RatioSD | Gen 0 | Gen 1 | Allocated | |---------------- |-------------:|-----------:|-----------:|------:|--------:|---------:|--------:|----------:| | GridifyCompiled | 1.008 us | 0.0035 us | 0.0031 us | 0.001 | 0.00 | 0.1564 | - | 984 B | | NativeLINQ | 724.329 us | 6.4686 us | 6.0507 us | 1.000 | 0.00 | 5.8594 | 2.9297 | 37,392 B | | Gridify | 736.854 us | 5.7427 us | 5.0907 us | 1.018 | 0.01 | 5.8594 | 2.9297 | 39,924 B |

Combine Gridify with AutoMapper

//AutoMapper ProjectTo + Filtering Only, example
var query = myDbContext.Persons.ApplyFiltering(gridifyQuery);
var result = query.ProjectTo<PersonDTO>().ToList();

// AutoMapper ProjectTo + Filtering + Ordering + Paging, example
QueryablePaging<Person> qp = myDbContext.Persons.GridifyQueryable(gridifyQuery);
var result = new Paging<Person> (qp.Count,qp.Query.ProjectTo<PersonDTO>().ToList ());

Or simply add these two extentions to your project

public static Paging<TDestination> GridifyTo<TSource, TDestination>(this IQueryable<TSource> query,
                        IMapper autoMapper, IGridifyQuery gridifyQuery, IGridifyMapper<TSource> mapper = null)
{
   mapper = mapper.FixMapper();
   var res = query.GridifyQueryable(gridifyQuery, mapper);
   return new Paging<TDestination> (res.Count , res.Query.ProjectTo<TDestination>(autoMapper.ConfigurationProvider).ToList());
}

// only if you have Gridify.EntityFramework package installed.
public static async Task<Paging<TDestination>> GridifyToAsync<TSource, TDestination>(this IQueryable<TSource> query,
                        IMapper autoMapper, IGridifyQuery gridifyQuery, IGridifyMapper<TSource> mapper = null)
{
   mapper = mapper.FixMapper();
   var res = await query.GridifyQueryableAsync(gridifyQuery, mapper);
   return new Paging<TDestination> (res.Count , await res.Query.ProjectTo<TDestination>(autoMapper.ConfigurationProvider).ToListAsync());
}


Contribution

Any contribution to improve documentation and library is appreciated. Feel free to send pull-Requests. ❤️

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (12)

Showing the top 5 NuGet packages that depend on Gridify:

Package Downloads
Gridify.EntityFramework

Gridify (EntityFramework), Easy and optimized way to apply Filtering, Sorting, and Pagination using text-based data.

KoloDev.GDS.UI

Kolo GDS UI Accelerator

Chaosage.Core.Common

Chaosage开发平台公共对象库

EasyExtensions.EntityFrameworkCore

Ready-to-use library for simplifying the development of .NET applications.

NiuX.Common

csharp common, utils, helpers, tools etc.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.15.0 1,848 10/31/2024
2.15.0-preview7 2,706 8/28/2024
2.15.0-preview5 197 8/14/2024
2.15.0-preview4 551 7/18/2024
2.15.0-preview3 413 6/29/2024
2.15.0-preview2 286 6/22/2024
2.15.0-preview1 137 6/21/2024
2.14.2 81,554 6/8/2024
2.14.1 176,287 12/4/2023
2.14.0 5,827 11/18/2023
2.13.1 1,966 11/12/2023
2.13.0 271 11/11/2023
2.12.0 4,730 10/27/2023
2.11.1 20,682 10/6/2023
2.11.0 204 10/5/2023 2.11.0 is deprecated because it has critical bugs.
2.10.1 4,129 9/28/2023
2.10.0 2,148 9/20/2023
2.10.0-Preview1 133 9/19/2023
2.9.2 2,329 9/15/2023
2.9.1 9,491 8/22/2023
2.9.0 1,827 8/18/2023
2.8.4 63,569 4/18/2023
2.8.3 24,279 3/4/2023
2.8.2 52,148 12/7/2022
2.8.1 158,753 10/7/2022
2.8.0 11,184 7/22/2022
2.7.5 31,734 6/6/2022
2.7.4 25,142 4/22/2022
2.7.3 10,206 4/13/2022
2.7.2 1,066 4/12/2022
2.7.1 8,200 3/2/2022
2.7.0 774 3/1/2022
2.6.0 18,428 1/14/2022
2.5.0 5,894 12/27/2021
2.4.8 4,315 12/15/2021
2.4.7 414 12/14/2021
2.4.6 444 12/10/2021
2.4.5 623 12/5/2021
2.4.5-alpha5 215 12/5/2021
2.4.5-alpha4 230 12/5/2021
2.4.5-alpha3 180 12/2/2021
2.4.5-alpha1 189 12/2/2021
2.4.4 20,440 11/20/2021
2.4.3 835 11/19/2021
2.4.2 865 11/19/2021
2.4.1 2,184 11/18/2021
2.4.0 653 11/18/2021
2.3.3 580 11/16/2021
2.3.2 1,013 11/1/2021
2.3.1 1,351 10/19/2021
2.3.0 4,892 10/4/2021
2.2.1 500 9/30/2021
2.2.0 517 9/28/2021
2.1.0 4,155 9/21/2021
2.0.0 485 9/18/2021
2.0.0-beta.3 159 9/17/2021
2.0.0-beta.2 157 9/16/2021
2.0.0-beta.1 199 9/15/2021
2.0.0-alpha.1 196 8/12/2021
1.4.2 8,439 8/8/2021
1.4.1 604 8/4/2021
1.4.0 519 8/4/2021
1.3.5 1,131 7/28/2021
1.3.4 2,191 7/16/2021
1.3.3 757 7/1/2021
1.3.2 698 6/30/2021
1.3.1 685 6/23/2021
1.1.2 1,608 4/16/2021
1.1.1 623 4/16/2021
1.1.0 1,683 9/17/2020
1.0.5 9,865 7/3/2020
1.0.3 836 7/2/2020
1.0.2 957 7/2/2020 1.0.2 is deprecated because it is no longer maintained.
1.0.1 993 7/2/2020 1.0.1 is deprecated because it is no longer maintained.
1.0.0 1,249 7/1/2020 1.0.0 is deprecated because it is no longer maintained.