FluentCondition 1.0.2

🚀 FluentCondition

English | 中文

English

The Simplest Way to Build Dynamic Queries in .NET

FluentCondition is a powerful, elegant query condition builder that makes complex queries simple and maintainable. Write less code, get more done! 🎯

✨ Why FluentCondition?

Tired of writing repetitive query code? FluentCondition eliminates boilerplate and lets you focus on what matters!

• 🎯 Declarative Design - Define queries with attributes, clean and maintainable
• 🔄 Dual Mode - Works with both in-memory collections (LINQ) and databases (SQL)
• 🛡️ Type Safe - Compile-time checking, catch errors before runtime
• ⚡ High Performance - Expression tree compilation, zero reflection overhead
• 🔒 Secure - Parameterized queries, SQL injection protection built-in
• 🎨 Flexible - Complex condition combinations, OR logic, conditional dependencies

📦 Installation

dotnet add package FluentCondition

Or via Package Manager Console:

Install-Package FluentCondition

🎯 Quick Start (3 Steps!)

Step 1: Define Your Entity

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public string Category { get; set; }
}

Step 2: Create Search Criteria (Just Add Attributes!)

using FluentCondition.Attributes;

public class ProductSearch : ISearchCriteria
{
    [Equal]
    public int? Id { get; set; }
    
    [Contains]
    public string? Name { get; set; }
    
    [GreaterThanOrEqual(FieldName = "Price")]
    public decimal? MinPrice { get; set; }
    
    [In]
    public string[]? Categories { get; set; }
}

Step 3: Use It! (That's It!)

For In-Memory Collections (LINQ)

using FluentCondition.Extensions;

var criteria = new ProductSearch { MinPrice = 100 };
var results = products.Where(criteria).ToList();

For Database Queries (SQL)

Note: SQL generation requires installing an extension package:

• FluentCondition.SqlServer for SQL Server
• FluentCondition.MySql for MySQL

// For SQL Server
using FluentCondition.SqlServer.Extensions;
using FluentCondition.SqlServer.Parameters;

var criteria = new ProductSearch { MinPrice = 100 };
var factory = new SqlServerParameterFactory();
var result = SqlConditionBuilderExtensions.BuildSqlCondition<Product, ProductSearch>(criteria, factory);

// Output: WHERE Price >= @p0
Console.WriteLine($"WHERE {result.WhereClause}");

// Use with ADO.NET
using (var command = new SqlCommand(result.ToSql("SELECT * FROM Product"), connection))
{
    command.Parameters.AddRange(result.Parameters);
    // Execute query...
}

That's it! No more manual query building! 🎉

📚 Supported Operators

🔥 Advanced Features

Multiple Conditions on Same Property (OR/AND)

Use [Combine] attribute to control how multiple conditions on the same property are combined:

public class SearchCriteria
{
    // OR combination (default)
    [Combine(CombineMode.Or)]
    [Contains(FieldName = nameof(Name))]
    [Contains(FieldName = nameof(Description))]
    public string? Q { get; set; }
    // Generates: x.Name.Contains(Q) || x.Description.Contains(Q)
    
    // AND combination
    [Combine(CombineMode.And)]
    [GreaterThan(FieldName = "Price")]
    [LessThan(FieldName = "Price")]
    public decimal? PriceRange { get; set; }
    // Generates: x.Price > PriceRange && x.Price < PriceRange
}

OR Conditions Between Properties

Use [OrWith] to create OR conditions between different properties:

public class SearchCriteria
{
    [Contains]
    [OrWith(nameof(Email))]
    public string? Name { get; set; }
    
    [Contains]
    [OrWith(nameof(Name))]
    public string? Email { get; set; }
}

// Generates: (Name LIKE '%search%' OR Email LIKE '%search%')

Conditional Application (IF)

Use [If] to apply conditions only when certain criteria are met:

public class SearchCriteria
{
    public bool UseAdvanced { get; set; }
    
    // Only apply when UseAdvanced = true
    [Equal]
    [If(nameof(UseAdvanced), CheckType = ConditionCheck.IsTrue)]
    public bool? IsActive { get; set; }
}

Supported Check Types:

• ConditionCheck.Equal - Equal to value
• ConditionCheck.NotEqual - Not equal to value
• ConditionCheck.IsTrue - Is true
• ConditionCheck.IsFalse - Is false
• ConditionCheck.NotNull - Is not null
• ConditionCheck.IsNull - Is null

Field Name Mapping

Map properties to different field names:

[GreaterThan(FieldName = "Age")]
public int? MinAge { get; set; }
// Maps to Age field, not MinAge

Table Alias Support

// Requires FluentCondition.SqlServer or FluentCondition.MySql package
using FluentCondition.SqlServer.Extensions;
using FluentCondition.SqlServer.Parameters;

var factory = new SqlServerParameterFactory();
var result = SqlConditionBuilderExtensions.BuildSqlCondition<Product, ProductSearch>(
    criteria, 
    factory,
    tableAlias: "p");
// Generates: p.Price >= @p0

📖 Complete Example

// Define search criteria
public class ProductSearchCriteria : ISearchCriteria
{
    [Equal]
    public int? Id { get; set; }

    [Contains]
    [OrWith(nameof(Description))]
    public string? Name { get; set; }

    [Contains]
    [OrWith(nameof(Name))]
    public string? Description { get; set; }

    [GreaterThanOrEqual(FieldName = "Price")]
    public decimal? MinPrice { get; set; }

    [LessThanOrEqual(FieldName = "Price")]
    public decimal? MaxPrice { get; set; }

    [In]
    public string[]? Categories { get; set; }

    public bool UseAdvancedSearch { get; set; }

    [GreaterThan(FieldName = "Stock")]
    [If(nameof(UseAdvancedSearch), CheckType = ConditionCheck.IsTrue)]
    public int? MinStock { get; set; }

    // Multiple conditions on same property with OR
    [Combine(CombineMode.Or)]
    [Contains(FieldName = nameof(Name))]
    [Contains(FieldName = nameof(Description))]
    public string? Q { get; set; }
}

// Use it!
var criteria = new ProductSearchCriteria
{
    Name = "keyboard",
    MinPrice = 500,
    MaxPrice = 2000,
    Categories = new[] { "Electronics", "Accessories" },
    UseAdvancedSearch = true,
    MinStock = 10,
    Q = "wireless"
};

// LINQ query
var memoryResults = products.Where(criteria).ToList();

// SQL query (requires FluentCondition.SqlServer or FluentCondition.MySql package)
using FluentCondition.SqlServer.Extensions;
using FluentCondition.SqlServer.Parameters;

var factory = new SqlServerParameterFactory();
var sql = SqlConditionBuilderExtensions.BuildSqlCondition<Product, ProductSearchCriteria>(criteria, factory);
Console.WriteLine(sql.ToSql("SELECT * FROM Product"));
// Output: SELECT * FROM Product WHERE (Name LIKE @p0 OR Description LIKE @p1) 
//         AND Price >= @p2 AND Price <= @p3 AND Categories IN (@p4, @p5) 
//         AND Stock > @p6 AND (Name LIKE @p7 OR Description LIKE @p8)

🧪 Run Examples

cd samples/FluentCondition.Samples
dotnet run

🧪 Run Tests

dotnet test

📄 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.

📧 Support

Have questions or suggestions? Open an issue on GitHub.

⭐ If this project helps you, please give us a Star!

中文

.NET 中最简单的动态查询构建方式

FluentCondition 是一个强大而优雅的查询条件构建器，让复杂查询变得简单易维护。写更少的代码，做更多的事！🎯

✨ 为什么选择 FluentCondition？

厌倦了写重复的查询代码？FluentCondition 帮你消除样板代码，让你专注于真正重要的事情！

• 🎯 声明式设计 - 用特性标记定义查询，代码清晰易维护
• 🔄 双模式支持 - 同时支持内存集合（LINQ）和数据库（SQL）
• 🛡️ 类型安全 - 编译时检查，运行时前捕获错误
• ⚡ 高性能 - 表达式树编译，零反射性能损耗
• 🔒 安全可靠 - 参数化查询，内置 SQL 注入防护
• 🎨 灵活强大 - 支持复杂条件组合、OR 逻辑、条件依赖

📦 安装

dotnet add package FluentCondition

或通过 Package Manager Console:

Install-Package FluentCondition

🎯 快速开始（只需 3 步！）

第 1 步：定义实体类

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public string Category { get; set; }
}

第 2 步：创建查询条件类（只需添加特性！）

using FluentCondition.Attributes;

public class ProductSearch : ISearchCriteria
{
    [Equal]
    public int? Id { get; set; }
    
    [Contains]
    public string? Name { get; set; }
    
    [GreaterThanOrEqual(FieldName = "Price")]
    public decimal? MinPrice { get; set; }
    
    [In]
    public string[]? Categories { get; set; }
}

第 3 步：使用它！（就这么简单！）

内存集合查询（LINQ）

using FluentCondition.Extensions;

var criteria = new ProductSearch { MinPrice = 100 };
var results = products.Where(criteria).ToList();

数据库查询（SQL）

注意： SQL 生成功能需要安装扩展包：

• FluentCondition.SqlServer 用于 SQL Server
• FluentCondition.MySql 用于 MySQL

// 对于 SQL Server
using FluentCondition.SqlServer.Extensions;
using FluentCondition.SqlServer.Parameters;

var criteria = new ProductSearch { MinPrice = 100 };
var factory = new SqlServerParameterFactory();
var result = SqlConditionBuilderExtensions.BuildSqlCondition<Product, ProductSearch>(criteria, factory);

// 输出: WHERE Price >= @p0
Console.WriteLine($"WHERE {result.WhereClause}");

// 在 ADO.NET 中使用
using (var command = new SqlCommand(result.ToSql("SELECT * FROM Product"), connection))
{
    command.Parameters.AddRange(result.Parameters);
    // 执行查询...
}

就这么简单！再也不用手动构建查询了！🎉

📚 支持的操作符

🔥 高级特性

同一属性上的多个条件（OR/AND）

使用 [Combine] 特性控制同一属性上多个条件的组合方式：

public class SearchCriteria
{
    // OR 组合（默认）
    [Combine(CombineMode.Or)]
    [Contains(FieldName = nameof(Name))]
    [Contains(FieldName = nameof(Description))]
    public string? Q { get; set; }
    // 生成: x.Name.Contains(Q) || x.Description.Contains(Q)
    
    // AND 组合
    [Combine(CombineMode.And)]
    [GreaterThan(FieldName = "Price")]
    [LessThan(FieldName = "Price")]
    public decimal? PriceRange { get; set; }
    // 生成: x.Price > PriceRange && x.Price < PriceRange
}

不同属性间的 OR 条件

使用 [OrWith] 在不同属性间创建 OR 条件：

public class SearchCriteria
{
    [Contains]
    [OrWith(nameof(Email))]
    public string? Name { get; set; }
    
    [Contains]
    [OrWith(nameof(Name))]
    public string? Email { get; set; }
}

// 生成: (Name LIKE '%search%' OR Email LIKE '%search%')

条件依赖（IF）

使用 [If] 特性根据其他属性决定是否应用条件：

public class SearchCriteria
{
    public bool UseAdvanced { get; set; }
    
    // 只有当 UseAdvanced = true 时才应用此条件
    [Equal]
    [If(nameof(UseAdvanced), CheckType = ConditionCheck.IsTrue)]
    public bool? IsActive { get; set; }
}

支持的检查类型：

• ConditionCheck.Equal - 等于指定值
• ConditionCheck.NotEqual - 不等于指定值
• ConditionCheck.IsTrue - 为 true
• ConditionCheck.IsFalse - 为 false
• ConditionCheck.NotNull - 不为空
• ConditionCheck.IsNull - 为空

字段名映射

将属性映射到不同的字段名：

[GreaterThan(FieldName = "Age")]
public int? MinAge { get; set; }
// 映射到 Age 字段，而不是 MinAge

表别名支持

// 需要安装 FluentCondition.SqlServer 或 FluentCondition.MySql 扩展包
using FluentCondition.SqlServer.Extensions;
using FluentCondition.SqlServer.Parameters;

var factory = new SqlServerParameterFactory();
var result = SqlConditionBuilderExtensions.BuildSqlCondition<Product, ProductSearch>(
    criteria, 
    factory,
    tableAlias: "p");
// 生成: p.Price >= @p0

📖 完整示例

// 定义查询条件
public class ProductSearchCriteria : ISearchCriteria
{
    [Equal]
    public int? Id { get; set; }

    [Contains]
    [OrWith(nameof(Description))]
    public string? Name { get; set; }

    [Contains]
    [OrWith(nameof(Name))]
    public string? Description { get; set; }

    [GreaterThanOrEqual(FieldName = "Price")]
    public decimal? MinPrice { get; set; }

    [LessThanOrEqual(FieldName = "Price")]
    public decimal? MaxPrice { get; set; }

    [In]
    public string[]? Categories { get; set; }

    public bool UseAdvancedSearch { get; set; }

    [GreaterThan(FieldName = "Stock")]
    [If(nameof(UseAdvancedSearch), CheckType = ConditionCheck.IsTrue)]
    public int? MinStock { get; set; }

    // 同一属性上的多个条件，使用 OR 组合
    [Combine(CombineMode.Or)]
    [Contains(FieldName = nameof(Name))]
    [Contains(FieldName = nameof(Description))]
    public string? Q { get; set; }
}

// 使用示例
var criteria = new ProductSearchCriteria
{
    Name = "键盘",
    MinPrice = 500,
    MaxPrice = 2000,
    Categories = new[] { "电子产品", "配件" },
    UseAdvancedSearch = true,
    MinStock = 10,
    Q = "无线"
};

// LINQ 查询
var memoryResults = products.Where(criteria).ToList();

// SQL 查询（需要安装 FluentCondition.SqlServer 或 FluentCondition.MySql 扩展包）
using FluentCondition.SqlServer.Extensions;
using FluentCondition.SqlServer.Parameters;

var factory = new SqlServerParameterFactory();
var sql = SqlConditionBuilderExtensions.BuildSqlCondition<Product, ProductSearchCriteria>(criteria, factory);
Console.WriteLine(sql.ToSql("SELECT * FROM Product"));
// 输出: SELECT * FROM Product WHERE (Name LIKE @p0 OR Description LIKE @p1) 
//       AND Price >= @p2 AND Price <= @p3 AND Categories IN (@p4, @p5) 
//       AND Stock > @p6 AND (Name LIKE @p7 OR Description LIKE @p8)

🧪 运行示例

cd samples/FluentCondition.Samples
dotnet run

🧪 运行测试

dotnet test

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🤝 贡献

欢迎贡献代码！请随时提交 Pull Request。

📧 支持

有问题或建议？请在 GitHub 上提交 Issue。

⭐ 如果这个项目对你有帮助，请给我们一个 Star！