romaklayt.DynamicFilter.Binder.Net 2.5.9

romaklayt.DynamicFilter

Simple filter for .net WebApi that enables your endpoint to query your requests by url.

It provides ways to query, order and page your webapi and mvc.

.Net Core and .Net

First, download the packages into your project from nuget

nuget install romaklayt.DynamicFilter.Extensions.EntityFrameworkCore
nuget install romaklayt.DynamicFilter.Binder.Net

and, if you need, add to your ConfigureServices Startup.cs class for register value provider (JSON) for body JSON POST request support (providers for form-data, x-www-form-urlencoded work them by default)

services.AddControllers(options => options.ValueProviderFactories.Add(new JsonBodyValueProviderFactory()));

If you need to use DynamicFilter with IAsyncEnumerable or IAsyncQueryable use the package

nuget install romaklayt.DynamicFilter.Extensions.Async

After downloaded, go to your webapi and create an get or post endpoint receiving IDynamicComplex as parameter.

[HttpGet]
public Task<List<User>> Get([FromQuery] DynamicComplex filter)

Now you can query your endpoint with the DynamicFilter properties. Check "tests" folder on the Api projects for examples.

[HttpGet]
public Task<List<User>> Get([FromQuery] DynamicComplex filter)
{
    return users.Apply(filter).ToList();
}

DynamicFilter.Parser will transform your URI Queries into .Net Expressions. That way, you can use these expressions to filter your values into your database repository.

Simple Filter

You can use a DynamicComplexModel model for filtering. A DynamicFilterModel model without additional properties is also available.

public Task<List<User>> Get([FromQuery] DynamicComplex filter) #or DynamicFilterModel
{
    return users.Apply(filter).ToList(); #ApplyFilter for DynamicFilterModel
}

Example Uri:

GET http://url?filter=name==Bruno

Expression generated by Uri:

x => x.Name == "Bruno"

Filters are also supported for nested collections.

GET http://url?filter=roles.name==admin

Your request will be converted to:

users.Where(x => x.Roles.Any(y => y.Name == "admin"))

If the standard behavior for arrays and lists using the Any method does not suit you, you can add the '=' sign after the comparison operator, after which the system will use the All method for arrays:

GET http://url?filter=roles.name===admin

Your request will be converted to:

users.Where(x => x.Roles.All(y => y.Name == "admin"))

The parser supports the count property for the collection, you can use it as a regular collection property:

GET http://url?filter=roles.count==1

If you need to filter values by default for the value type, use \default:

GET http://url?filter=roles.name==\default

Complex Filter

Boolean operators &&(and) and ||(or) are supported.

Example Uri:

GET http://url?filter=name==Bruno&&lastname@=r&&age>=27

Since version 2.0 more complex filters are available. You can use brackets to create more complex expressions.

GET http://url?filter=(name==Bruno&&lastname@=r)||(age>=27)

GET http://url?filter=(name==Bruno&&lastname@=r)||(age>=27&&name==Bruno)

You can nest multiple parentheses to create complex expressions.

GET http://url?filter=((name==Bruno&&lastname@=r)||(age>=27))&&roles.name==Admin

Attention!

For correct parsing of the filter, when using brackets, enclose all logical elements in brackets, for example:

Not correct

GET http://url?filter=((name==Bruno&&lastname@=r)||age>=27)&&roles.name==Admin

Correct (age>=27 in brackets)

GET http://url?filter=((name==Bruno&&lastname@=r)||(age>=27))&&roles.name==Admin

Nested Filer

Example Uri:

GET http://url?filter=address.number==23

Expression generated by Uri:

x => x.Address.Number == 23

Ordering

You can also order your queries via DynamicFilter. You simply need to add an order parameter on your query, where you specify the property you'll use for order.

GET http://url?filter=name==Bruno&order=name

Default order type is Ascending. You can adding a - before the name switches to sorting descendingly..

GET http://url?filter=name==Bruno&order=name

GET http://url?filter=name==Bruno&order=-name

To sort by multiple properties:

GET http://url?filter=name==Bruno&order=name,firstname

GET http://url?filter=name==Bruno&order=-name,-firstname

If you do not specify the sort type, asc is used by default.

On your DynamicFilter object received on the endpoint, you'll get the orderType as an Enum, this way you can order by the type specified on enum.

public Task<List<User>> Get([FromQuery] DynamicComplex filter)
{
    return users.Apply(filter).ToList();
}

Pagging

GET http://url?filter=name@=*b&order=name&page=1&pagesize=10

In romaklayt.DynamicFilter.Extensions.* there is a method of expanding the ToPageModel which returns PageModel with info about page and your filtered data.

var page = users.ToPageModel(filterModel);

The PageModel is built on top of the List<T> so to add page information to the server response you need to add an AddPageInfoFilter which will write the page information to the headers.

services.AddControllers(options =>
        {
            options.Filters.Add(new PageInfoWriter());
        });

If you no need page info, you simply needs to add the parameters page and pagesize on your get request.

result = result.ApplyFilter(filter); #page mode without additional info

If you specify the page number and size in the filter model, pagination is disabled when using ApplyFilter. You can also disable pagination by forcibly calling:

result = result.ApplyFilter(filter, false); #only filtering without pagination

Example:

[HttpGet("page")]
public async Task<PageModel<User>> GetPage([FromQuery] DynamicComplex filterModel)
{
    return Data.Users.ToPageModel(filterModel);
}

Select

To select, you simply needs to add the parameter select with the properties you want to select from. It will render either an linq select and a plain string select.

GET http://url?select=name,age

If you select a nested property, from default, the properties from the root model will be ignored, to select all the root properties, use the word root.

GET http://url?select=address.zip,root #select Address.Zip and all root properties

If you need to select properties from only one model (the GetById method, for example), you can also use the method ** ApplyFilter**.

[HttpGet("{id}")]
public async Task<object> GetById([FromQuery] DynamicSelect dynamicSelectModel, Guid id)
{
    return await Data.Users.ApplySelect(dynamicSelectModel).DynamicFirstOfDefault("Id", id);
}

Filter operator support

All operators support negation, you need to put "!" before the operator (e.g. !== for Equals)