Ardalis.Specification for C# (.NET): Complete Guide with Examples

In modern C# (.NET) development, one of the key tasks is organizing clean, testable, and maintainable code for working with data. The Specification pattern is a powerful tool that allows encapsulating business rules and query logic in the form of reusable, composable, and testable classes. The Ardalis.Specification library is the de facto standard for implementing this pattern in the .NET ecosystem, providing developers with an elegant way to abstract from specific ORMs (Entity Framework Core, Dapper, etc.) and build flexible data queries.

Why is this needed? In a typical application using Entity Framework Core, query logic is often scattered throughout the code: in controllers, services, repositories. This leads to code duplication (for example, the same "active users" filter may be repeated in different places), testing complexity (need to mock DbContext), and fragility (changing one query can break another). Ardalis.Specification solves these problems by offering a unified, strongly typed way to describe what data needs to be retrieved, without being tied to how exactly it will be retrieved.

The library provides a rich API for building queries: from simple filtering (Where) to complex includes of related data (Include, ThenInclude), sorting (OrderBy, ThenBy), pagination (Skip, Take), and projections (Select). It is fully compatible with Entity Framework Core (via the Ardalis.Specification.EntityFrameworkCore package) but can be adapted for other data providers as well. Thanks to this, your code becomes cleaner, query logic becomes reusable, and testing becomes significantly easier.

Installation

NuGet is used to install the library. Depending on your ORM, you need to install the main package and the provider package.

# Main package (contains base classes and interfaces)\ndotnet add package Ardalis.Specification\n\n# Package for Entity Framework Core (contains repository implementation)\ndotnet add package Ardalis.Specification.EntityFrameworkCore\n\n# If you are using only the base package without EF Core (e.g., for tests or custom implementation)\ndotnet add package Ardalis.Specification

Quick Start

Let's look at a minimal working example. Suppose we have a Product entity and we want to get all products whose price is greater than 100.

// 1. Define the entity\npublic class Product\n{\n    public int Id { get; set; }\n    public string Name { get; set; } = string.Empty;\n    public decimal Price { get; set; }\n    public bool IsActive { get; set; }\n}\n\n// 2. Create a specification\npublic class ProductsWithPriceGreaterThanSpec : Specification<Product>\n{\n    public ProductsWithPriceGreaterThanSpec(decimal minPrice)\n    {\n        Query.Where(p => p.Price > minPrice);\n    }\n}\n\n// 3. Use the specification with a repository\npublic class ProductService\n{\n    private readonly IRepositoryBase<Product> _repository;\n\n    public ProductService(IRepositoryBase<Product> repository)\n    {\n        _repository = repository;\n    }\n\n    public async Task<List<Product>> GetExpensiveProductsAsync(decimal minPrice)\n    {\n        var spec = new ProductsWithPriceGreaterThanSpec(minPrice);\n        return await _repository.ListAsync(spec);\n    }\n}

In this example, we created a specification class that encapsulates the filtering logic. The IRepositoryBase repository (from the Ardalis.Specification.EntityFrameworkCore package) automatically applies this specification to your DbContext and returns the result. This is the essence of the pattern: separating the query description from its execution.

Main Methods and Classes

The library