Clean Architecture vs. Onion Architecture: A Beginner's Guide with Code Examples

Uncle Bob’s Approach Vs Jeffrey Palermo’s Approach

If you're new to software architecture in ASP.NET Core, you've probably heard about Clean Architecture and Onion Architecture. Both promote maintainable and testable code, but how do they differ? Let’s break them down with simple explanations and code examples.

---

1. What Do They Have in Common?

Both architectures follow these core principles:
✅ Business logic is independent of UI, databases, and frameworks.
✅ Dependency flows inward (outer layers depend on inner layers, not vice versa).
✅ Easy to test (business rules can be tested without databases or APIs).

---

2. Clean Architecture (Uncle Bob’s Approach)

Layers

1. Domain → Entities & business rules

2. Application → Use cases & interfaces

3. Infrastructure → Database, APIs

4. Presentation → UI (MVC, Blazor, API)

Example: User Registration

Step 1: Domain Layer (Business Rules)

// MyApp.Domain/Entities/User.cs
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
}

Step 2: Application Layer (Use Cases)

// MyApp.Application/Interfaces/IUserRepository.cs
public interface IUserRepository
{
    void Add(User user);
}

// MyApp.Application/UseCases/RegisterUser.cs
public class RegisterUser
{
    private readonly IUserRepository _userRepo;

    public RegisterUser(IUserRepository userRepo) => _userRepo = userRepo;

    public void Execute(User user)
    {
        // Business logic (e.g., validate email)
        _userRepo.Add(user);
    }
}

Step 3: Infrastructure Layer (Database)

// MyApp.Infrastructure/Repositories/UserRepository.cs
public class UserRepository : IUserRepository
{
    private readonly AppDbContext _db;
    public UserRepository(AppDbContext db) => _db = db;

    public void Add(User user)
    {
        _db.Users.Add(user);
        _db.SaveChanges();
    }
}

Step 4: Presentation Layer (API)

// MyApp.Web/Controllers/UserController.cs
[ApiController]
public class UserController : ControllerBase
{
    private readonly RegisterUser _registerUser;

    public UserController(RegisterUser registerUser) => _registerUser = registerUser;

    [HttpPost("register")]
    public IActionResult Register(User user)
    {
        _registerUser.Execute(user);
        return Ok();
    }
}

---

3. Onion Architecture (Jeffrey Palermo’s Approach)

---

Layers (Concentric Circles)

• Core(Entities) → Domain models

• Services → Business logic

• Infrastructure → Database, APIs

• UI → Controllers, Pages

Example: User Registration

Step 1: Core Layer (Entities)

// MyApp.Core/Entities/User.cs
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
}

Step 2: Services Layer (Business Logic)

// MyApp.Services/Interfaces/IUserService.cs
public interface IUserService
{
    void Register(User user);
}

// MyApp.Services/UserService.cs
public class UserService : IUserService
{
    private readonly IUserRepository _userRepo;
    public UserService(IUserRepository userRepo) => _userRepo = userRepo;

    public void Register(User user)
    {
        // Business logic
        _userRepo.Add(user);
    }
}

Step 3: Infrastructure Layer (Database)

// MyApp.Infrastructure/Repositories/UserRepository.cs
public class UserRepository : IUserRepository
{
    private readonly AppDbContext _db;
    public UserRepository(AppDbContext db) => _db = db;

    public void Add(User user)
    {
        _db.Users.Add(user);
        _db.SaveChanges();
    }
}

Step 4: UI Layer (API Controller)

// MyApp.Web/Controllers/UserController.cs
[ApiController]
public class UserController : ControllerBase
{
    private readonly IUserService _userService;

    public UserController(IUserService userService) => _userService = userService;

    [HttpPost("register")]
    public IActionResult Register(User user)
    {
        _userService.Register(user);
        return Ok();
    }
}

---

4. Key Differences

---

---

5. Which One Should You Choose?

---

• For beginners → Start with Onion Architecture (easier to visualize).

• For modern .NET apps → Clean Architecture (better for CQRS, MediatR).

• For enterprise systems → Either works, but Onion is more DDD-friendly.

---

6. Final Thoughts

---

Both architectures keep business logic independent, making your code:
✔ Easier to test
✔ More maintainable
✔ Flexible for future changes

#ASPNETCore #CleanArchitecture #OnionArchitecture #DotNet #LearnWithAmran