TwoRivers.Specifications.EntityFrameworkCore 2.0.0-beta.1

TwoRivers.Specifications.EntityFrameworkCore

The TwoRivers.Specifications.EntityFrameworkCore package provides Entity Framework Core integration for the Specification Pattern, allowing you to encapsulate query logic and apply it to DbContext queries efficiently.

Installation

You can install the TwoRivers.Specifications.EntityFrameworkCore package via NuGet Package Manager:

Install-Package TwoRivers.Specifications.EntityFrameworkCore

Or via the .NET CLI:

dotnet add package TwoRivers.Specifications.EntityFrameworkCore

Overview

This package bridges the TwoRivers.Specifications pattern with Entity Framework Core, providing:

• SpecificationRepository<TEntity, TDbContext> - Generic repository with specification support
• SpecificationEvaluator<TEntity> - Converts specifications to EF Core queryable expressions
• ISpecificationRepository<TEntity> - Repository abstraction for specification queries

Features

SpecificationRepository

A generic repository implementation that applies specifications to Entity Framework Core queries:

• Supports all CRUD operations
• Applies specifications to IQueryable
• Handles async operations with cancellation tokens
• Implements proper dispose pattern

SpecificationEvaluator

Evaluates specifications and applies them to EF Core queryables:

• Converts IQuery<T> specifications to IQueryable<T>
• Handles Where, OrderBy, Skip, Take operations
• Optimizes query execution with EF Core

Usage

Basic Repository Usage

using Microsoft.EntityFrameworkCore;
using TwoRivers.Specifications;

public class ApplicationDbContext : DbContext
{
    public DbSet<Customer> Customers { get; set; }

    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options)
    {
    }
}

// Using the repository
public class CustomerService
{
    private readonly SpecificationRepository<Customer, ApplicationDbContext> _repository;

    public CustomerService(ApplicationDbContext context)
    {
        _repository = new SpecificationRepository<Customer, ApplicationDbContext>(context);
    }

    public async Task<IEnumerable<Customer>> GetActiveCustomersAsync()
    {
        var spec = new ActiveCustomersSpecification();
        return await _repository.FindAsync(spec).ToListAsync();
    }

    public async Task<Customer?> GetCustomerByIdAsync(Guid id)
    {
        var spec = new CustomerByIdSpecification(id);
        return await _repository.GetAsync(spec);
    }

    public async Task<Int32> CountActiveCustomersAsync()
    {
        var spec = new ActiveCustomersSpecification();
        return await _repository.CountAsync(spec);
    }
}

Dependency Injection Registration

using Microsoft.Extensions.DependencyInjection;
using TwoRivers.Specifications;

services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(connectionString));

// Register repository
services.AddScoped<ISpecificationRepository<Customer>, 
    SpecificationRepository<Customer, ApplicationDbContext>>();

// Or use the extension method (if available)
services.AddSpecificationRepository<Customer, ApplicationDbContext>();

Complete Example with Specifications

using TwoRivers.Specifications;

// Define your entity
public class Customer
{
    public Guid Id { get; set; }
    public String Name { get; set; }
    public String Email { get; set; }
    public Boolean IsActive { get; set; }
    public DateTime CreatedAt { get; set; }
}

// Create specifications
public class ActiveCustomersSpecification : BaseQuery<Customer>
{
    public ActiveCustomersSpecification()
    {
        AddCriteria(c => c.IsActive);
        ApplyOrderBy(c => c.Name);
    }
}

public class CustomerByEmailSpecification : BaseQuery<Customer>
{
    public CustomerByEmailSpecification(String email)
    {
        AddCriteria(c => c.Email == email);
    }
}

public class RecentCustomersSpecification : BaseQuery<Customer>
{
    public RecentCustomersSpecification(Int32 days, Int32 pageSize = 10)
    {
        var cutoffDate = DateTime.UtcNow.AddDays(-days);
        AddCriteria(c => c.CreatedAt >= cutoffDate);
        ApplyOrderByDescending(c => c.CreatedAt);
        ApplyPaging(0, pageSize);
    }
}

// Use in a service
public class CustomerQueryService
{
    private readonly ISpecificationRepository<Customer> _repository;

    public CustomerQueryService(ISpecificationRepository<Customer> repository)
    {
        _repository = repository;
    }

    public async Task<IEnumerable<Customer>> GetActiveCustomersAsync()
    {
        var spec = new ActiveCustomersSpecification();
        return await _repository.FindAsync(spec).ToListAsync();
    }

    public async Task<Boolean> IsEmailInUseAsync(String email)
    {
        var spec = new CustomerByEmailSpecification(email);
        return await _repository.AnyAsync(spec);
    }

    public async Task<IEnumerable<Customer>> GetRecentCustomersAsync(Int32 days = 30)
    {
        var spec = new RecentCustomersSpecification(days, pageSize: 20);
        return await _repository.FindAsync(spec).ToListAsync();
    }
}

Direct Specification Evaluation

If you prefer not to use the repository pattern:

public class CustomerService
{
    private readonly ApplicationDbContext _context;

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

    public async Task<List<Customer>> GetActiveCustomersAsync()
    {
        var spec = new ActiveCustomersSpecification();
        var query = SpecificationEvaluator<Customer>.GetQuery(
            _context.Customers.AsQueryable(), 
            spec);

        return await query.ToListAsync();
    }
}

Best Practices

Keep Specifications Focused

Each specification should represent a single query concept:

// Good - single responsibility
public class ActiveCustomersSpecification : BaseQuery<Customer>
{
    public ActiveCustomersSpecification()
    {
        AddCriteria(c => c.IsActive);
    }
}

// Good - composable
var spec = new ActiveCustomersSpecification()
    .And(new CustomersByStateSpecification("CA"))
    .OrderBy(c => c.Name);

Use Strongly-Typed Specifications

Avoid stringly-typed queries:

// Good
var spec = new CustomerByEmailSpecification(customer.Email);

// Avoid
var query = _context.Customers.Where($"Email == '{customer.Email}'");

Leverage Async Methods

Always use async methods for database queries:

// Good
var customers = await _repository.FindAsync(spec).ToListAsync();

// Avoid blocking
var customers = _repository.FindAsync(spec).ToEnumerable().ToList();

License

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