SmartWhere

🚀 Getting Started Guide

Welcome to SmartWhere! This guide will help you get started with the library quickly and efficiently.

📦 Installation

NuGet Package Installation

Install the SmartWhere NuGet package using one of these methods:

# Package Manager Console
PM> Install-Package SmartWhere

# .NET CLI
dotnet add package SmartWhere

# NuGet Package Manager
Install-Package SmartWhere

Package Reference

Add this to your .csproj file:

<PackageReference Include="SmartWhere" Version="2.2.3" />

🔧 Basic Setup

1. Add Using Statement

Add the following using statement to your files:

using SmartWhere;

2. Create Your First Search Request

Create a class that implements IWhereClause:

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

    [WhereClause]
    public string Author { get; set; }

    [WhereClause]
    public int? PublishedYear { get; set; }
}

3. Use SmartWhere in Your Queries

[HttpPost]
public IActionResult SearchBooks(BookSearchRequest request)
{
    var result = _context.Books
        .Where(request)  // 🎯 SmartWhere magic happens here!
        .ToList();

    return Ok(result);
}

📚 Complete Example

Here’s a complete working example:

Entity Classes

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Author { get; set; }
    public int PublishedYear { get; set; }
    public decimal Price { get; set; }
    public string Genre { get; set; }
}

public class Publisher
{
    public int Id { get; set; }
    public string Name { get; set; }
    public List<Book> Books { get; set; } = new();
}

Search Request

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

    [WhereClause("Author")]
    public string AuthorName { get; set; }

    [WhereClause("PublishedYear")]
    public int? Year { get; set; }

    [WhereClause("Publisher.Name")]
    public string PublisherName { get; set; }
}

Controller Usage

[ApiController]
[Route("api/[controller]")]
public class BooksController : ControllerBase
{
    private readonly ApplicationDbContext _context;

    public BooksController(ApplicationDbContext context)
    {
        _context = context;
    }

    [HttpPost("search")]
    public async Task<IActionResult> SearchBooks(AdvancedBookSearchRequest request)
    {
        var books = await _context.Books
            .Include(b => b.Publisher)
            .Where(request)
            .ToListAsync();

        return Ok(books);
    }
}

🎯 Key Concepts

1. IWhereClause Interface

All search request classes must implement this interface:

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

2. WhereClause Attribute

The basic attribute for simple property filtering:

[WhereClause]                    // Same property name
[WhereClause("PropertyName")]    // Different property name
[WhereClause(PropertyName = "PropertyName")]  // Explicit property name

3. Property Mapping

SmartWhere automatically maps properties between your request object and entity properties:

// Request property: AuthorName
// Entity property: Author
[WhereClause("Author")]
public string AuthorName { get; set; }

🔍 Advanced Usage

Text Search

public class TextSearchRequest : IWhereClause
{
    [TextualWhereClause(StringMethod.Contains)]
    public string Title { get; set; }

    [TextualWhereClause(StringMethod.StartsWith)]
    public string Author { get; set; }
}

Numeric Comparisons

public class NumericSearchRequest : IWhereClause
{
    [ComparativeWhereClause(ComparisonOperator.GreaterThan)]
    public int? MinYear { get; set; }

    [ComparativeWhereClause(ComparisonOperator.LessThan)]
    public decimal? MaxPrice { get; set; }
}

Logical Operators

public class LogicalSearchRequest : IWhereClause
{
    [WhereClause(LogicalOperator.OR)]
    public string Title { get; set; }

    [WhereClause(LogicalOperator.OR)]
    public string Author { get; set; }
}

🚨 Common Pitfalls

1. Missing Interface Implementation

❌ Wrong:

public class SearchRequest  // Missing IWhereClause
{
    [WhereClause]
    public string Name { get; set; }
}

✅ Correct:

public class SearchRequest : IWhereClause
{
    [WhereClause]
    public string Name { get; set; }
}

2. Incorrect Property Names

❌ Wrong:

[WhereClause("NonExistentProperty")]
public string Name { get; set; }

✅ Correct:

[WhereClause("Name")]  // Property exists in entity
public string Name { get; set; }

3. Missing Include Statements

❌ Wrong:

var result = _context.Books
    .Where(request)  // Will fail for nested properties
    .ToList();

✅ Correct:

var result = _context.Books
    .Include(b => b.Author)
    .Include(b => b.Publisher)
    .Where(request)
    .ToList();

🔗 Next Steps

• Read the Details and Rules for comprehensive understanding
• Explore Advanced Features for complex scenarios
• Check Examples and Scenarios for real-world usage
• Review API Reference for complete documentation

💡 Tips for Success

1. Start Simple: Begin with basic WhereClause attributes
2. Test Incrementally: Add one filter at a time
3. Use IntelliSense: SmartWhere provides full IntelliSense support
4. Check Entity Properties: Ensure property names match your entities
5. Include Dependencies: Use Include() for nested property access

---

Last Updated: 2025-01-16
Version: 2.2.3

This site is open source. Improve this page.