As your .NET projects grow, handling data gets more and more complicated. Many teams start with the Repository Pattern, wrapping their EF Core queries inside.

At first, this works fine. But as your project grows, your Repositories either don't do enough or try to do too much. Your code becomes harder to understand and modify as business requirements change.

Each time you need a new filter or query, you add another method or even a new repository.

How can you solve this issue? The answer is a Specification pattern.

In this post, you will learn how the Specification Pattern works in real .NET projects, why it is better than writing lots of repositories for reading data.

In this post, we will explore:

• Why Repositories Become a Bottleneck in Real Projects
• What Is the Specification Pattern?
• How to Implement Specifications in EF Core
• Advanced Specifications

Let's dive in!

When your application is small, using the Repository Pattern seems easy.

You put all your data queries in one place, such as a PostRepository or UserRepository. Each method is designed to answer a specific question, such as "Get all recent posts" or "Find user by email".

But as your project grows, you will notice a few big problems:

1. Repositories Become Too Large

Every new business requirement means adding another method to the Repository. Over time, you end up with classes full of similar methods:

csharp
1public class PostRepository
2{
3    public Task<List<Post>> GetPostsByUser(int userId) { ... }
4    public Task<List<Post>> GetPopularPosts() { ... }
5    public Task<List<Post>> GetPostsByCategory(string category) { ... }
6    public Task<List<Post>> GetRecentViralPosts(int daysBack) { ... }
7    // ...and many more!
8}

It gets harder to find the correct method or even remember what's already in every repository.

2. Method Naming and Duplication

You start writing awkward and long method names to describe every filter. For example, GetPostsByCategoryAndLikesCountAndDate.

And what if you need the same method but with sorting by date in descending order? This results in a lot of code duplication.

3. Too Many Repositories

Trying to keep repositories small sometimes means splitting them into many tiny classes. But then you lose the benefit of having everything in one place.

Now, it's harder to find the necessary repository and reuse logic between repositories.

Remember that EF Core's DbContext already implements the Repository and Unit of Work patterns, as stated in the official DbContext's code summary. When we create a repository over EF Core, we create an abstraction over an abstraction, leading to over-engineered solutions.

Let's explore what a Specification pattern is and how it solves our problem.

The Specification Pattern is a way to describe what data you want from your database using small, reusable classes called "specifications".

Each Specification represents a filter or a rule that can be applied to a query. This lets you build complex queries by combining simple, easy-to-understand classes.

The Specification Pattern brings the following benefits to the table:

• Reusability: You can write a specification once and use it anywhere in your project.
• Combination: You can combine two or more specifications to make more advanced queries.
• Testability: Specifications are classes over EF Core (or any other ORM), so you can cover them with unit tests, or even better - integration tests.
• Separation of Concerns: Your query logic is separated from your data access code. This keeps things clean.

Instead of writing dozens of methods in your Repository, you can just create new specifications as your requirements grow. You can then pass these specifications to your DbContext (or even a repository, if you still want to use one).

Here is an example of a Specification that returns viral posts in a social media application with at least 150 likes:

csharp
1public class ViralPostSpecification : Specification<Post>
2{
3    public ViralPostSpecification(int minLikesCount = 150)
4    {
5        AddFilteringQuery(post => post.Likes.Count >= minLikesCount);
6        AddOrderByDescendingQuery(post => post.Likes.Count);
7    }
8}

You can reuse this Specification anywhere in your code to get "viral" posts.

Let's explore how to implement Specifications.

To implement specifications in EF Core, you need to follow these steps:

Step 1: Define a Specification Interface

You need a common way to describe filters, includes, and sorting for any entity. Here's a simple interface:

csharp
1public interface ISpecification<TEntity>
2    where TEntity : class
3{
4    Expression<Func<TEntity, bool>>? FilterQuery { get; }
5    IReadOnlyCollection<Expression<Func<TEntity, object>>>? IncludeQueries { get; }
6    IReadOnlyCollection<Expression<Func<TEntity, object>>>? OrderByQueries { get; }
7    IReadOnlyCollection<Expression<Func<TEntity, object>>>? OrderByDescendingQueries { get; }
8}

Step 2: Create a Base Specification Class

This base class holds the logic for building up specifications. You add filters, includes, and sort expressions in one place:

csharp
1using System.Linq.Expressions;
2
3public abstract class Specification<TEntity> : ISpecification<TEntity>
4    where TEntity : class
5{
6    private List<Expression<Func<TEntity, object>>>? _includeQueries;
7    private List<Expression<Func<TEntity, object>>>? _orderByQueries;
8    private List<Expression<Func<TEntity, object>>>? _orderByDescendingQueries;
9
10    public Expression<Func<TEntity, bool>>? FilterQuery { get; private set; }
11    public IReadOnlyCollection<Expression<Func<TEntity, object>>>? IncludeQueries => _includeQueries;
12    public IReadOnlyCollection<Expression<Func<TEntity, object>>>? OrderByQueries => _orderByQueries;
13    public IReadOnlyCollection<Expression<Func<TEntity, object>>>? OrderByDescendingQueries => _orderByDescendingQueries;
14
15    protected Specification() {}
16
17    protected Specification(Expression<Func<TEntity, bool>> query)
18    {
19        FilterQuery = query;
20    }
21
22    protected Specification(ISpecification<TEntity> specification)
23    {
24        FilterQuery = specification.FilterQuery;
25
26        _includeQueries = specification.IncludeQueries?.ToList();
27        _orderByQueries = specification.OrderByQueries?.ToList();
28        _orderByDescendingQueries = specification.OrderByDescendingQueries?.ToList();
29    }
30
31    protected void AddFilteringQuery(Expression<Func<TEntity, bool>> query)
32    {
33        FilterQuery = query;
34    }
35
36    protected void AddIncludeQuery(Expression<Func<TEntity, object>> query)
37    {
38        _includeQueries ??= new();
39        _includeQueries.Add(query);
40    }
41
42    protected void AddOrderByQuery(Expression<Func<TEntity, object>> query)
43    {
44        _orderByQueries ??= new();
45        _orderByQueries.Add(query);
46    }
47
48    protected void AddOrderByDescendingQuery(Expression<Func<TEntity, object>> query)
49    {
50        _orderByDescendingQueries ??= new();
51        _orderByDescendingQueries.Add(query);
52    }
53}

Here is a description of each option:

• FilterQuery: A filtering function to test each entity for a condition
• IncludeQueries: A collection of functions that describe included entities
• OrderByQueries, OrderByDescendingQueries: A function that describes how to order entities by ascending/descending order

Step 3: Applying a Specification in EF Core

Now let's connect our Specification class to EF Core:

csharp
1public class EfCoreSpecification<TEntity> : Specification<TEntity>
2    where TEntity : class
3{
4    public EfCoreSpecification(ISpecification<TEntity> specification)
5        : base(specification) { }
6    
7    public virtual IQueryable<TEntity> Apply(IQueryable<TEntity> queryable)
8    {
9        if (FilterQuery is not null)
10        {
11            queryable = queryable.Where(FilterQuery);
12        }
13
14        if (IncludeQueries?.Count > 0)
15        {
16            queryable = IncludeQueries.Aggregate(queryable,
17                (current, includeQuery) => current.Include(includeQuery));
18        }
19
20        if (OrderByQueries?.Count > 0)
21        {
22            var orderedQueryable = queryable.OrderBy(OrderByQueries.First());
23            
24            orderedQueryable = OrderByQueries.Skip(1)
25                .Aggregate(orderedQueryable, (current, orderQuery) => current.ThenBy(orderQuery));
26            
27            queryable = orderedQueryable;
28        }
29        
30        if (OrderByDescendingQueries?.Count > 0)
31        {
32            var orderedQueryable = queryable.OrderByDescending(OrderByDescendingQueries.First());
33            
34            orderedQueryable = OrderByDescendingQueries.Skip(1)
35                .Aggregate(orderedQueryable, (current, orderQuery) => current.ThenByDescending(orderQuery));
36            
37            queryable = orderedQueryable;
38        }
39
40        return queryable;
41    }
42}

The Apply method takes a database query and adds different types of filters and sorting to it step by step.

First, it checks if there's a filter condition (like "show only posts with more than 10 likes") and applies it using the Where method.

Next, it looks for any related data that needs to be loaded together (called "includes") and adds those using the Include method (EF Core Eager Loading).

Then it handles sorting - it applies the first one with OrderBy and any additional ones with ThenBy.

Finally, the method returns the modified query with all these conditions applied, ready to be sent to the database.

Step 4: Use Specifications Directly in Your Endpoints

With this pattern, you put your query logic into small, reusable classes called specifications. You can use these directly with DbContext in EF Core. That means you don't need the Repository Pattern at all.

Now you can write simple, clean endpoints:

csharp
1public class GetViralPostsEndpoint : IEndpoint
2{
3    public void MapEndpoint(WebApplication app)
4    {
5        app.MapGet("/api/social-media/viral-posts", Handle);
6    }
7
8    private static async Task<IResult> Handle(
9        [FromQuery] int? minLikesCount,
10        [FromServices] ApplicationDbContext dbContext,
11        [FromServices] ILogger<GetViralPostsEndpoint> logger,
12        CancellationToken cancellationToken)
13    {
14        var specification = new ViralPostSpecification(minLikesCount ?? 150);
15
16        var response = await dbContext
17            .ApplySpecification(specification)
18            .Select(post => post.ToDto())
19            .ToListAsync(cancellationToken);
20
21        logger.LogInformation("Retrieved {Count} viral posts with minimum {MinLikes} likes",
22            response.Count, minLikesCount ?? 150);
23
24        return Results.Ok(response);
25    }
26}

I apply the Specification on DbContext with a small extension method:

csharp
1public static class SpecificationExtensions
2{
3    public static IQueryable<TEntity> ApplySpecification<TEntity>(
4        this ApplicationDbContext dbContext,
5        ISpecification<TEntity> specification) where TEntity : class
6    {
7        var efCoreSpecification = new EfCoreSpecification<TEntity>(specification);
8
9        var query = dbContext.Set<TEntity>().AsNoTracking();
10        query = efCoreSpecification.Apply(query);
11
12        return query;
13    }
14}

If you still want to use a Repository pattern, you can materialize the specification query and return the result from your Repository:

csharp
1public abstract class BaseRepository<TEntity> where TEntity : class
2{
3    private readonly ApplicationDbContext _dbContext;
4
5    public Repository(ApplicationDbContext dbContext)
6    {
7        _dbContext = dbContext;
8    }
9
10    public async Task<List<TEntity>> WhereAsync(
11        ISpecification<TEntity> specification,
12        CancellationToken cancellationToken = default)
13    {
14        var efCoreSpecification = new EfCoreSpecification<TEntity>(specification);
15
16        var query = _dbContext.Set<TEntity>().AsNoTracking();
17        query = efCoreSpecification.Apply(query);
18
19        return await query.ToListAsync(cancellationToken).ConfigureAwait(false);
20    }
21}

One of the best things about the Specification Pattern is how easily you can build advanced queries by combining small, focused specifications.

You can join two or more specifications together using logical operators like AND and OR.

Here is how to create AndSpecification and OrSpecification:

csharp
1public class AndSpecification<TEntity> : Specification<TEntity>
2    where TEntity : class
3{
4    public AndSpecification(Specification<TEntity> left, Specification<TEntity> right)
5    {
6        RegisterFilteringQuery(left, right);
7    }
8
9    private void RegisterFilteringQuery(Specification<TEntity> left, Specification<TEntity> right)
10    {
11        var leftExpression = left.FilterQuery;
12        var rightExpression = right.FilterQuery;
13
14        if (leftExpression is null && rightExpression is null)
15        {
16            return;
17        }
18        
19        if (leftExpression is not null && rightExpression is null)
20        {
21            AddFilteringQuery(leftExpression);
22            return;
23        }
24        
25        if (leftExpression is null && rightExpression is not null)
26        {
27            AddFilteringQuery(rightExpression);
28            return;
29        }
30        
31        var replaceVisitor = new ReplaceExpressionVisitor(rightExpression!.Parameters.Single(), leftExpression!.Parameters.Single());
32        var replacedBody = replaceVisitor.Visit(rightExpression.Body);
33
34        var andExpression = Expression.AndAlso(leftExpression.Body, replacedBody);
35        var lambda = Expression.Lambda<Func<TEntity, bool>>(andExpression, leftExpression.Parameters.Single());
36
37        AddFilteringQuery(lambda);
38    }
39}

csharp
1public class OrSpecification<TEntity> : Specification<TEntity>
2    where TEntity : class
3{
4    public OrSpecification(Specification<TEntity> left, Specification<TEntity> right)
5    {
6        RegisterFilteringQuery(left, right);
7    }
8
9    private void RegisterFilteringQuery(Specification<TEntity> left, Specification<TEntity> right)
10    {
11        var leftExpression = left.FilterQuery;
12        var rightExpression = right.FilterQuery;
13
14        if (leftExpression is null && rightExpression is null)
15        {
16            return;
17        }
18        
19        if (leftExpression is not null && rightExpression is null)
20        {
21            AddFilteringQuery(leftExpression);
22            return;
23        }
24        
25        if (leftExpression is null && rightExpression is not null)
26        {
27            AddFilteringQuery(rightExpression);
28            return;
29        }
30        
31        var replaceVisitor = new ReplaceExpressionVisitor(
32            rightExpression!.Parameters.Single(),
33            leftExpression!.Parameters.Single()
34        );
35        
36        var replacedBody = replaceVisitor.Visit(rightExpression.Body);
37
38        var andExpression = Expression.OrElse(leftExpression.Body, replacedBody);
39        
40        var lambda = Expression.Lambda<Func<TEntity, bool>>(
41            andExpression, leftExpression.Parameters.Single());
42
43        AddFilteringQuery(lambda);
44    }
45}

To combine two queries, we need to use Expression.AndAlso or Expression.OrElse with an expression Visitor:

csharp
1internal class ReplaceExpressionVisitor : ExpressionVisitor
2{
3    private readonly Expression _oldValue;
4    private readonly Expression _newValue;
5
6    /// <summary>
7    /// Initializes a new instance of the class
8    /// </summary>
9    /// <param name="oldValue">Old expression to be replaced</param>
10    /// <param name="newValue">A new expression that replaces the old one</param>
11    public ReplaceExpressionVisitor(Expression oldValue, Expression newValue)
12    {
13        _oldValue = oldValue;
14        _newValue = newValue;
15    }
16
17    public override Expression Visit(Expression? node)
18        => (node == _oldValue ? _newValue : base.Visit(node))!;
19}

To simplify these Specifications' usage, let's create 2 helper methods in the Specification class:

csharp
1public Specification<TEntity> And(Specification<TEntity> specification)
2    => new AndSpecification<TEntity>(this, specification);
3
4public Specification<TEntity> Or(Specification<TEntity> specification)
5    => new OrSpecification<TEntity>(this, specification);

Now let's explore a practical example.

Let's say you have a Specification that searches for posts in a given category:

csharp
1public class PostByCategorySpecification : Specification<Post>
2{
3    public PostByCategorySpecification(string categoryName)
4    {
5        AddFilteringQuery(post => post.Category.Name == categoryName);
6    }
7}

You can combine specifications to select posts that belong to ".NET" or "Architecture" categories:

csharp
1public class DotNetAndArchitecturePostSpecification : Specification<Post>
2{
3    public DotNetAndArchitecturePostSpecification()
4    {
5        var dotNetSpec = new PostByCategorySpecification(".NET");
6        var architectureSpec = new PostByCategorySpecification("Architecture");
7
8        // Combine 2 specifications with OrSpecification
9        var combinedSpec = dotNetSpec.Or(architectureSpec);
10
11        AddFilteringQuery(combinedSpec.FilterQuery!);
12
13        AddOrderByDescendingQuery(post => post.Id);
14    }
15}

Another example, where we select posts that are both recent and have high engagement:

csharp
1public class HighEngagementRecentPostSpecification : Specification<Post>
2{
3    public HighEngagementRecentPostSpecification(int daysBack = 7,
4        int minLikes = 100, int minComments = 30)
5    {
6        var recentSpec = new RecentPostSpecification(daysBack);
7        var highEngagementSpec = new HighEngagementPostSpecification(minLikes, minComments);
8
9        // Combine 2 specifications with AndSpecification
10        var combinedSpec = recentSpec.And(highEngagementSpec);
11
12        AddFilteringQuery(combinedSpec.FilterQuery!);
13
14        AddOrderByDescendingQuery(post => post.Likes.Count + post.Comments.Count);
15    }
16}

This provides us with the flexibility and reusability of existing Specifications to form new specifications.

Note: Adding Include queries like AddIncludeQuery(post => post.Category); is not necessary here, as we do not materialize our database query in the Specification itself, as we use Select Projection:

If you use repositories and want one universal method that applies specifications, you have 2 options:

• Add Include queries, but it will result in returning too much data from the database in the WhereAsync method
• Push a delegate with a mapping function to the WhereAsync method in the Repository

Both of these approaches come with trade-offs; that's why I prefer to work with EF Core without a Repository pattern.

So our API endpoints (or Application handlers or services, depending on the project complexity) will be as simple as this:

csharp
1public class GetDotNetAndArchitecturePostsEndpoint : IEndpoint
2{
3    public void MapEndpoint(WebApplication app)
4    {
5        app.MapGet("/api/social-media/dotnet-architecture-posts", Handle);
6    }
7
8    private static async Task<IResult> Handle(
9        ApplicationDbContext dbContext,
10        CancellationToken cancellationToken)
11    {
12        var specification = new DotNetAndArchitecturePostSpecification();
13
14        var response = await dbContext
15            .ApplySpecification(specification)
16            .Select(post => post.ToDto())
17            .ToListAsync(cancellationToken);
18
19        return Results.Ok(response);
20    }
21}

P.S.: You can find more real-world Specifications for social media in the source code at the end of the post

The Specification Pattern is a powerful tool for building flexible and reusable database queries in your .NET projects. By defining your filters, includes, and sorting rules as specification classes, you avoid the problems that come with large, hard-to-maintain repositories.

With EF Core, you don't need the Repository Pattern — you can apply your specifications directly to the DbContext.

This approach:

• Keeps your codebase clean and easy to change
• Makes your queries reusable across many parts of your application
• Lets you combine and compose specifications for advanced scenarios
• Helps you test your query logic separately from the database

Whenever you find yourself adding more and more methods to a repository or writing duplicate query logic, consider using the Specification Pattern instead. It will help your project grow in a healthy, maintainable way.

Hope you find this newsletter useful. See you next time.