romaklayt.DynamicFilter.Common 1.8.0

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
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()));

.Net Framework (>=4.6.1)

First, download the packages into your project from nuget

nuget install romaklayt.DynamicFilter.Extensions

If you need to add a filter to the web api controller use the package

nuget install romaklayt.DynamicFilter.Binder.NetFramework.WebApi

and, if you need, add to your WebApiConfig class for register value providers (form-data, x-www-form-urlencoded and JSON) for body POST request

config.AddDynamicFilterProviders();

If you need to add a filter to the MVC controller use the package

nuget install romaklayt.DynamicFilter.Binder.NetFramework.Mvc

and, if you need, add to your Application_Start Global.asax.cs class for register value providers (form-data, x-www-form-urlencoded and JSON) for body POST request

DynamicFilterProviders.AddProviders();

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 DynamicComplexModel as parameter.

[HttpGet]
public Task<List<User>> Get(DynamicComplexModel 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(DynamicComplexModel filter)
{
    var result = this.users.UseFilter(filter);

    return Task.FromResult(result.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(DynamicComplexModel filter) #or DynamicFilterModel
{
    var result = users.UseFilter(filter);

    return Task.FromResult(result.ToList());
}

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"))

Complex Filter

Example Uri:

GET http://url?filter=name=Bruno,lastname%r,age>=27

Expression generated by Uri:

x => x.Name == "Bruno" 
  && x.LastName.ToLower().Contains("r") 
  && x.Age >= 27

You can add conditions to your filter sorting your filters with a comma (,), as shown above.

Nested Filer

Example Uri:

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

Expression generated by Uri:

x => x.Address.Number == 23

Multiple filter values for a single property

Such a query will select all entities whose age corresponds to 23, 28 or 27 years

GET http://url?filter=age=[23|28|37] #

To recognize the query, you need to put the values in square brackets [ and ]. The values inside the brackets must be separated by '|' (which will be equivalent to or) or '~' (which will be equivalent to and). Comparison operators are available the same as by default.

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 specify the order type with an equals (=) Asc or Desc after the property.

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

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

To sort by multiple properties:

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

GET http://url?filter=name=Bruno&order=name=desc,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(DynamicComplexModel filter)
{
    var result = users.UseFilter(filter);

    return Task.FromResult(result.ToList());
}

Pagging

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

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

var page = users.ToPagedList(filterModel);

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

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

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

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

Example:

[HttpGet("page")]
public async Task<PageModel<User>> GetPage(DynamicComplexModel filterModel)
{
    var filteredUsers = await Data.Users.UseFilter(filterModel);
    return await filteredUsers.ToPagedList(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 ** UseFilter**.

[HttpGet("{id}")]
public async Task<object> GetById(DynamicSelectModel dynamicSelectModel, Guid id)
{
    var user = await Data.Users.UseSelect(dynamicSelectModel).FirstOrDefaultAsync(user => user.Id == id);
    return user;
}

Filter operator support

• Equals (=)

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

• Contains Invariant Case (%)

GET http://url?filter=name%b

• Contains Case Sensitive (%%)

GET http://url?filter=name%%B

• GreaterThan (>)

GET http://url?filter=age>15

• GreaterOrEqual (>=)

GET http://url?filter=age>=15

• LessThan (<)

GET http://url?filter=age<15

• LessOrEqual (<=)

GET http://url?filter=age<=15

• NotEquals (!=)

GET http://url?filter=age!=15