Clean Architecture in .NET: A Practical Blueprint

I’ve seen too many .NET projects turn into maintenance nightmares because they skipped proper architecture. Here’s the pattern I use to keep business logic clean, testable, and framework-independent.

The Problem

Most .NET tutorials teach you CRUD operations, but they don’t show you how to structure a real application that:

Won’t break when you swap ORMs (Entity Framework → Dapper)
Keeps business rules separate from database concerns
Makes testing possible without spinning up SQL Server
Actually scales beyond a todo app

You end up with controllers talking directly to Entity Framework, business logic scattered across layers, and code that’s impossible to test.

Prerequisites

This assumes you’re comfortable with:

.NET Core 2.2+ (concepts apply to .NET 5+)
Entity Framework Core basics
Dependency injection fundamentals
C# async/await patterns

Time investment: 30-45 minutes to understand the pattern, then it’s your default setup.

The Solution: Three-Layer Architecture

The key is treating your Core business logic as the center of the application—everything else is just infrastructure plugging into it.

Layer Structure

1
├── ClientWeb/         # UI Layer (Razor Pages, Blazor, whatever)
2
├── Core/              # Business logic, interfaces, models
3
└── Infrastructure/    # Database, logging, external services

Clean Architecture file structure in Visual Studio

Core owns the interfaces. Infrastructure implements them. This inverts the typical dependency flow.

Core Layer: Business Rules Only

1
public class ArticleEntity : IEntity
2
{
3
    public int Id { get; set; }
4
    public string Title { get; set; }
5
    public string Content { get; set; }
6
    public DateTime PublishedDate { get; set; }
7
}
8

9
// Core/Interfaces/IGenericRepository.cs
10
public interface IGenericRepository<TEntity> where TEntity : class, IEntity
11
{
12
    Task<IEnumerable<TEntity>> GetAll();
13
    Task<TEntity> GetById(int id);
14
    Task Create(TEntity entity);
15
    Task Update(int id, TEntity entity);
16
    Task Delete(int id);
17
}
18

19
// Core/Services/ArticleService.cs
20
public class ArticleService : IArticleService
21
{
22
    private readonly IGenericRepository<ArticleEntity> _repository;
23

24
    public ArticleService(IGenericRepository<ArticleEntity> repository)
25
    {
26
        _repository = repository;
27
    }
28

29
    public async Task<IEnumerable<ArticleDto>> GetPublishedArticles()
30
    {
31
        var articles = await _repository.GetAll();
32
        return articles
33
            .Where(a => a.PublishedDate <= DateTime.UtcNow)
34
            .OrderByDescending(a => a.PublishedDate);
35
    }
36
}

Notice: No database code in Core. Just interfaces and business rules.

Infrastructure Layer: Implementation Details

1
public class GenericRepository<TEntity> : IGenericRepository<TEntity>
2
    where TEntity : class, IEntity
3
{
4
    private readonly ApplicationDbContext _context;
5
    private readonly DbSet<TEntity> _dbSet;
6

7
    public GenericRepository(ApplicationDbContext context)
8
    {
9
        _context = context;
10
        _dbSet = context.Set<TEntity>();
11
    }
12

13
    public async Task<IEnumerable<TEntity>> GetAll()
14
    {
15
        return await _dbSet.ToListAsync();
16
    }
17

18
    public async Task<TEntity> GetById(int id)
19
    {
20
        return await _dbSet.FindAsync(id);
21
    }
22

23
    public async Task Create(TEntity entity)
24
    {
25
        await _dbSet.AddAsync(entity);
26
        await _context.SaveChangesAsync();
27
    }
28

29
    // Update and Delete implementations...
30
}

Swap Entity Framework for Dapper? Just reimplement IGenericRepository. Your Core layer doesn’t care.

Unlimited power meme - when your architecture is clean

Wiring It Up: Dependency Injection

1
public void ConfigureServices(IServiceCollection services)
2
{
3
    // Infrastructure dependencies
4
    services.AddDbContext<ApplicationDbContext>(options =>
5
        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));
6

7
    // Repository registration
8
    services.AddScoped(typeof(IGenericRepository<>), typeof(GenericRepository<>));
9

10
    // Service registration
11
    services.AddScoped<IArticleService, ArticleService>();
12

13
    // AutoMapper for DTO conversions
14
    services.AddAutoMapper(typeof(Startup));
15

16
    services.AddRazorPages();
17
}

With this setup, your controllers just ask for IArticleService and everything flows.

Using It in Pages/Controllers

1
public class IndexModel : PageModel
2
{
3
    private readonly IArticleService _articleService;
4

5
    public IndexModel(IArticleService articleService)
6
    {
7
        _articleService = articleService;
8
    }
9

10
    public IEnumerable<ArticleDto> Articles { get; set; }
11

12
    public async Task OnGetAsync()
13
    {
14
        Articles = await _articleService.GetPublishedArticles();
15
    }
16
}

Clean. Testable. No DbContext in your page model.

What I Learned / Gotchas

Generic repositories can be controversial. Some developers say they’re an anti-pattern because Entity Framework’s DbSet<T> already is a repository. That’s true for simple apps, but the abstraction pays off when you:

Need to swap data sources
Want to test without EF’s in-memory provider
Work on teams where not everyone should touch database code

AutoMapper setup is easy to get wrong. Create mapping profiles explicitly:

1
public class MappingProfile : Profile
2
{
3
    public MappingProfile()
4
    {
5
        CreateMap<ArticleEntity, ArticleDto>();
6
        CreateMap<ArticleDto, ArticleEntity>();
7
    }
8
}

Version note: This was written for .NET Core 2.2. In .NET 6+, use Program.cs instead of Startup.cs, but the architecture principles are identical.

Going Further

This example uses a blog platform (articles, categories, images) instead of a todo app because it’s closer to real-world complexity. Full source code with working migrations is on GitHub.

Want to go deeper?

Microsoft’s Clean Architecture template (more complex, production-grade)
Martin Fowler’s “Patterns of Enterprise Application Architecture”
My .NET dependency injection deep-dive (future post)

Questions? I’m @brandontillman everywhere.