MasterNeverDown.DataFilter 1.0.3

MasterNeverDown.DataFilter - Expression Tree Filter Extension

A high-performance, type-safe generic filter library for C# that uses Expression Trees to dynamically build LINQ query conditions. Designed for IQueryable<T> (e.g., EF Core) to enable database-level filtering (instead of in-memory filtering), significantly improving performance for large datasets.

📦 Installation

.NET CLI

dotnet add package MasterNeverDown.DataFilter

NuGet Package Manager

Install-Package MasterNeverDown.DataFilter

PackageReference

<PackageReference Include="MasterNeverDown.DataFilter" Version="1.0.0" />

🚀 Quick Start

Step 1: Define Your Entity

public class User
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public int Age { get; set; }
    public DateTime CreateTime { get; set; }
    public string? Email { get; set; }
    // Nested property example
    public UserProfile Profile { get; set; } = new UserProfile();
}

public class UserProfile
{
    public string Address { get; set; } = string.Empty;
    public int PhoneNumber { get; set; }
}

Step 2: Build Filter Conditions

using GenericFilter.Models;
using GenericFilter.Enums;
using GenericFilter.Extensions;

// Create filter request
var filterRequest = new FilterRequest
{
    UseAndLogic = true, // Use AND to combine conditions (default: true)
    Conditions = new List<FilterCondition>
    {
        // Age >= 25
        new FilterCondition 
        { 
            FieldName = "Age", 
            Operator = FilterOperator.GreaterThanOrEqual, 
            Value = 25 
        },
        // Name contains "Zhang" (case-insensitive in EF Core)
        new FilterCondition 
        { 
            FieldName = "Name", 
            Operator = FilterOperator.Contains, 
            Value = "Zhang" 
        },
        // Nested property: Profile.Address contains "Beijing"
        new FilterCondition 
        { 
            FieldName = "Profile.Address", 
            Operator = FilterOperator.Contains, 
            Value = "Beijing" 
        },
        // Email is not null
        new FilterCondition 
        { 
            FieldName = "Email", 
            Operator = FilterOperator.IsNotNull, 
            Value = null 
        }
    }
};

Step 3: Apply Filter to Query

// For in-memory collections (IEnumerable)
var users = new List<User> { /* Your data */ }.AsQueryable();
var filteredUsers = users.ApplyExpressionFilter(filterRequest).ToList();

// For EF Core (database-level filtering)
// var filteredDbUsers = _dbContext.Users.ApplyExpressionFilter(filterRequest).ToListAsync();

✨ Core Features

Supported Filter Operators

Key Advantages

1. High Performance: Translates to SQL (for EF Core) and filters at the database level (no in-memory overhead)
2. Type Safety: Compile-time checking for property names and value types
3. Nested Properties: Support for nested properties (e.g., Profile.Address, Order.Product.Name)
4. Flexible Logic: Combine conditions with AND/OR logic
5. Automatic Type Conversion: Converts filter values to match property types (e.g., string "25" → int 25)
6. EF Core Compatibility: Fully compatible with EF Core 6+/7+/8+ (translates to efficient SQL)

📚 API Reference

Extension Method: ApplyExpressionFilter<T>

Model: FilterRequest

Model: FilterCondition

💡 Advanced Examples

Example 1: OR Logic Combination

var filterRequest = new FilterRequest
{
    UseAndLogic = false, // Use OR instead of AND
    Conditions = new List<FilterCondition>
    {
        new FilterCondition { FieldName = "Age", Operator = "GreaterThanOrEqual", Value = 30 },
        new FilterCondition { FieldName = "Name", Operator = "Contains", Value = "Admin" }
    }
};

// Result: Users where Age >=30 OR Name contains "Admin"
var filteredUsers = _dbContext.Users.ApplyExpressionFilter(filterRequest).ToListAsync();

Example 2: EF Core with Pagination/Sorting

// Combine filter with pagination and sorting
var pageNumber = 1;
var pageSize = 10;

var query = _dbContext.Users
    .ApplyExpressionFilter(filterRequest)
    .OrderBy(u => u.CreateTime)
    .Skip((pageNumber - 1) * pageSize)
    .Take(pageSize);

var result = await query.ToListAsync();
var totalCount = await _dbContext.Users.ApplyExpressionFilter(filterRequest).CountAsync();

Example 3: Filter DateTime Properties

var filterRequest = new FilterRequest
{
    Conditions = new List<FilterCondition>
    {
        new FilterCondition 
        { 
            FieldName = "CreateTime", 
            Operator = "GreaterThanOrEqual", 
            Value = new DateTime(2024, 1, 1) 
        }
    }
};

// EF Core translates to: WHERE CreateTime >= '2024-01-01 00:00:00'
var filteredUsers = await _dbContext.Users.ApplyExpressionFilter(filterRequest).ToListAsync();

⚠️ Important Notes

1. Property Name Case Sensitivity:

   • Property names must match the entity's property names (case-sensitive in C#). For example: FieldName = "Name" (not "name" or "NAME") for a property public string Name { get; set; }.

2. EF Core Translation Limits:

   • Some string operations (e.g., Contains) are case-insensitive in SQL Server (depends on collation), but case-sensitive in in-memory collections.
   • Complex nested properties (e.g., User.Orders[0].Product.Name) are not supported (only dot-separated nested properties like User.Profile.Address).

3. Type Conversion:

   • The library will attempt to convert the Value to the property's type (e.g., string "25" → int 25). If conversion fails, the condition is ignored (no exception thrown).

4. Null Handling:

   • For IsNull/IsNotNull, set Value = null (the value is ignored for these operators).
   • For nullable value types (e.g., int?, DateTime?), IsNull/IsNotNull works as expected.

🛠️ Troubleshooting

Common Issues

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an Issue if you find a bug or have a feature request.

Contribution Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📞 Support

If you have any questions or need help, please open an issue on the GitHub repository or contact the maintainers at [your-email@example.com].

wechat: 东百牧码人

Changelog

• v1.0.0: Initial release with core expression tree filtering functionality.
• Support for all standard filter operators and nested properties.
• Full compatibility with EF Core 6+/7+/8+ and .NET 6+/7+/8+.