Intermediate lesson 148 asked whether you should build a repository at all, and deliberately refused to answer for you. This lesson assumes the answer was yes, and teaches you how to build one you won't regret.

Back in Intermediate lesson 148, you weighed the real case for and against wrapping EF Core's DbContext in a repository interface — a genuinely contested, per-project decision with no universal right answer. That lesson deliberately stayed neutral. This one doesn't need to: assume your team has already made the call, for real reasons — a genuine architectural boundary, a planned technology swap, or a team convention worth respecting — and a repository abstraction is going into the codebase. The question now isn't "should we?" It's "how do we build one that earns its keep instead of becoming exactly the leaky, awkward layer 148 warned about?"

In this lesson, you'll learn the two real shapes a repository can take — generic and specific — the honest trade-off between them, precisely what belongs inside a repository and what doesn't, and how repositories set up the very next lesson's topic: coordinating several of them atomically with Unit of Work.

What Is It?

The Simple Explanation

A repository is a class (behind an interface) that gives the rest of your application a clean, domain-shaped way to fetch and persist a particular kind of object — Order, Product, Customer — without that calling code needing to know or care how the data is actually stored or retrieved. Lesson 148 already established that EF Core's own DbSet<T> functions as a repository per entity type; this lesson is about building a second, purpose-shaped layer on top of it well, once you've decided you genuinely need one.

The Technical Definition

There are two recognized shapes a repository implementation can take, and choosing between them is the first real design decision this lesson covers:

Why Does It Exist? — The Trade-Off, Stated Honestly

Once you've decided (per lesson 148's reasoning) that a repository is warranted, the very next question is which shape to build — and that decision has real, lasting consequences, which is exactly why it deserves a lesson of its own rather than a single paragraph.

Neither shape is a mistake in isolation — the mistake, covered later under Common Mistakes, is picking one shape and forcing every entity in the domain through it regardless of fit.

Big Picture — What Belongs Inside, What Doesn't

Before any code, the most important structural rule: a repository is a persistence and querying concern. It is not, and must never become, a place for business rules.

The reasoning is the same dependency-inversion discipline from lesson 081, applied specifically to data access: a repository's job is how data gets fetched and saved. What should happen, and whether it should happen, are questions for your domain and application layers, not your data-access classes. A repository method named GetActiveVipCustomersAsync is fine — it's a query shape. A repository method that decides who counts as VIP by encoding business logic inside the query, invisible to anyone reading the domain layer, has smuggled a business rule into the data-access layer where nobody will think to look for it.

How It Works — Building Both Shapes

public interface IRepository<T> where T : class
{
    Task<T?> GetByIdAsync(int id);
    Task<List<T>> GetAllAsync();
    Task AddAsync(T entity);
    void Update(T entity);
    void Delete(T entity);
}

public class EfRepository<T>(ShopDbContext context) : IRepository<T> where T : class
{
    public async Task<T?> GetByIdAsync(int id) => await context.Set<T>().FindAsync(id);
    public async Task<List<T>> GetAllAsync() => await context.Set<T>().ToListAsync();
    public async Task AddAsync(T entity) => await context.Set<T>().AddAsync(entity);
    public void Update(T entity) => context.Set<T>().Update(entity);
    public void Delete(T entity) => context.Set<T>().Remove(entity);
}

services.AddScoped(typeof(IRepository<>), typeof(EfRepository<>));
// Now IRepository<Category>, IRepository<Tag>, etc. all resolve automatically.

public interface IOrderRepository
{
    Task<Order?> GetWithLinesAsync(int orderId);
    Task<List<Order>> GetOverdueOrdersAsync(DateTime asOf);
    Task AddAsync(Order order);
}

public class EfOrderRepository(ShopDbContext context) : IOrderRepository
{
    public async Task<Order?> GetWithLinesAsync(int orderId) =>
        await context.Orders.Include(o => o.Lines)
            .FirstOrDefaultAsync(o => o.Id == orderId);

    public async Task<List<Order>> GetOverdueOrdersAsync(DateTime asOf) =>
        await context.Orders.AsNoTracking()
            .Where(o => o.Status == OrderStatus.Pending && o.DueDate < asOf)
            .ToListAsync();

    public async Task AddAsync(Order order) => await context.Orders.AddAsync(order);
}

Simple Example — the Same Entity, Both Ways

A small, simple Category entity — just a name and a description, no interesting queries — versus Order, which genuinely has domain-specific needs:

Code → Meaning → Result: CategoryService loses nothing by using the generic repository — Category has no special query needs today. Forcing Order through the same generic interface, on the other hand, would mean either bolting GetWithLinesAsync and GetOverdueOrdersAsync onto a supposedly "generic" interface (which stops it being generic) or exposing IQueryable<Order> and pushing EF Core-specific LINQ back out to the caller (exactly the leak lesson 148 flagged as Mistake 2). Picking the shape per entity, rather than committing the whole codebase to one, is the actual skill this lesson is teaching.

Real-World Example — Order Fulfillment, With the Business Logic Kept Out

An e-commerce platform's order-cancellation workflow, showing the boundary between the repository and the application service that uses it — deliberately, since this is the exact line the "what belongs where" section drew:

Notice EfOrderRepository never once asks "is this order allowed to be cancelled?" — it only knows how to fetch and save an Order. The rule that a shipped order can't be cancelled lives in CancelOrderService, where anyone reading the business logic will actually find it, and where it can be unit tested with a fake IOrderRepository and zero database involved.

Analogy

Under the Hood — Where the Generic Shape Genuinely Strains

Common Confusion

1. "Generic vs specific" is not "wrong vs right" — it's per-entity, not per-codebase

It's entirely normal, and often the best design, for one codebase to use a generic IRepository<T> for simple lookup entities (Category, Tag) and specific repositories for entities with real query complexity (Order, Customer). Choosing this per entity, based on its actual needs, isn't inconsistency — it's the same "match the tool to the actual requirement" judgment lesson 148 modeled for the repository-or-not decision itself.

2. "Repository" does not mean "no business logic ever touches this data" — it means the repository itself doesn't decide the business logic

A repository method can absolutely be named around a business-meaningful concept (GetOverdueOrdersAsync) — that's just a query shaped around what the domain cares about. The line is: the repository fetches the facts ("orders where DueDate < asOf"); it does not decide what "overdue" means in terms of business consequence, or what should happen to an overdue order. That decision belongs to whoever calls the repository.

Common Mistakes

Mistake 1 — Forcing every entity in the domain through one generic IRepository<T>, regardless of fit

Building only IRepository<T>, and when Order needs a query the generic interface can't express, bolting an order-specific method onto the "generic" interface — or worse, exposing IQueryable<T> so every caller can compose whatever LINQ it wants, quietly abandoning the abstraction.

Introduce a specific IOrderRepository for entities whose query needs have genuinely outgrown generic CRUD, and keep the generic repository for the entities that are still well served by it. Mixed shapes in one codebase are normal.

Mistake 2 — Putting a validation rule or a business decision inside a repository method

public async Task AddAsync(Order order) { if (order.Lines.Count == 0) throw new InvalidOperationException("Order must have at least one line."); ... } — a business rule, hidden inside a data-access class where nobody reading the domain layer will ever find it.

Validate in the domain entity itself, or in the application service that orchestrates the operation — before the repository is ever called. The repository's job starts once the object is already known to be valid.

Mistake 3 — Building a specific repository per entity before any real query need has appeared

Writing a full ICategoryRepository with five carefully-named methods for an entity that has, and will likely ever have, exactly two operations: get by id, add. This is the specific-repository version of over-engineering — real work spent anticipating needs that never arrive.

Start simple entities on the generic repository; promote a specific one into existence only once a genuine, real query need shows up that the generic shape can't express well.

When Should I Use It?

And the honest overkill case: for a small application with few entities and no real architectural mandate, building even a well-designed specific-repository layer for every entity is more ceremony than the project needs — lesson 148's guidance about injecting DbContext directly still applies just as much here as it did there. This lesson is about building repositories well, once you've decided to build them — not a reason to build more of them than your project actually needs.

Mental Model

Key Takeaway

Check Your Understanding

You've weighed generic versus specific repositories, and drawn the line between what belongs in a repository and what doesn't. Let's confirm the reasoning transfers to new scenarios.

You now know how to build a repository layer that earns its cost — the right shape per entity, and a clean line between persistence and business logic. Next: Unit of Work, the pattern that coordinates multiple repositories into one atomic operation.

dotnetmadeeasy.com — Learn C# and .NET, the right way.