Skip to content 
404
PAGE NOT FOUND
But if you don't change your direction, and if you keep looking, you may end up where you are heading.
404
But if you don't change your direction, and if you keep looking, you may end up where you are heading.
Any kind of contribution is welcome.
start contributing to the project by submitting pull requests
Gridify documentation is powered by vuePress, All the markdown source files are placed in docs directory.
by running the following commands, you can check the documentation site locally:
yarn install
+yarn devnpm install
+npm run devcheck out the github contributing guide
Thank you to everyone who has contributed to the Gridify codebase. We appreciate you!
When working with ASP.NET APIs, especially when you need to apply string-based filtering conditions, sorting based on field names, or implementing pagination functionality, the Gridify library is a valuable tool. It can be used in any .NET project and with any type of collection, not just limited to ASP.NET projects.
To demonstrate the core concepts of Gridify, let's look at a simple implementation in the following example.
Imagine you have an API that returns a list of users. You want to use this API in your client-side application to display a list of users.
// UserController
+// ...
+public IEnumerable<User> GetUsers()
+{
+ // context can be Entity Framework, a repository, or whatever.
+ return context.Users.ToList();
+}However, there are a few challenges:
Implementing these features can be complex and messy. If you want to support multiple properties, you would need to write a lot of code with if-else statements. This is where Gridify comes in.
With Gridify, you can simplify your code and implement the required features in just a few lines:
public Paging<User> GetUsers([FromQuery] GridifyQuery query)
+{
+ return context.Users.Gridify(query);
+}Gridify handles all the complexity behind the scenes.
The Paging class is a generic Data Transfer Object (DTO) that has two properties:
public int Count { get; set; }
+public IEnumerable<T> Data { get; set; }The Count property indicates the total number of records, while the Data property contains the records on the current page.
GridifyQuery is a class that represents the query parameters passed to the Gridify method.
Learn more about GridifyQuery.
Please note that this URL is not encoded. Always remember to encode query strings before passing them to your APIs.
http://exampleDomain.com/api/GetUsers?
+ pageSize=100&
+ page=1&
+ orderBy=FirstName&
+ filter=Age>10Alternatively, you can ignore the GridifyQuery and use the default pagination values, which are pageSize=20 and page=1.
http://exampleDomain.com/api/GetUsersTIP
GridifyMapper instance as a parameter.Gridify is completely compatible with AutoMapper. Also, these two packages can help each other nicely. We can use Gridify for filtering, sorting, and paging and AutoMapper for the projection.
// AutoMapper ProjectTo + Filtering Only, example
+var query = personRepo.ApplyFiltering(gridifyQuery);
+var result = query.ProjectTo<PersonDTO>().ToList();// AutoMapper ProjectTo + Filtering + Ordering + Paging, example
+QueryablePaging<Person> qp = personRepo.GridifyQueryable(gridifyQuery);
+var result = new Paging<Person>(qp.Count, qp.Query.ProjectTo<PersonDTO>().ToList());Filtering, Ordering, Paging, and Projection are all done with GridifyTo.
Gridify library does not have a built-in GridifyTo extension method because we don't want to have AutoMapper dependency. but if you are using AutoMapper in your project, I recommend you to add the bellow extension method to your project.
public static Paging<TDestination> GridifyTo<TSource, TDestination>(
+ this IQueryable<TSource> query, IMapper autoMapper, IGridifyQuery gridifyQuery, IGridifyMapper<TSource> mapper = null)
+{
+ 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)
+{
+ var res = await query.GridifyQueryableAsync(gridifyQuery, mapper);
+ return new Paging<TDestination>(res.Count, await res.Query.ProjectTo<TDestination>(autoMapper.ConfigurationProvider).ToListAsync());
+}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.
WARNING
You should only use a compiled expression (delegate) if you are not using Gridify alongside an ORM like Entity-Framework.
// eg.1 - using GridifyQuery - Compiled - 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 - Compiled - 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 | Ratio | RatioSD | Gen 0 | Gen 1 | Allocated |
|---|---|---|---|---|---|---|
| GridifyCompiled | 1.008 us | 0.001 | 0.00 | 0.1564 | - | 984 B |
| Gridify | 689.329 us | 1.000 | 0.00 | 5.8594 | 2.9297 | 39,924 B |
| NativeLINQ | 736.854 us | 1.019 | 0.01 | 5.8594 | 2.9297 | 37,392 B |
Gridify offers a powerful feature that enables you to streamline data mapping and configurations in your application by integrating with the Dependency Injection (DI) container. By registering your mapping profiles with DI, you can achieve cleaner, more maintainable code and improved separation of concerns. This section provides an overview of how to register your GridifyMapper configurations with DI.
Registering Gridify mapping with DI is a straightforward process. You'll define mapping profiles for your models and then register them in the DI container. Follow these steps to get started:
Create mapping profiles by inheriting from GridifyMapper<T>, where T represents the type you want to map. Configure your mappings within these profile classes.
Example:
public class WeatherForecastGridifyMapper : GridifyMapper<WeatherForecast>
+{
+ public WeatherForecastGridifyMapper()
+ {
+ // Define your mappings here
+ AddMap("summary", q => q.Summary);
+ AddMap("temp", q => q.TemperatureC);
+
+ // optionally you can customize the configuration for each mapper
+ Configuration.CaseSensitive = false;
+ Configuration.AllowNullSearch = true;
+ Configuration.IgnoreNotMappedFields = true;
+
+ }
+}Utilize the AddGridifyMappers extension method available on the IServiceCollection to scan your assembly and register all mapping profiles.
Example:
using Gridify; // Make sure to include the necessary namespace
+// ...
+
+public void ConfigureServices(IServiceCollection services)
+{
+ // Other service registrations
+
+ services.AddGridifyMappers(typeof(Program).Assembly);
+}Once you've registered the mapping profiles, you can inject the corresponding IGridifyMapper<T> interfaces into your services or controllers.
Example:
public class WeatherForecastController : ControllerBase
+{
+ private readonly IGridifyMapper<WeatherForecast> _mapper;
+
+ public WeatherForecastController(IGridifyMapper<WeatherForecast> mapper)
+ {
+ _mapper = mapper;
+ }
+
+ [HttpGet(Name = "GetWeatherForecast")]
+ public Paging<WeatherForecast> Get([FromQuery] GridifyQuery query)
+ {
+ IQueryable<WeatherForecast> result = GetWeatherForecasts();
+
+ // You can pass the mapper to the GridifyExtension
+ return result.Gridify(query, _mapper);
+ }
+}public class WeatherForecastController : ControllerBase
+{
+ private readonly IGridifyMapper<WeatherForecast> _mapper;
+
+ public WeatherForecastController(IGridifyMapper<WeatherForecast> mapper)
+ {
+ _mapper = mapper;
+ }
+
+ [HttpGet(Name = "GetWeatherForecast")]
+ public IEnumerable<WeatherForecast> Get([FromQuery] GridifyQuery query)
+ {
+ var result = GetWeatherForecasts();
+
+ var queryBuilder = new QueryBuilder<WeatherForecast>()
+ .UseCustomMapper(_mapper)
+ .AddQuery(query);
+
+ return queryBuilder.Build(result);
+ }
+}The Gridify library adds the below extension methods to IQueryable objects.
All Gridify extension methods can accept GridifyQuery and GridifyMapper as a parameter. Make sure to check out the documentation of these classes for more information.
TIP
If you want to use Gridify extension methods on an IEnumerable object, use .AsQueryable() first.
You can use this method if you want to only apply filtering on an IQueriable or DbSet.
var query = personsRepo.ApplyFiltering("name = John");this is completely equivalent to the below LINQ query:
var query = personsRepo.Where(p => p.Name == "John");In the ApplyFiltering method, we can use a raw string to filter the data, which can be generated dynamically or passed by the end-user for example through an API client or console input, but using the Linq Where method, we always have to hard code the query for the supported fields.
Check out the Filtering Operators section for more information.
You can use this method if you want to only apply ordering on an IQueriable collection or DbSet.
var query = personsRepo.ApplyOrdering("name, age desc");this is completely equivalent to the below LINQ query:
var query = personsRepo.OrderBy(x => x.Name).ThenByDescending(x => x.Age);Check out the Ordering section for more information.
You can use this method if you want to only apply paging on an IQueryable collection or DbSet.
var query = personsRepo.ApplyPaging(3, 20);this is completely equivalent to the below LINQ query:
var query = personsRepo.Skip((3-1) * 20).Take(20);You can use this method if you want to apply filtering and ordering on an IQueryable collection or DbSet. This method accepts IGridifyQuery.
You can use this method if you want to apply ordering and paging on an IQueryable collection or DbSet. This method accepts IGridifyQuery.
You can use this method if you want to apply filtering and ordering and paging on an IQueryable collection or DbSet. This method accepts IGridifyQuery.
Like ApplyFilteringOrderingPaging but it returns a QueryablePaging<T> that has an extra int Count value that can be used for pagination.
This is an ALL-IN-ONE package, it accepts IGridifyQuery, applies filtering, ordering, and paging, and returns a Paging<T> object. This method is completely optimized to be used with any Grid component.
Gridify.Elasticsearch is an extension of Gridify, that provides an ability to generate Elasticsearch DSL queries.
The Gridify.Elasticsearch package has a bunch of extension methods that allow to convert Gridify filters and sortings to Elasticsearch DSL queries using Elastic.Clients.Elasticsearch .NET client.
Specifies how field names are inferred from CLR property names. By default, Elastic.Clients.Elasticsearch uses camel-case property names.
null (default behavior) CLR property EmailAddress will be inferred as emailAddress Elasticsearch document field name.p => p, the CLR property EmailAddress will be inferred as EmailAddress Elasticsearch document field name.await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyFiltering("emailAddress = test@test.com"));this will make the next Elasticsearch query:
GET users/_search
+{
+ "query": {
+ "term": {
+ "emailAddress.keyword": {
+ "value": "test@test.com"
+ }
+ }
+ }
+}GridifyGlobalConfiguration.CustomElasticsearchNamingAction = p => $"_{p}_";
+
+await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyFiltering("emailAddress = test@test.com"));this will make the next Elasticsearch query:
GET users/_search
+{
+ "query": {
+ "term": {
+ "_EmailAddress_.keyword": {
+ "value": "test@test.com"
+ }
+ }
+ }
+}var gq = new GridifyQuery()
+{
+ Filter = "FirstName=John",
+ Page = 1,
+ PageSize = 20,
+ OrderBy = "Age"
+};
+
+var response = await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyPaging(gq)
+ .ApplyFiltering(gp)
+ .ApplyOrdering(gp));
+
+return response.Documents;GET users/_search
+{
+ "query": {
+ "term": {
+ "firstName.keyword": {
+ "value": "John"
+ }
+ }
+ },
+ "from": 0,
+ "size": 20,
+ "sort": [{
+ "age": {
+ "order": "asc"
+ }
+ }]
+}var gq = new GridifyQuery()
+{
+ Filter = "name=John, surname=Smith, age=30, totalOrderPrice=45",
+ Page = 1,
+ PageSize = 20,
+ OrderBy = "Age"
+};
+
+var mapper = new GridifyMapper<User>()
+ .AddMap("name", x => x.FirstName)
+ .AddMap("surname", x => x.LastName)
+ .AddMap("age", x => x.Age)
+ .AddMap("totalOrderPrice", x => x.Order.TotalSum);
+
+var response = await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyFilteringOrderingPaging(gq));
+
+return response.Documents;GET users/_search
+{
+ "query": {
+ "bool": {
+ "must": [
+ {
+ "term": {
+ "firstName.keyword": {
+ "value": "John"
+ }
+ }
+ },
+ {
+ "term": {
+ "lastName.keyword": {
+ "value": "Smith"
+ }
+ }
+ },
+ {
+ "term": {
+ "age": {
+ "value": 30
+ }
+ }
+ },
+ {
+ "term": {
+ "order.totalSum": {
+ "value": 45
+ }
+ }
+ }
+ ]
+ }
+ },
+ "from": 0,
+ "size": 20,
+ "sort": [{
+ "age": {
+ "order": "asc"
+ }
+ }]
+}By default, Elasticsearch converts property names to camel-case for document fields. That's Gridify.Elasticsearch extensions work by default. But if it's necessary to apply a custom naming policy, it can also be customized.
Func<string, string>? namingAction = p => $"_{p}_";
+var mapper = new GridifyMapper<TestClass>(autoGenerateMappings: true)
+{
+ Configuration = { CustomElasticsearchNamingAction = namingAction }
+};
+
+var gq = new GridifyQuery()
+{
+ Filter = "FirstName=John",
+ Page = 1,
+ PageSize = 20,
+ OrderBy = "Age"
+};
+
+var response = await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyFilteringOrderingPaging(gq));GET users/_search
+{
+ "query": {
+ "term": {
+ "_FirstName_.keyword": {
+ "value": "John"
+ }
+ }
+ },
+ "from": 0,
+ "size": 20,
+ "sort": [{
+ "_Age_": {
+ "order": "asc"
+ }
+ }]
+}WARNING
Gridify.Elasticsearch package does not support all of the advanced Gridify features like NestedFiltering
The Gridify.EntityFramework package has two additional GridifyAsync() and GridifyQueryableAsync() methods.
If you want to use gridify with Entity Framework, you should enable the compatibility layer:
GridifyGlobalConfiguration.EnableEntityFrameworkCompatibilityLayer();Enabling the compatibility layer provides the following features:
DECLARE @__Value_0 nvarchar(4000) = N'vahid';
+
+SELECT [u].[Id], [u].[CreateDate], [u].[FkGuid], [u].[Name]
+FROM [Users] AS [u]
+WHERE [u].[Name] = @__Value_0Setting this property to true Enables the EntityFramework Compatibility layer to make the generated expressions compatible whit entity framework.
boolfalseSimply sets the EntityFrameworkCompatibilityLayer property to true.
Simply sets the EntityFrameworkCompatibilityLayer property to false.
The Gridify Client library is a lightweight JavaScript and TypeScript library designed to simplify the creation of dynamic queries on the client side. This library facilitates the construction of queries that can be seamlessly integrated with your server-side APIs, leveraging the powerful features of Gridify.
To integrate the Gridify Client library into your project, install it using npm:
npm i gridify-clientThe GridifyQueryBuilder interface represents the methods available for constructing dynamic queries using the Gridify Client library.
The following table describes the methods available in the GridifyQueryBuilder interface for constructing dynamic queries.
| Method | Parameter | Description |
|---|---|---|
| setPage | page: number | Set the page number for pagination. |
| setPageSize | pageSize: number | Set the page size for pagination. |
| addOrderBy | field: string, descending?: boolean | Add ordering based on a field. If descending is true, the ordering is in descending order (default is ascending). |
| addCondition | field, operator, value, caseSensitive, escapeValue | Add filtering conditions. caseSensitive and escapeValue are optional parameters. |
| startGroup | - | Start a logical grouping of conditions. |
| endGroup | - | End the current logical group. |
| and | - | Add the logical AND operator. |
| or | - | Add the logical OR operator. |
| build | - | Build and retrieve the constructed query. |
We can use the ConditionalOperator enum to access supported operators. we can pass these operators to the second parameter of addCondition method
| Operator | Description |
|---|---|
Equal | Equality |
NotEqual | Inequality |
LessThan | Less Than |
GreaterThan | Greater Than |
GreaterThanOrEqual | Greater Than or Equal |
LessThanOrEqual | Less Than or Equal |
Contains | String Contains (LIKE) |
NotContains | String Does Not Contain (NOT LIKE) |
StartsWith | String Starts With |
NotStartsWith | String Does Not Start With |
EndsWith | String Ends With |
NotEndsWith | String Does Not End With |
Below is a basic example demonstrating the usage of the Gridify Client library in TypeScript. This example constructs a dynamic query for pagination, ordering, and filtering:
import { GridifyQueryBuilder, ConditionalOperator as op } from "gridify-client";
+
+const query = new GridifyQueryBuilder()
+ .setPage(2)
+ .setPageSize(10)
+ .addOrderBy("name", true)
+ .startGroup()
+ .addCondition("age", op.LessThan, 50)
+ .or()
+ .addCondition("name", op.StartsWith, "A")
+ .endGroup()
+ .and()
+ .addCondition("isActive", op.Equal, true)
+ .build();
+
+console.log(query);Output:
{
+ "page": 2,
+ "pageSize": 10,
+ "orderBy": "name desc",
+ "filter": "(age<50|name^A),isActive=true"
+}Gridify supports the following 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" |
TIP
If you don't specify any value after = or != operators, Gridify search for the default and null values.
var x = personsRepo.ApplyFiltering("name=");this is equivalent to the bellow LINQ query:
var x = personsRepo.Where(p =>
+ p.Name is null ||
+ p.Name == string.Empty );Using logical operators we easily can create complex queries.
| Name | Operator | Usage example |
|---|---|---|
| AND | , | "FirstName = Value, LastName = Value2" |
| OR | | | "FirstName=Value|LastName=Value2" |
| Parenthesis | () | "(FirstName=*Jo,Age<30)|(FirstName!=Hn,Age>30)" |
The '/i' operator can be use after string values for case insensitive searches. You should only use this operator after the search value.
Example:
var x = personsRepo.ApplyFiltering("FirstName=John/i");this query matches with JOHN - john - John - jOHn ...
Gridify have five special operators , | ( ) /i to handle complex queries and case-insensitive searches. If you want to use these characters in your query values (after conditional operator), you should add a backslash \\ before them. having this regex could be helpful ([(),|]|\\/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\\)Since version v2.3.0, Gridify support passing indexes to the sub collections. We can pass the index using the [ ] brackets. In the bellow example we want to filter data using 8th index of our SubCollection.
var gm = new GridifyMapper<TargetType>()
+ .AddMap("prop", (x , index) => x.SubCollection[index].SomeProp);
+
+var gq = new GridifyQuery
+{
+ Filter = "prop[8] > 10"
+};Checkout Use Indexes on Sub-Collections for more information.
Sometimes the default Gridify operators are not enough, For example, if you need an operator for regex matching or when you are using the EntityFramework, you may want to use EF.Functions.FreeText rather than a LIKE with wildcards. In this case, you can define your own operators. (added in v2.6.0)
To define a custom operator, you need to create a class that implements the IGridifyOperator interface. then you need to register it through the global CustomOperators configuration.
TIP
Custom operators must be start with the # character.
class FreeTextOperator : IGridifyOperator
+{
+ public string GetOperator() => "#=";
+ public Expression<OperatorParameter> OperatorHandler()
+ {
+ return (prop, value) => EF.Functions.FreeText(prop, value.ToString());
+ }
+}class RegexMatchOperator : IGridifyOperator
+{
+ public string GetOperator() => "#%";
+ public Expression<OperatorParameter> OperatorHandler()
+ {
+ return (prop, value) => Regex.IsMatch(prop.ToString(), value.ToString());
+ }
+}class InOperator: IGridifyOperator
+{
+ public string GetOperator()
+ {
+ return "#In";
+ }
+
+ public Expression<OperatorParameter> OperatorHandler()
+ {
+ return (prop, value) => value.ToString()
+ .Split(";",StringSplitOptions.RemoveEmptyEntries)
+ .Contains(prop.ToString());
+ }
+}
+
+// usage: .ApplyFiltering("name #In John;David;Felipe")Registration Example:
GridifyGlobalConfiguration.CustomOperators.Register<FreeTextOperator>();
+ GridifyGlobalConfiguration.CustomOperators.Register<RegexMatchOperator>();
+ GridifyGlobalConfiguration.CustomOperators.Register<InOperator>();There are three packages available for gridify in the nuget repository.
TIP
If you are using the Entity framework in your project, you should install the Gridify.EntityFramework package instead of Gridify.
This package has the same functionality as the Gridify package, but it is designed to be more compatible with Entity Framework.
TIP
In order to use Gridify with Elasticsearch it's necessary to install Gridify.Elasticsearch.
If you're developing in a JavaScript or TypeScript environment and need to create dynamic queries on the client side for server-side operations, Gridify also offer a lightweight client library. gridify-client
npm i gridify-clientAfter installing the package, you can use the Gridify namespace to access the package classes and static Extension methods.
using Gridify;There are two ways to start using Gridify:
Using this class you can change the default behavior and configuration of the Gridify library.
The default page size for the paging methods when no page size is specified.
int20By default mappings are case insensitive. For example, name=John and Name=John are considered equal. You can change this behavior by setting this property to true.
boolfalseThis option enables the null keyword in filtering operations, for example, name=null searches for all records with a null value for the name field not the string "null". if you need to search for the string "null" you can disable this option.
booltrueIf true, in filtering and ordering operations, gridify doesn't return any exceptions when a mapping is not defined for the given field.
boolfalseOn nested collections by default gridify adds a null checking condition to prevent the null reference exceptions
e.g () => field != null && field....
some ORMs like NHibernate don't support this. You can disable this behavior by setting this option to true.
boolfalseUsing the Register method of this property you can add your own custom operators.
GridifyGlobalConfiguration.CustomOperators.Register<MyCustomOperator>();To learn more about custom operators, see Custom operator
',24),r=[l];function s(n,d,c,p,h,u){return i(),a("div",null,r)}const b=e(t,[["render",s]]);export{g as __pageData,b as default}; diff --git a/assets/guide_gridifyGlobalConfiguration.md.UeTwzC58.lean.js b/assets/guide_gridifyGlobalConfiguration.md.UeTwzC58.lean.js new file mode 100644 index 00000000..5dc75d62 --- /dev/null +++ b/assets/guide_gridifyGlobalConfiguration.md.UeTwzC58.lean.js @@ -0,0 +1 @@ +import{_ as e,c as a,o as i,U as o}from"./chunks/framework.BZkFhLI2.js";const g=JSON.parse('{"title":"GridifyGlobalConfiguration","description":"","frontmatter":{},"headers":[],"relativePath":"guide/gridifyGlobalConfiguration.md","filePath":"guide/gridifyGlobalConfiguration.md"}'),t={name:"guide/gridifyGlobalConfiguration.md"},l=o("",24),r=[l];function s(n,d,c,p,h,u){return i(),a("div",null,r)}const b=e(t,[["render",s]]);export{g as __pageData,b as default}; diff --git a/assets/guide_gridifyMapper.md.pzrB12Km.js b/assets/guide_gridifyMapper.md.pzrB12Km.js new file mode 100644 index 00000000..65f51303 --- /dev/null +++ b/assets/guide_gridifyMapper.md.pzrB12Km.js @@ -0,0 +1,38 @@ +import{_ as s,c as i,o as a,U as e}from"./chunks/framework.BZkFhLI2.js";const y=JSON.parse('{"title":"GridifyMapper","description":"","frontmatter":{},"headers":[],"relativePath":"guide/gridifyMapper.md","filePath":"guide/gridifyMapper.md"}'),t={name:"guide/gridifyMapper.md"},n=e(`Internally Gridify is using an auto generated mapper that maps your string base field names to actual properties in your entities, but sometimes we don't want to support filtering or sorting on a specific field. If you want to control what field names are mapped to what properties, you can create a custom mapper.
To get a better understanding of how this works, consider the following example:
// sample Entities
+public class Person
+{
+ public string UserName { get; set; }
+ public string FirstName { get; set; }
+ public string LastName { get; set; }
+ public string Password { get; set; }
+ public Contact Contact { get; set; }
+}
+
+public class Contact
+{
+ public string Address { get; set; }
+ public int PhoneNumber { get; set; }
+}In this example we want to:
Password propertyaddress and mobile to the Contact propertyvar mapper = new GridifyMapper<Person>()
+ .GenerateMappings()
+ .RemoveMap(nameof(Person.Password))
+ .AddMap("address", p => p.Contact.Address)
+ .AddMap("mobile", p => p.Contact.PhoneNumber)
+ .AddMap("userName", p => p.UserName, v => v.ToLower());In the following, we will become more familiar with the above methods
This method generates mappings for the properties of the entity, including top-level public properties and properties of nested classes up to the specified nesting depth.
var mapper = new GridifyMapper<Person>()
+ .GenerateMappings();maxNestingDepth parameter. This parameter limits how deep the mappings will be generated for nested classes. Set it to 0 for no nesting or a positive value to control the depth (added in v2.11.0):var mapper = new GridifyMapper<Person>()
+ // Generates mappings for top-level properties and properties of nested classes up to 2 levels deep.
+ .GenerateMappings(2);TIP
Another alternative to generate default mappings for top-level public properties is by passing true to the GridifyMapper constructor. This generates mappings without considering nesting depth.
var mapper = new GridifyMapper<Person>(true);This method removes mapping from the mapper. Usually you will use this method after you have generated the mappings to ignore some properties that you don't want to be supported by Gridify filtering or ordering actions.
This method adds a mapping to the mapper.
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.
in the above example we want to convert the userName value to lowercase before the filtering operation.
mapper = mapper.AddMap("userName", p => p.UserName, v => v.ToLower());This method checks if the mapper has a mapping for the given field name.
This method returns list of current mappings.
var mapperConfig = new GridifyMapperConfiguration()
+{
+ CaseSensitive = false,
+ AllowNullSearch = true,
+ IgnoreNotMappedFields = false
+};
+
+var mapper = new GridifyMapper<Person>(mapperConfig);By default mapper is Case-insensitive but you can change this behavior if you need Case-Sensitive mappings.
boolfalsevar mapper = new GridifyMapper<Person>(q => q.CaseSensitive = true);By setting this to true Gridify don't throw an exception when a field name is not mapped. for instance, in the above example, searching for password will not throw an exception.
boolfalsevar mapper = new GridifyMapper<Person>(q => q.IgnoreNotMappedFields = true);By setting this to false, Gridify don't allow searching on null values using the null keyword for values.
booltruevar mapper = new GridifyMapper<Person>(q => q.AllowNullSearch = false);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 mapper = new GridifyMapper<Level1>()
+ .AddMap("prop1", l1 => l1.Level2List
+ .SelectMany(l2 => l2.Level3List)
+ .Select(l3 => l3.Property1));
+// ...
+var query = level1List.ApplyFiltering("prop1 = 123", mapper);if you have only two-level nesting, you don't need to use SelectMany.
Since version v2.3.0, GridifyMapper AddMap method has a new overload that accepts a index parameter. In the bellow example we want to filter data using 8th index of our SubCollection.
var gq = new GridifyQuery { Filter = "prop[8] > 10" };
+
+var gm = new GridifyMapper<TargetType>()
+ .AddMap("prop", (x , index) => x.SubCollection[index].SomeProp);checkout Passing Indexes for more information.
This method returns the selector expression that you can use it in LINQ queries.
Expression<Func<Person, object>> selector = mapper.GetExpression(nameof(Person.Name));This method returns the selector expression that you can use it in LINQ queries.
LambdaExpression selector = mapper.GetLambdaExpression(nameof(Person.Name));GridifyQuery is a simple class for configuring Filtering, Ordering and Paging.
var gq = new GridifyQuery()
+{
+ Filter = "FirstName=John",
+ Page = 1,
+ PageSize = 20,
+ OrderBy = "Age"
+};
+
+// Apply Filter, Sort and Paging
+Paging<Person> result = personsRepo.Gridify(gq);This extension method, checks if the GridifyQuery (Filter, OrderBy) is valid to use with a custom mapper or the auto generated mapper and returns true or false.
var gq = new GridifyQuery() { Filter = "name=John" , OrderBy = "Age" };
+// true
+bool isValid = gq.IsValid<Person>();var gq = new GridifyQuery() { Filter = "NonExist=John" , OrderBy = "Age" };
+// false (NonExist is not a property of Person)
+bool isValid = gq.IsValid<Person>();var gq = new GridifyQuery() { Filter = "@name=!" , OrderBy = "Age" };
+// false (this is not a valid filter)
+bool isValid = gq.IsValid<Person>();Optionally you can pass a custom mapper to check if the GridifyQuery is valid for that mapper.
var mapper = new GridifyMapper<Person>()
+ .AddMap("name", q => q.Name);
+var gq = new GridifyQuery() { Filter = "name=John" , OrderBy = "Age" };
+
+// false (Age is not mapped)
+bool isValid = gq.IsValid(mapper);This extension method, creates a lambda expression using the GridifyQuery.Filter property that you can use it in the LINQ Where method to filter the data.
var gq = new GridifyQuery() { Filter = "name=John" };
+Expression<Func<T, bool>> expression = gq.GetFilteringExpression<Person>();
+var result = personsRepo.Where(expression);Greetings!
Gridify is an exceptional dynamic LINQ library designed to simplify the process of converting strings into LINQ queries. It offers remarkable performance and ease-of-use, making it effortless to apply filtering, sorting, and pagination utilizing text-based data.
Here are some notable features of Gridify:
To provide a better understanding of Gridify's functionality, we have prepared a few examples:
Filtering is the most expensive feature in Gridify. The following benchmark compares filtering in various popular dynamic LINQ libraries. Interestingly, Gridify outperforms even Native LINQ in terms of speed. It's worth mentioning that other features like Pagination and Sorting in Gridify have minimal impact on performance.
| Method | Mean | Error | StdDev | Ratio | Allocated | Alloc Ratio |
|---|---|---|---|---|---|---|
| Gridify | 599.8 us | 2.76 us | 2.45 us | 0.92 | 36.36 KB | 1.11 |
| Native_LINQ | 649.9 us | 2.55 us | 2.38 us | 1.00 | 32.74 KB | 1.00 |
| DynamicLinq | 734.8 us | 13.90 us | 13.01 us | 1.13 | 119.4 KB | 3.65 |
| Sieve | 1,190.9 us | 7.41 us | 6.93 us | 1.83 | 53.05 KB | 1.62 |
| Fop | 2,637.6 us | 8.59 us | 7.61 us | 4.06 | 321.57 KB | 9.82 |
| CSharp_Scripting | 216,863.8 us | 4,295.66 us | 6,021.92 us | 336.64 | 23660.26 KB | 722.71 |
BenchmarkDotNet v0.13.10, Windows 11 (10.0.22621.2715/22H2/2022Update/SunValley2) 12th Gen Intel Core i7-12800H, 1 CPU, 20 logical and 14 physical cores .NET SDK 8.0.100 [Host] : .NET 8.0.0 (8.0.23.53103), X64 RyuJIT AVX2
This Benchmark is available Here
The ordering query expression can be built with a comma-delimited ordered list of field/property names followed by asc or desc keywords.
By default, if you don't add these keywords, Gridify assumes you need Ascending ordering.
// asc - desc
+var x = personsRepo.ApplyOrdering("Id"); // default ascending its equal to "Id asc"
+var x = personsRepo.ApplyOrdering("Id desc"); // use descending ordering
+
+// multiple orderings example
+var x = personsRepo.ApplyOrdering("Id desc, FirstName asc, LastName");// asc - desc
+var gq = new GridifyQuery() { OrderBy = "Id" }; // default ascending its equal to "Id asc"
+var gq = new GridifyQuery() { OrderBy = "Id desc" }; // use descending ordering
+
+// multiple orderings example
+var gq = new GridifyQuery() { OrderBy = "Id desc, FirstName asc, LastName" };var builder = new QueryBuilder<Person>();
+// asc - desc
+builder.AddOrderBy("Id"); // default ascending its equal to "Id asc"
+builder.AddOrderBy("Id desc"); // use descending ordering
+
+// multiple orderings example
+builder.AddOrderBy("Id desc, FirstName asc, LastName");Sometimes we need to order by nullable types, for example:
personsRepo.OrderBy(p => p.BirthDate.HasValue)to support this behavior, you can use Gridify special characters (? or !) after the property name.
e.g:
To achieve the personsRepo.OrderBy(p => p.BirthDate.HasValue) query, you can use ?:
var x = personsRepo.ApplyOrdering("BirthDate?");and for personsRepo.OrderBy(p => !p.BirthDate.HasValue), you can use !:
var x = personsRepo.ApplyOrdering("BirthDate!");WARNING
These nullable characters will only work on the nullable types.
The QueryBuilder class is really useful if you want to manually build your query Or 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 |
| IsValid | Validates Condition, OrderBy, Query , Mapper and returns a bool |
| 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 |
var builder = new QueryBuilder<Person>()
+ .AddCondition("name=John")
+ .AddOrderBy("age, id");
+
+var query = builder.Build(persons);