SmartWhere

📖 API Reference

Complete API reference for the SmartWhere library, including all attributes, enums, interfaces, and extension methods.

🏷️ Attributes

WhereClauseAttribute

The base attribute for simple property filtering.

public class WhereClauseAttribute : Attribute
{
    public string? PropertyName { get; set; }
    public LogicalOperator LogicalOperator { get; set; } = LogicalOperator.AND;
    public bool CaseSensitive { get; set; } = false;
}

Usage Examples:

[WhereClause]                                    // Same property name
[WhereClause("PropertyName")]                    // Different property name
[WhereClause(PropertyName = "PropertyName")]     // Explicit property name
[WhereClause(LogicalOperator = LogicalOperator.OR)]  // OR operator
[WhereClause(CaseSensitive = true)]              // Case sensitive

TextualWhereClauseAttribute

Advanced text search with multiple string methods.

public class TextualWhereClauseAttribute : WhereClauseAttribute
{
    public StringMethod StringMethod { get; set; }
    public bool CaseSensitive { get; set; } = false;
}

Usage Examples:

[TextualWhereClause(StringMethod.Contains)]
[TextualWhereClause("PropertyName", StringMethod.StartsWith)]
[TextualWhereClause(StringMethod.EndsWith, CaseSensitive = true)]

ComparativeWhereClauseAttribute

Numeric and date comparisons with various operators.

public class ComparativeWhereClauseAttribute : WhereClauseAttribute
{
    public ComparisonOperator ComparisonOperator { get; set; }
    public bool IncludeNullValues { get; set; } = true;
}

Usage Examples:

[ComparativeWhereClause("PropertyName", ComparisonOperator.GreaterThan)]
[ComparativeWhereClause(ComparisonOperator.LessThanOrEqual)]
[ComparativeWhereClause("Price", ComparisonOperator.Between, IncludeNullValues = false)]

WhereClauseClassAttribute

Class-level filtering configuration.

public class WhereClauseClassAttribute : Attribute
{
    public StringMethod DefaultStringMethod { get; set; } = StringMethod.Contains;
    public bool CaseSensitive { get; set; } = false;
}

Usage Examples:

[WhereClauseClass]
[WhereClauseClass(DefaultStringMethod = StringMethod.StartsWith)]
[WhereClauseClass(CaseSensitive = true)]

🔢 Enums

StringMethod

Text search methods for TextualWhereClause.

public enum StringMethod
{
    Contains,           // LIKE '%value%'
    NotContains,       // NOT LIKE '%value%'
    StartsWith,        // LIKE 'value%'
    NotStartsWith,     // NOT LIKE 'value%'
    EndsWith,          // LIKE '%value'
    NotEndsWith        // NOT LIKE '%value'
}

SQL Equivalents:

Method	SQL Equivalent	Description
Contains	LIKE '%value%'	Substring search
NotContains	NOT LIKE '%value%'	Exclude substring
StartsWith	LIKE 'value%'	Prefix search
NotStartsWith	NOT LIKE 'value%'	Exclude prefix
EndsWith	LIKE '%value'	Suffix search
NotEndsWith	NOT LIKE '%value'	Exclude suffix

ComparisonOperator

Comparison operators for ComparativeWhereClause.

public enum ComparisonOperator
{
    Equal,                  // =
    NotEqual,               // !=
    GreaterThan,            // >
    NotGreaterThan,         // !>
    GreaterThanOrEqual,     // >=
    NotGreaterThanOrEqual,  // !>=
    LessThan,               // <
    NotLessThan,            // !<
    LessThanOrEqual,        // <=
    NotLessThanOrEqual      // !<=
}

SQL Equivalents:

Operator	SQL Equivalent	Description
Equal	=	Equal to
NotEqual	!=	Not equal to
GreaterThan	>	Greater than
NotGreaterThan	!>	Not greater than
GreaterThanOrEqual	>=	Greater than or equal
NotGreaterThanOrEqual	!>=	Not greater than or equal
LessThan	<	Less than
NotLessThan	!<	Not less than
LessThanOrEqual	<=	Less than or equal
NotLessThanOrEqual	!<=	Not less than or equal

LogicalOperator

Logical operators for combining conditions.

public enum LogicalOperator
{
    AND,    // Logical AND
    OR      // Logical OR
}

Default Behavior:

• WhereClause attributes default to AND
• TextualWhereClause and ComparativeWhereClause inherit this behavior
• Can be explicitly set to OR for alternative logic

🔌 Interfaces

IWhereClause

Marker interface for search request classes.

public interface IWhereClause
{
    // No methods required - it's a marker interface
}

Implementation Requirements:

• All search request classes must implement this interface
• No methods need to be implemented
• Used by SmartWhere to identify filter objects

Example:

public class BookSearchRequest : IWhereClause
{
    [WhereClause]
    public string Title { get; set; }
}

⚡ Extension Methods

Where Extensions

Core filtering extension methods for IQueryable<T>.

public static class WhereExtensions
{
    // Basic filtering
    public static IQueryable<T> Where<T>(this IQueryable<T> query, IWhereClause whereClause);
    
    // Logical combinations
    public static IQueryable<T> And<T>(this IQueryable<T> query, IWhereClause whereClause);
    public static IQueryable<T> Or<T>(this IQueryable<T> query, IWhereClause whereClause);
    public static IQueryable<T> Not<T>(this IQueryable<T> query, IWhereClause whereClause);
}

Usage Examples:

// Basic filtering
var result = _context.Books.Where(request);

// Logical combinations
var result = _context.Books
    .Where(request1)
    .And(request2)
    .Or(request3)
    .Not(request4);

Attribute Extensions

Utility methods for working with attributes.

public static class AttributeExtensions
{
    // Get WhereClause attributes
    public static IEnumerable<WhereClauseAttribute> GetWhereClauseAttributes(this PropertyInfo property);
    
    // Get TextualWhereClause attributes
    public static IEnumerable<TextualWhereClauseAttribute> GetTextualWhereClauseAttributes(this PropertyInfo property);
    
    // Get ComparativeWhereClause attributes
    public static IEnumerable<ComparativeWhereClauseAttribute> GetComparativeWhereClauseAttributes(this PropertyInfo property);
}

⚙️ Configuration

SmartWhereOptions

Global configuration options for SmartWhere.

public class SmartWhereOptions
{
    public StringMethod DefaultStringMethod { get; set; } = StringMethod.Contains;
    public bool CaseSensitive { get; set; } = false;
    public int MaxNestingLevel { get; set; } = 10;
    public bool EnablePerformanceLogging { get; set; } = false;
    public bool ThrowOnInvalidProperty { get; set; } = true;
}

Configuration Example:

// In Program.cs or Startup.cs
services.Configure<SmartWhereOptions>(options =>
{
    options.DefaultStringMethod = StringMethod.StartsWith;
    options.CaseSensitive = true;
    options.MaxNestingLevel = 15;
    options.EnablePerformanceLogging = true;
});

🔧 Advanced Features

Custom Attribute Creation

You can create custom attributes by inheriting from base classes:

public class CustomWhereClauseAttribute : WhereClauseAttribute
{
    public string CustomProperty { get; set; }
    
    public CustomWhereClauseAttribute(string customProperty)
    {
        CustomProperty = customProperty;
    }
}

Reflection Support

SmartWhere provides reflection utilities for advanced scenarios:

// Get all WhereClause properties from a type
var properties = typeof(SearchRequest)
    .GetProperties()
    .Where(p => p.GetCustomAttributes<WhereClauseAttribute>().Any());

// Check if a type implements IWhereClause
bool isWhereClause = typeof(SearchRequest).GetInterfaces().Contains(typeof(IWhereClause));

📊 Performance Considerations

Expression Tree Generation

• SmartWhere generates expression trees at runtime
• Minimal overhead for simple filters (~0.1ms)
• Complex nested filters may take longer (~0.5ms)
• Expression trees are cached for repeated use

Memory Usage

• Minimal additional memory footprint
• Expression trees are lightweight
• No memory leaks from attribute usage
• Efficient property access patterns

Compilation Overhead

• First-time compilation may be slower
• Subsequent uses are optimized
• Consider pre-compiling for production use
• Monitor performance in development

🚨 Error Handling

Common Exceptions

// PropertyNotFoundException
// Thrown when PropertyName doesn't exist in entity
[WhereClause("NonExistentProperty")]
public string Name { get; set; }

// InvalidOperationException
// Thrown when logical operators are misused
[WhereClause(LogicalOperator.OR)]
[WhereClause(LogicalOperator.AND)]  // Mixed operators without clear logic
public string Title { get; set; }

Validation

SmartWhere performs validation at runtime:

• Property existence checks
• Type compatibility validation
• Logical operator validation
• Nested property depth validation

🔗 Related Pages

• 🏠 Home Page
• 🚀 Getting Started Guide
• 📋 Details and Rules
• 🔧 Advanced Features

---

Last Updated: 2025-01-16
Version: 2.2.3

This site is open source. Improve this page.