Ardalis.Specification para C# (.NET): guia completo com exemplos

No desenvolvimento moderno com C# (.NET), uma das principais tarefas é organizar um código limpo, testável e de fácil manutenção para trabalhar com dados. O padrão Specification (Especificação) é uma ferramenta poderosa que permite encapsular regras de negócio e lógica de consultas em classes reutilizáveis, combináveis e testáveis. A biblioteca Ardalis.Specification é o padrão de facto para implementar esse padrão no ecossistema .NET, oferecendo aos desenvolvedores uma maneira elegante de abstrair ORMs específicos (Entity Framework Core, Dapper, etc.) e construir consultas de dados flexíveis.

Por que isso é necessário? Em uma aplicação típica que usa Entity Framework Core, a lógica de consultas geralmente fica espalhada por todo o código: em controllers, serviços e repositórios. Isso leva à duplicação de código (por exemplo, o mesmo filtro "usuários ativos" pode se repetir em vários lugares), dificuldade de teste (é necessário mockar o DbContext) e fragilidade (alterar uma consulta pode quebrar outra). O Ardalis.Specification resolve esses problemas oferecendo uma maneira única e fortemente tipada de descrever quais dados devem ser obtidos, sem se prender a como eles serão recuperados.

A biblioteca fornece uma API rica para construir consultas: desde filtros simples (Where) até inclusões complexas de dados relacionados (Include, ThenInclude), ordenações (OrderBy, ThenBy), paginação (Skip, Take) e projeções (Select). Ela é totalmente compatível com Entity Framework Core (através do pacote Ardalis.Specification.EntityFrameworkCore), mas também pode ser adaptada para outros provedores de dados. Com isso, seu código fica mais limpo, a lógica de consultas se torna reutilizável e os testes ficam muito mais simples.

Instalação

Para instalar a biblioteca, use o NuGet. Dependendo do seu ORM, você precisa instalar o pacote principal e o pacote provedor.

# Pacote principal (contém classes e interfaces base)
dotnet add package Ardalis.Specification

# Pacote para Entity Framework Core (contém a implementação do repositório)
dotnet add package Ardalis.Specification.EntityFrameworkCore

# Se você estiver usando apenas o pacote base sem EF Core (ex.: para testes ou implementação personalizada)
dotnet add package Ardalis.Specification

Início rápido

Vamos ver um exemplo mínimo funcional. Suponha que temos uma entidade Product e queremos obter todos os produtos com preço maior que 100.

// 1. Definindo a entidade
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public bool IsActive { get; set; }
}

// 2. Criando a especificação
public class ProductsWithPriceGreaterThanSpec : Specification<Product>
{
    public ProductsWithPriceGreaterThanSpec(decimal minPrice)
    {
        Query.Where(p => p.Price > minPrice);
    }
}

// 3. Usando a especificação com o repositório
public class ProductService
{
    private readonly IRepositoryBase<Product> _repository;

    public ProductService(IRepositoryBase<Product> repository)
    {
        _repository = repository;
    }

    public async Task<List<Product>> GetExpensiveProductsAsync(decimal minPrice)
    {
        var spec = new ProductsWithPriceGreaterThanSpec(minPrice);
        return await _repository.ListAsync(spec);
    }
}

Neste exemplo, criamos uma classe de especificação que encapsula a lógica de filtro. O repositório IRepositoryBase (do pacote Ardalis.Specification.EntityFrameworkCore) aplica automaticamente essa especificação ao seu DbContext e retorna o resultado. Essa é a essência do padrão: separar a descrição da consulta de sua execução.