klod68/criteria-pattern

---

name: criteria-pattern description: "Use when a search, filter, or query method has more than 2–3 optional parameters and the parameter list keeps growing, or when adding a new filter requires changing method signatures across multiple call sites. Covers the typed criteria object pattern (e.g., ProductCriteria), conditional LINQ filtering, paged variants with IPagedRequest, and naming conventions for ByCriteria, ById, and Paged overloads. Domain: Architecture, Query Design. Level: Foundational. Tags: criteria, query, filtering, search, specification."

Criteria Pattern

Problem

Methods with growing parameter lists for filtering (e.g., GetProducts(string? name, decimal? minPrice, decimal? maxPrice, string? category, bool? isActive)) become unwieldy. Adding a filter requires changing the method signature everywhere.

Solution: Typed Criteria Object

Encapsulate filter parameters in a typed criteria object. The method accepts one TCriteria parameter instead of N optional parameters. Adding a filter means adding a property — no signature changes anywhere.

Criteria Class

public sealed class ProductCriteria
{
    public string? NameSearch { get; set; }
    public string? Category { get; set; }
    public decimal? MinPrice { get; set; }
    public decimal? MaxPrice { get; set; }
    public bool? IsActive { get; set; }
}

Service Interface

public interface IProductService
{
    Task<IReadOnlyList<Product>> GetProductsAsync(
        ProductCriteria criteria,
        CancellationToken ct = default);
}

Implementation — Apply Filters Conditionally

public async Task<IReadOnlyList<Product>> GetProductsAsync(
    ProductCriteria criteria,
    CancellationToken ct = default)
{
    ArgumentNullException.ThrowIfNull(criteria);

    var query = _products.AsQueryable();

    if (!string.IsNullOrWhiteSpace(criteria.NameSearch))
        query = query.Where(p => p.Name.Contains(criteria.NameSearch, StringComparison.OrdinalIgnoreCase));

    if (!string.IsNullOrWhiteSpace(criteria.Category))
        query = query.Where(p => p.Category == criteria.Category);

    if (criteria.MinPrice.HasValue)
        query = query.Where(p => p.Price >= criteria.MinPrice.Value);

    if (criteria.MaxPrice.HasValue)
        query = query.Where(p => p.Price <= criteria.MaxPrice.Value);

    if (criteria.IsActive.HasValue)
        query = query.Where(p => p.IsActive == criteria.IsActive.Value);

    return query.ToList();
}

Method Naming Variants

| Variant | Purpose | Example | |---------|---------|---------| | *ByCriteria | Filter by multiple fields | GetProductsByCriteriaAsync(ProductCriteria) | | *ById | Filter by primary key | GetProductByIdAsync(int id) | | *Paged | Criteria + pagination | GetProductsPagedAsync(ProductCriteria, IPagedRequest) |

public interface IProductService
{
    Task<IReadOnlyList<Product>> GetProductsByCriteriaAsync(ProductCriteria criteria, CancellationToken ct = default);
    Task<Product?> GetProductByIdAsync(int id, CancellationToken ct = default);
    Task<IPagedResult<Product>> GetProductsPagedAsync(ProductCriteria criteria, IPagedRequest paging, CancellationToken ct = default);
}

When to Use

• Any search/filter/query operation with more than 2–3 optional parameters
• Product catalogs, user directories, log searches, report filters
• Operations where filter combinations grow over time
• API endpoints accepting complex query parameters

When NOT to Use

• Single-key lookups (GetById) — a simple parameter is clearer
• Operations with exactly one required filter — no benefit over a direct parameter
• Write operations — criteria are for reads

Gotchas

1. All properties are nullable — a null or unset property means "don't filter on this field."
2. Criteria classes are plain POCOs — data containers with no behavior.
3. Name the class {Entity}Criteria for consistency across the codebase.
4. Always guard with ArgumentNullException.ThrowIfNull(criteria) — the criteria object itself must not be null.
5. Combine with AsNoTracking() for read-only queries in EF Core.

Related Skills

• Guard Clause Validation (validate criteria object at the boundary)
• Gen Service Interface (generate service interface with criteria-based queries)