Gridify

Gridify is a dynamic LINQ library that converts strings into LINQ queries. It is designed for high performance and ease of use when applying data operations via text-based inputs.

Key capabilities include:

• Query Operations: Supports filtering, sorting, and pagination.
• Complex Queries: Supports nested queries, sub-collections, and mapping from strings to objects.
• Optimization: Supports query compilation for better performance.
• Compatibility:
  • Works with any collection supporting LINQ.
  • Compatible with object-mappers like AutoMapper.
  • Compatible with ORMs, specifically Entity Framework.
  • Supports Elasticsearch DSL queries.
• Ecosystem: Includes a Javascript/Typescript client called gridify-client.

Gridify is a modern dynamic LINQ library designed to simplify converting text-based strings into LINQ queries. It provides a high-performance alternative to GraphQL or OData by allowing front-end clients to selectively filter, sort, and paginate resources, requesting only the necessary records.

Key capabilities include:

• Filtering, Sorting, and Pagination: Apply these operations using simple string syntax.
• Complex Query Support: Handles nested queries, sub-collections, and string-to-object mapping.
• Performance: Supports query compilation and collection indexes.
• Extensibility: Allows for custom operators.
• Compatibility: Works with ORMs (especially Entity Framework), object-mappers (like AutoMapper), Elasticsearch, and any collection supported by LINQ.

Gridify can be used in two primary ways:

1. Extension Methods: Use the built-in extension methods provided by the library to apply queries to your data sources.
2. QueryBuilder: Use the QueryBuilder class to programmatically construct dynamic queries.

When using the Gridify extension method for pagination, the result is wrapped in a Paging<T> object. This DTO is designed to provide both the current page of data and the metadata required for client-side pagination controls.

public class Paging<T>
{
    public int Count { get; set; } // Total number of records across all pages
    public IEnumerable<T> Data { get; set; } // The records for the current page
}

The GridifyQuery class is used to encapsulate parameters for filtering, ordering, and paging data. You can instantiate it and set the Filter, Page, PageSize, and OrderBy properties. Once configured, you can apply these settings to a repository or collection using the .Gridify() extension method.

var gq = new GridifyQuery()
{
    Filter = "FirstName=John",
    Page = 1,
    PageSize = 20,
    OrderBy = "Age"
};

// Apply Filter, Sort and Paging
Paging<Person> result = personsRepo.Gridify(gq);

The GridifyQuery class is used to configure how data is filtered, sorted, and paginated. While often provided automatically by API controllers, you can instantiate it manually.

Key properties:

• Filter: A string representing the filtering conditions.
• IsSortAsc: A boolean indicating if sorting should be ascending.
• Page: The current page number.
• PageSize: The number of items per page.
• SortBy: The field name to sort by.

var gQuery = new GridifyQuery()
{
    Filter = "FirstName==John",
    IsSortAsc = false,
    Page = 1,
    PageSize = 20,
    SortBy = "LastName"
};

Paging<Person> pData = myDbContext.Persons.Gridify(gQuery);

// pData.TotalItems => Count of persons matching the filter
// pData.Items      => The subset of items for the requested page

Gridify is optimized for performance, performing nearly identically to native LINQ in modern .NET environments (such as .NET 10).

Key Performance Notes:

• Filtering: This is the most expensive operation in Gridify. While Gridify performs nearly as well as native LINQ, native LINQ performance has caught up due to improvements in the .NET runtime.
• Pagination and Sorting: These operations have minimal performance impact.
• Comparison: In benchmarks, Gridify significantly outperforms other dynamic LINQ libraries like Sieve, DynamicLinq, and Fop, and is vastly faster than CSharp_Scripting.

Gridify is optimized for ASP.NET APIs. You can use GridifyQuery as a parameter in your controller actions to automatically handle filtering, sorting, and pagination from query strings.

Example request URL: http://exampleDomain.com/api/GetPersons?pageSize=100&page=1&sortBy=FirstName&isSortAsc=false&filter=Age%3D%3D10

// ApiController

[Produces(typeof(Paging<Person>))]
public IActionResult GetPersons([FromQuery] GridifyQuery gQuery)
{
    // Gridify applies Filter, Sort & Apply Paging
    return myDbContext.Persons.Gridify(gQuery);
}

Since version v2.15.0, Gridify supports filtering on indexable properties by specifying an index or key within square brackets [ ]. This requires defining mappings via GridifyMapper for the target properties.

var gm = new GridifyMapper<TargetType>()
      .AddMap("arrayProp", (target, index) => target.MyArray[index].Prop)
      .AddMap("dictProp", (target, key) => target.MyDictionary[key]);

var gq = new GridifyQuery
{
    Filter = "arrayProp[8] > 10, dictProp[name] = John"
};

To use Gridify with Elasticsearch, you must install the Gridify.Elasticsearch package. This package provides extension methods for the Elastic.Clients.Elasticsearch .NET client to convert Gridify filters, sortings, and paging into Elasticsearch DSL queries.

# Package Manager
Install-Package Gridify.Elasticsearch -Version {{ $version }}

# .NET CLI
dotnet add package Gridify.Elasticsearch --version {{ $version }}