DesignPatterns.Specification.Net 26.2.11.1

DesignPatterns.Specification.Net

A lightweight, fluent Specification Pattern library for .NET that helps you build reusable, composable, and testable query logic. Works seamlessly with Entity Framework Core and in-memory collections.

📦 Installation

# Core library
dotnet add package DesignPatterns.Specification.Net

# Entity Framework Core integration
dotnet add package DesignPatterns.Specification.Net.EntityFrameworkCore

🎯 Why Use This Library?

The Specification pattern helps you:

• Encapsulate query logic in reusable, testable classes
• Eliminate duplicate queries across your application
• Compose complex queries using fluent, readable syntax
• Separate concerns by keeping query logic out of repositories and services
• Test easily with in-memory evaluation
• Apply consistently to both EF Core and in-memory collections

🚀 Quick Start

1. Define a Specification

using DesignPatterns.Specification.Net;

public class ActiveCustomersSpec : Specification<Customer>
{
    public ActiveCustomersSpec()
    {
        Query
            .Where(c => c.IsActive)
            .OrderBy(c => c.Name);
    }
}

2. Use with Entity Framework Core

// Apply specification to DbSet
var activeCustomers = await dbContext.Customers
    .WithSpecification(new ActiveCustomersSpec())
    .ToListAsync(cancellationToken);

// Or use the direct extension
var activeCustomers = await dbContext.Customers
    .ToListAsync(new ActiveCustomersSpec(), cancellationToken);

3. Use with In-Memory Collections

var customers = new List<Customer> { /* ... */ };

// Evaluate specification against in-memory data
var activeCustomers = new ActiveCustomersSpec().Evaluate(customers);

🎨 Features

✅ Fluent Query Builder

Build complex queries with an intuitive fluent API:

public class CustomerSearchSpec : Specification<Customer>
{
    public CustomerSearchSpec(string searchTerm, int page, int pageSize)
    {
        Query
            .Where(c => c.IsActive)
            .Search(c => c.Name, $"%{searchTerm}%")
            .Search(c => c.Email, $"%{searchTerm}%")
            .OrderBy(c => c.Name)
            .Skip((page - 1) * pageSize)
            .Take(pageSize)
            .Include(c => c.Orders)
            .ThenInclude(o => o.OrderItems)
            .AsNoTracking();
    }
}

✅ Projection Support

Transform query results with type-safe projections:

public class CustomerNamesSpec : Specification<Customer, string>
{
    public CustomerNamesSpec()
    {
        Query
            .Where(c => c.IsActive)
            .Select(c => c.Name)
            .OrderBy(name => name);
    }
}

// Usage
var names = await dbContext.Customers
    .ToListAsync(new CustomerNamesSpec(), cancellationToken);

✅ Single Result Queries

Optimize queries that return a single result:

public class CustomerByIdSpec : SingleResultSpecification<Customer>
{
    public CustomerByIdSpec(int id)
    {
        Query
            .Where(c => c.Id == id)
            .Include(c => c.Orders);
    }
}

// Usage
var customer = await repository.FirstOrDefaultAsync(
    new CustomerByIdSpec(customerId), 
    cancellationToken
);

✅ Advanced EF Core Features

public class OptimizedOrdersSpec : Specification<Order>
{
    public OptimizedOrdersSpec()
    {
        Query
            .Where(o => o.Total > 1000)
            .Include(o => o.Customer)
            .Include(o => o.OrderItems)
            .AsNoTracking()                          // No change tracking
            .AsSplitQuery()                          // Split into multiple SQL queries
            .IgnoreQueryFilters();                   // Ignore global query filters
    }
}

✅ Search with Pattern Matching

Supports SQL LIKE patterns (%, _, [A-Z], [^...]):

public class CustomerSearchSpec : Specification<Customer>
{
    public CustomerSearchSpec(string pattern)
    {
        Query.Search(c => c.Name, pattern);
        // Translates to EF.Functions.Like in EF Core
        // Uses custom Like extension for in-memory collections
    }
}

✅ Post-Processing Actions

Execute logic after materialization:

public class CustomersWithComputedDataSpec : Specification<Customer>
{
    public CustomersWithComputedDataSpec()
    {
        Query
            .Where(c => c.IsActive)
            .PostProcessingAction(customers => 
            {
                foreach (var customer in customers)
                {
                    customer.FullName = $"{customer.FirstName} {customer.LastName}";
                }
            });
    }
}

✅ Caching Support

Enable caching for frequently used specifications:

public class CachedCustomersSpec : Specification<Customer>
{
    public CachedCustomersSpec()
    {
        Query
            .Where(c => c.IsActive)
            .EnableCache("ActiveCustomers", nameof(Customer));
    }
}

📚 Core Concepts

ISpecification<T>

The main interface that represents a specification for type T. Contains all query rules, options, and metadata.

Specification<T>

Base class for creating specifications. Use the Query property to build your specification using the fluent API.

SingleResultSpecification<T>

Specialized base class optimized for queries that return a single result (e.g., by ID or unique key).

Specification<T, TResult>

Base class for specifications with projections, transforming T to TResult.

SpecificationBuilder

Fluent API for composing query rules:

• Where: Filter criteria
• Include/ThenInclude: Eager loading
• OrderBy/ThenBy/OrderByDescending/ThenByDescending: Sorting
• Skip/Take: Pagination
• Search: Pattern-based search
• Select/SelectMany: Projection
• PostProcessingAction: Post-materialization logic

🗄️ Repository Integration

Using the Provided Repository Base Classes

// Entity Framework Core repository
public class CustomerRepository : RepositoryBase<Customer>
{
    public CustomerRepository(AppDbContext context) : base(context)
    {
    }
}

// Usage
public class CustomerService
{
    private readonly CustomerRepository _repository;

    public CustomerService(CustomerRepository repository)
    {
        _repository = repository;
    }

    public async Task<List<Customer>> GetActiveCustomersAsync(CancellationToken ct)
    {
        return await _repository.ListAsync(new ActiveCustomersSpec(), ct);
    }

    public async Task<Customer?> GetCustomerByIdAsync(int id, CancellationToken ct)
    {
        return await _repository.FirstOrDefaultAsync(new CustomerByIdSpec(id), ct);
    }

    public async Task<int> CountActiveCustomersAsync(CancellationToken ct)
    {
        return await _repository.CountAsync(new ActiveCustomersSpec(), ct);
    }
}

Using IDbContextFactory (for long-lived services)

public class CustomerRepository : ContextFactoryRepositoryBase<Customer, AppDbContext>
{
    public CustomerRepository(IDbContextFactory<AppDbContext> factory) 
        : base(factory)
    {
    }
}

🔧 Advanced Scenarios

Combining Multiple Specifications

public class ActivePremiumCustomersSpec : Specification<Customer>
{
    public ActivePremiumCustomersSpec()
    {
        Query
            .Where(c => c.IsActive)
            .Where(c => c.IsPremium)
            .Where(c => c.TotalPurchases > 10000);
    }
}

Dynamic Specifications

public class CustomerFilterSpec : Specification<Customer>
{
    public CustomerFilterSpec(CustomerFilter filter)
    {
        if (filter.IsActive.HasValue)
            Query.Where(c => c.IsActive == filter.IsActive.Value);

        if (!string.IsNullOrEmpty(filter.SearchTerm))
            Query.Search(c => c.Name, $"%{filter.SearchTerm}%");

        if (filter.MinPurchases.HasValue)
            Query.Where(c => c.TotalPurchases >= filter.MinPurchases.Value);

        Query
            .OrderBy(c => c.Name)
            .Skip((filter.Page - 1) * filter.PageSize)
            .Take(filter.PageSize);
    }
}

Complex Includes

public class OrderWithDetailsSpec : Specification<Order>
{
    public OrderWithDetailsSpec(int orderId)
    {
        Query
            .Where(o => o.Id == orderId)
            .Include(o => o.Customer)
                .ThenInclude(c => c.Address)
            .Include(o => o.OrderItems)
                .ThenInclude(oi => oi.Product)
                    .ThenInclude(p => p.Category)
            .AsNoTracking();
    }
}

Using Custom Evaluators

// Create a custom in-memory evaluator
var customEvaluator = new InMemorySpecificationEvaluator(
    whereEvaluator: new WhereEvaluator(),
    orderEvaluator: new OrderEvaluator(),
    paginationEvaluator: new PaginationEvaluator()
);

// Use in specification
public class CustomSpec : Specification<Customer>
{
    public CustomSpec() : base(customEvaluator)
    {
        Query.Where(c => c.IsActive);
    }
}

⚡ Performance Tips

1. Use Cached Include Evaluator (EF Core)

For specifications with complex include chains:

// Configure in your DI container
services.AddSingleton<ISpecificationEvaluator>(
    SpecificationEvaluator.Cached
);

2. Disable Tracking When Appropriate

Query.AsNoTracking(); // For read-only queries

3. Use Split Queries for Large Includes

Query
    .Include(o => o.Customer)
    .Include(o => o.OrderItems)
    .AsSplitQuery(); // Generates multiple SQL queries

4. Optimize Count/Any Operations

Repositories automatically optimize these operations by excluding includes and projections.

🧪 Testing

Unit Testing with In-Memory Evaluation

[Fact]
public void ActiveCustomersSpec_ShouldFilterActiveCustomers()
{
    // Arrange
    var customers = new List<Customer>
    {
        new() { Id = 1, Name = "Alice", IsActive = true },
        new() { Id = 2, Name = "Bob", IsActive = false },
        new() { Id = 3, Name = "Charlie", IsActive = true }
    };

    var spec = new ActiveCustomersSpec();

    // Act
    var result = spec.Evaluate(customers).ToList();

    // Assert
    Assert.Equal(2, result.Count);
    Assert.All(result, c => Assert.True(c.IsActive));
}

Integration Testing with EF Core

[Fact]
public async Task CustomerRepository_WithActiveSpec_ReturnsActiveCustomers()
{
    // Arrange
    using var context = CreateInMemoryDbContext();
    await SeedTestDataAsync(context);
    var repository = new CustomerRepository(context);

    // Act
    var result = await repository.ListAsync(
        new ActiveCustomersSpec(), 
        CancellationToken.None
    );

    // Assert
    Assert.All(result, c => Assert.True(c.IsActive));
}

🚨 Common Pitfalls & Best Practices

❌ Avoid: Multiple OrderBy Calls

// DON'T: This will throw DuplicateOrderChainException
Query
    .OrderBy(c => c.Name)
    .OrderBy(c => c.Email); // ❌ Wrong!

// DO: Use ThenBy for secondary ordering
Query
    .OrderBy(c => c.Name)
    .ThenBy(c => c.Email); // ✅ Correct!

❌ Avoid: Multiple Skip or Take Calls

// DON'T: This will throw exceptions
Query.Skip(10).Skip(20);  // ❌ DuplicateSkipException
Query.Take(10).Take(20);  // ❌ DuplicateTakeException

❌ Avoid: Using Includes for Count/Any

// DON'T: Includes are ignored in count operations anyway
public class CustomerCountSpec : Specification<Customer>
{
    public CustomerCountSpec()
    {
        Query
            .Where(c => c.IsActive)
            .Include(c => c.Orders); // ❌ Unnecessary for counting
    }
}

// DO: Keep count specs simple
public class ActiveCustomerCountSpec : Specification<Customer>
{
    public ActiveCustomerCountSpec()
    {
        Query.Where(c => c.IsActive); // ✅ Clean and efficient
    }
}

✅ Do: Use AsNoTracking for Read-Only Queries

public class ReadOnlyCustomersSpec : Specification<Customer>
{
    public ReadOnlyCustomersSpec()
    {
        Query
            .Where(c => c.IsActive)
            .AsNoTracking(); // ✅ Better performance
    }
}

✅ Do: Keep Specifications Focused

// ✅ Good: Single responsibility
public class ActiveCustomersSpec : Specification<Customer>
{
    public ActiveCustomersSpec()
    {
        Query.Where(c => c.IsActive);
    }
}

// ✅ Good: Compose when needed
public class ActivePremiumCustomersSpec : Specification<Customer>
{
    public ActivePremiumCustomersSpec()
    {
        Query
            .Where(c => c.IsActive)
            .Where(c => c.IsPremium);
    }
}

📖 API Reference

Query Builder Methods

Repository Methods

📄 License

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

🙏 Acknowledgments

This library provides a pragmatic, production-ready implementation of the Specification pattern for .NET, emphasizing:

• Reusability: Define query logic once, use everywhere
• Testability: Easy to test with in-memory evaluation
• Maintainability: Clear separation of query concerns
• Performance: Optimized for EF Core with caching options
• Type Safety: Strongly-typed fluent API