Clean Architecture in .NET Web API: Comprehensive Cheatsheet

Understanding Clean Architecture

The Case for Clean Architecture: Taming Complexity

In many software projects, traditional layered architectures can inadvertently lead to tightly coupled systems. Business logic often becomes entangled with database details, UI frameworks, or third-party service integrations. This "spaghetti architecture" results in code that is hard to test, painful to change, and brittle when modified. Technology choices become almost irreversible, leading to expensive migrations or outdated systems.

Clean Architecture tackles these challenges head-on by championing the Dependency Rule. This fundamental principle dictates that source code dependencies can only point inwards. The core of your application—the Domain (enterprise business rules) and Application (application-specific business rules) layers—knows nothing about the outer layers like Infrastructure (databases, file systems, network calls) or Presentation (UI, Web API). Outer layers depend on abstractions (interfaces) defined by the inner layers, effectively inverting the control flow for technical details.

Key Benefits Unlocked:

Independent of Frameworks: The core business logic isn't tied to web frameworks, UI toolkits, or database technologies.
Enhanced Testability: Business rules can be unit-tested in isolation, without external dependencies, leading to faster and more reliable tests.
Independent of UI: The UI can change easily, without changing the rest of the system. A Web UI could be swapped for a console UI, for instance, without business rule changes.
Independent of Database: You can swap Oracle or SQL Server, for Mongo or BigTable. Your business rules are not bound to the database.
Independent of External Agencies: Your business rules don't know anything about the outside world.
Improved Maintainability & Flexibility: Changes to external concerns have minimal impact on core logic, making the system easier to evolve and adapt.
Promotes a development focus on core business logic, leading to more accurate implementation.
Helps maintain consistent coding practices, improving application stability and security.
Aids in quickly adding new features, APIs, and third-party components.
Implements abstraction effectively.

When is Clean Architecture Most Beneficial?

For applications with significant and complex business logic that forms the heart of their value proposition.
In long-lived projects expected to undergo evolution, maintenance, and potential technology shifts over many years.
When high degrees of testability and maintainability are paramount project goals.
If there's a strategic need for independence from specific external frameworks or technologies, ensuring future-proofing and adaptability.
When the software needs to closely follow Domain-Driven Design (DDD) principles.
When there is a need for the architecture to help enforce specific development policies and standards.

Important Note: Clean Architecture is not a silver bullet. It introduces a degree of initial setup complexity and requires discipline. For very simple CRUD applications or short-lived projects, the overhead might not be justified. However, for complex, evolving systems, the long-term benefits in resilience, adaptability, and reduced maintenance costs often far outweigh the upfront investment.

Core Principles

Core Philosophy

The Dependency Rule: The cornerstone. Promotes independence of core business logic from external concerns.
Abstraction via Interfaces: Inner layers define abstractions (interfaces); outer layers provide concrete implementations. This inverts traditional control flow for dependencies.
High Testability: Business logic (Domain & Application layers) can be unit-tested independently of UI, database, or any external service.
Enhanced Maintainability & Flexibility: The decoupling makes the system easier to understand, modify, and evolve. Changes in one area (e.g., database technology) are less likely to ripple through the entire codebase.
Focus on Core Logic: Business rules and entities are modeled within the Core (Domain) project, independent of other concerns.
Unidirectional Dependencies: All source code dependencies must flow inwards, towards the Core project. Outer layers depend on the Core; the Core does not depend on any outer layer.
Interface Definition: Inner layers (Domain, Application) define interfaces, and outer layers (Infrastructure, Presentation) implement them.

Key Motivators for Adoption

Tackling systems with **complex and evolving business logic** that needs protection from volatile external details.
Ensuring the **longevity and adaptability** of an application over an extended lifecycle.
Aligning with **Domain-Driven Design (DDD) principles**, placing the domain model at the application's heart.
Achieving **superior testability** by isolating business rules from infrastructure for reliable unit testing.
Gaining **independence from specific technologies** (databases, frameworks, UI), allowing for easier changes or deferral of decisions.

Layers Overview & Responsibilities

Domain Layer (Core)

Purpose: Contains enterprise-wide business logic, entities, and value objects. It's the innermost layer and has no dependencies on other layers in the solution.

Key Components:

Entities: Core business objects with an identity, encapsulating business logic and data.

// Domain/Entities/Product.cs
public class Product
{
    public Guid Id { get; private set; }
    public string Name { get; private set; }
    public decimal Price { get; private set; }

    private Product() {} // For ORM/factory

    public Product(Guid id, string name, decimal price)
    {
        if (id == Guid.Empty) throw new ArgumentException("Id cannot be empty.", nameof(id));
        // ... more validation logic ...
        Id = id; Name = name; Price = price;
    }
    public void UpdatePrice(decimal newPrice) { /* ... validation & logic ... */ Price = newPrice; }
}

Value Objects: Immutable objects defined by their attributes, not an ID.
Aggregates: Clusters of domain objects ensuring consistency within a boundary, with an Aggregate Root entity.
Domain Services: Business logic that doesn't naturally fit within a single entity.

Interfaces: Abstractions defined by the Domain layer.

Repository Interfaces: Contracts for data persistence operations (e.g., IProductRepository).

// Domain/Interfaces/IProductRepository.cs
public interface IProductRepository
{
    Task<Product?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
    Task<IEnumerable<Product>> GetAllAsync(CancellationToken cancellationToken = default);
    Task AddAsync(Product product, CancellationToken cancellationToken = default);
    Task UpdateAsync(Product product, CancellationToken cancellationToken = default);
    Task DeleteAsync(Guid id, CancellationToken cancellationToken = default);
}

Other domain-specific service interfaces.

Domain Events: Represent something significant that happened in the domain. Used for side effects and decoupling.
Custom Domain Exceptions: Specific exceptions to signal violations of domain rules (e.g., `InsufficientStockException`).
Specifications: (e.g., for defining complex query criteria in a reusable way).
Domain-Specific Validators/Guards: For validating entities against business rules and ensuring invariants.
Enums: Domain-specific enumerations.
(Event Handlers - Domain-Level, if applicable): Handlers for domain events orchestrating logic *within* the domain.

Application Layer

Purpose: Contains application-specific business logic. It orchestrates use cases by interacting with the Domain layer and coordinating with the Infrastructure layer through interfaces.

Key Components:

Use Cases/Interactors:

Commands & Command Handlers: Encapsulate operations that change the system's state.

// Application/Products/Commands/CreateProductCommand.cs
public record CreateProductCommand(string Name, decimal Price) : IRequest<Guid>;

// Application/Products/Handlers/CreateProductCommandHandler.cs
public class CreateProductCommandHandler : IRequestHandler<CreateProductCommand, Guid>
{
    private readonly IProductRepository _productRepository;
    private readonly IUnitOfWork _unitOfWork;

    public CreateProductCommandHandler(IProductRepository productRepository, IUnitOfWork unitOfWork)
    {
        _productRepository = productRepository; _unitOfWork = unitOfWork;
    }

    public async Task<Guid> Handle(CreateProductCommand request, CancellationToken cancellationToken)
    {
        var product = new Product(Guid.NewGuid(), request.Name, request.Price);
        await _productRepository.AddAsync(product, cancellationToken);
        await _unitOfWork.SaveChangesAsync(cancellationToken); // Explicitly save changes
        return product.Id;
    }
}

Queries & Query Handlers: Encapsulate operations that retrieve data without altering state.

Data Transfer Objects (DTOs): For transferring data between layers.
Interfaces for Infrastructure Services: Abstractions for infrastructure concerns (e.g., `IEmailSender`, `IDateTimeProvider`, `IFileStorage`).
Validation Logic: For input data (e.g., using FluentValidation, often as MediatR pipeline behaviors).
CQRS Pattern Support: Tools like MediatR are commonly used here to separate commands and queries.
Application Exceptions: For errors specific to application logic (e.g., `ValidationException`, `NotFoundException`).
Pipeline Behaviors (e.g., for MediatR): For cross-cutting concerns like validation, logging, or caching applied to use cases.

Infrastructure Layer

Purpose: Handles all external concerns and technical details like databases, file systems, network calls, and third-party services. It implements the interfaces defined in the Application and Domain layers.

Key Components:

Data Access/Persistence Implementations:

Repositories: Concrete implementations of repository interfaces (e.g., using Entity Framework Core).

// Infrastructure/Persistence/Repositories/ProductRepository.cs
public class ProductRepository : IProductRepository
{
    private readonly ApplicationDbContext _dbContext;
    public ProductRepository(ApplicationDbContext dbContext) {_dbContext = dbContext;}
    // ... implementations of IProductRepository methods using _dbContext ...
    public async Task AddAsync(Product product, CancellationToken ct) => 
        await _dbContext.Products.AddAsync(product, ct);
    // ... etc.
}

DbContext: EF Core `DbContext` class for database interaction.

// Infrastructure/Persistence/ApplicationDbContext.cs (EF Core example)
public class ApplicationDbContext : DbContext, IUnitOfWork // Explicitly implementing IUnitOfWork
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options) { }
    public DbSet<Product> Products { get; set; }
    // ... other DbSets

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
        base.OnModelCreating(modelBuilder);
    }

    public async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
    {
        return await base.SaveChangesAsync(cancellationToken);
    }
}

Database migrations.

External Service Integrations:
- Clients for payment gateways, **email services (Emailing Implementations)**, **SMS services**, third-party APIs.
- Cloud service accessors** (e.g., Azure Storage, AWS S3).

Caching Implementations: (e.g., Redis, In-Memory).

Identity Service Implementations: User authentication and authorization.

File System Accessors/Implementations.

Clock/DateTime Service Implementations.

Logging Service Implementations.

Other Infrastructure Services: (e.g., concrete implementations of any other interfaces defined by the Application layer for infrastructure concerns).

Presentation Layer (Web API)

Purpose: Handles user interaction (HTTP requests/responses for an API). It translates user input into commands/queries for the Application layer and presents the results.

Key Components:

Controllers/API Endpoints: Receive HTTP requests, perform minimal validation/mapping, and delegate to Application layer.
// Presentation/Controllers/ProductsController.cs [ApiController] [Route("api/[controller]")] public class ProductsController : ControllerBase { private readonly ISender _mediator; // Using MediatR's ISender public ProductsController(ISender mediator) {_mediator = mediator;} [HttpPost] public async Task<IActionResult> CreateProduct([FromBody] CreateProductCommand command) { var productId = await _mediator.Send(command); return CreatedAtAction(nameof(GetProductById), new { id = productId }, new { id = productId }); } [HttpGet("{id}")] public async Task<IActionResult> GetProductById(Guid id) { // var query = new GetProductByIdQuery(id); // Assuming a GetProductByIdQuery exists // var productDto = await _mediator.Send(query); // if (productDto == null) return NotFound(); // return Ok(productDto); return Ok($"Product with ID {id} retrieved (example)."); // Simplified for cheatsheet } }

Middleware: For cross-cutting concerns like global error handling, authentication, request logging.

Dependency Injection (DI) Setup / Composition Root: Configuration of services and their dependencies (typically in `Program.cs`). This is the "Composition Root".

API Models/ViewModels: Models specific to API requests/responses. Often mapped to/from Application layer DTOs.

API Versioning, OpenAPI/Swagger Configuration.

Filters (Action Filters, Exception Filters, etc.): For cross-cutting concerns specific to API request processing.

Model Binders: Custom logic for binding request data to models.

(Other UI-specific services if not strictly a Web API, e.g., for MVC: ViewModels, Tag Helpers - though less relevant for a pure Web API cheatsheet).

Project Structure & Visual Studio Setup

Typical Solution Structure

A common way to organize projects in a .NET solution reflecting Clean Architecture:

YourProjectSolution.sln ├── src │ ├── YourProject.Domain.csproj (.NET Class Library) │ │ ├── Entities/ │ │ ├── Aggregates/ │ │ ├── Enums/ │ │ ├── Events/ │ │ ├── Exceptions/ │ │ ├── Interfaces/ (e.g., IProductRepository.cs) │ │ ├── Specifications/ │ │ ├── Validators/Guards/ │ │ └── ValueObjects/ │ │ │ ├── YourProject.Application.csproj (.NET Class Library) │ │ ├── Features/ (Organized by feature, e.g., Products, Orders) │ │ │ ├── Products/ │ │ │ │ ├── Commands/ │ │ │ │ ├── Queries/ │ │ │ │ └── DTOs/ │ │ ├── Common/ │ │ │ ├── Interfaces/ (e.g., IEmailSender.cs, IDateTimeProvider.cs) │ │ │ ├── Behaviors/ (MediatR pipeline behaviors) │ │ │ └── Mappings/ (AutoMapper profiles if used) │ │ └── Exceptions/ │ │ │ ├── YourProject.Infrastructure.csproj (.NET Class Library) │ │ ├── Persistence/ │ │ │ ├── DataContext/ (e.g., ApplicationDbContext.cs) │ │ │ ├── Repositories/ (e.g., ProductRepository.cs) │ │ │ ├── Migrations/ │ │ │ └── Configurations/ (EF Core entity type configurations) │ │ ├── Services/ (e.g., EmailSender.cs, DateTimeProvider.cs) │ │ └── Identity/ │ │ │ └── YourProject.WebApi.csproj (ASP.NET Core Web API Project) │ ├── Controllers/ │ ├── Middleware/ │ ├── Filters/ │ ├── Extensions/ (Service registration extensions) │ ├── appsettings.json │ └── Program.cs (Composition Root) │ └── tests ├── YourProject.Domain.UnitTests.csproj ├── YourProject.Application.UnitTests.csproj ├── YourProject.Infrastructure.IntegrationTests.csproj └── YourProject.Presentation.IntegrationTests.csproj

Setting up the Projects in Visual Studio:

Create the Solution and Presentation Layer (Web API):

Open Visual Studio.

Select "Create a new project".

Choose the "ASP.NET Core Web API" template. Click Next.

Name your project (e.g., `YourProject.WebApi`) and solution (e.g., `YourProjectSolution`). Click Next.

Choose your desired .NET framework version. Configure other settings as needed. Click Create.

This project will serve as your Presentation Layer.

Add the Domain Layer:

In Solution Explorer, right-click on the Solution (`YourProjectSolution`).

Select Add > New Project...

Choose the "Class Library" template. Click Next.

Name the project `YourProject.Domain`. Click Next.

Choose the same .NET framework version as your Web API project. Click Create.

Delete the default `Class1.cs` file.

Create folders like `Entities`, `Interfaces`, `ValueObjects`, etc., as shown in the structure above.

Important: The Domain project should NOT have project references to any other layer project in this solution.

Add the Application Layer:

Right-click on the Solution > Add > New Project...

Choose "Class Library". Name it `YourProject.Application`.

Ensure the .NET framework version matches. Click Create.

Delete `Class1.cs`.

Create folders like `Features`, `Common/Interfaces`, `DTOs`, etc.

Add Project Reference: Right-click on the `YourProject.Application` project > Add > Project Reference... > Check `YourProject.Domain` > OK.

Add the Infrastructure Layer:

Right-click on the Solution > Add > New Project...

Choose "Class Library". Name it `YourProject.Infrastructure`.

Ensure the .NET framework version matches. Click Create.

Delete `Class1.cs`.

Create folders like `Persistence/DataContext`, `Repositories`, `Services`, etc.

Add Project Reference: Right-click on the `YourProject.Infrastructure` project > Add > Project Reference... > Check `YourProject.Application` > OK. (The Infrastructure layer implements interfaces defined in Application and Domain).

Install necessary NuGet packages here (e.g., `Microsoft.EntityFrameworkCore`, database providers, SDKs).

Configure Presentation Layer Dependencies:

The `YourProject.WebApi` (Presentation) project orchestrates the application.

Add Project References: Right-click on the `YourProject.WebApi` project > Add > Project Reference... > Check `YourProject.Application` and `YourProject.Infrastructure` > OK.

This allows the Web API to send commands/queries to the Application layer and to register services (dependency injection) from the Infrastructure layer in `Program.cs`.

Set Startup Project:

Right-click on the `YourProject.WebApi` project in Solution Explorer and select "Set as Startup Project".

Dependency Flow Reminder:
Presentation (WebApi) → references Application & Infrastructure
Infrastructure → references Application (to implement its interfaces and use its DTOs/Domain types)
Application → references Domain
Domain → references (No other project dependencies within the solution)

Best Practices & Considerations

Key Practices

Dependency Injection (DI): Absolutely crucial. Register dependencies in the Presentation layer's `Program.cs` (the Composition Root). Use constructor injection primarily.

MediatR: Widely used for implementing CQRS in the Application layer. It helps decouple command/query senders from their handlers and allows for cross-cutting concerns via pipeline behaviors.

FluentValidation: A popular library for robust validation in the Application layer, often integrated with MediatR pipelines.

AutoMapper (or similar): Useful for mapping between Entities, DTOs, and API Models. Define profiles in the Application layer or where the mapping is most relevant.

Unit of Work (UoW) Pattern: Often implemented in the Infrastructure layer (e.g., within the `DbContext`). An `IUnitOfWork` interface can be defined in the Application layer to be consumed by command handlers.

Error Handling: Implement a global error handling middleware in the Presentation layer to catch exceptions and return consistent API error responses. Define custom exceptions in Domain and Application layers for specific business or application errors.

Configuration (Options Pattern): Use the Options pattern (`IOptions`) for strongly-typed configuration, typically configured in the Presentation layer and injected where needed.

Async/Await: Use `async`/`await` thoroughly for I/O-bound operations. Prefer `async Task` over `async void` for most methods (except event handlers where `async void` is sometimes necessary).

Single Responsibility Principle (SRP): Apply SRP to classes and methods within each layer to improve cohesion and reduce coupling.

Lean Controllers: Controllers should be thin, primarily responsible for receiving HTTP requests, validating input (often with model binding), and delegating work to the Application layer (e.g., MediatR). Avoid business logic in controllers.

Avoid Leaking Abstractions: Do not expose `IQueryable` from repositories directly to the Application or Presentation layers, as this can lead to infrastructure concerns (like specific EF Core LINQ expressions) leaking outwards. Queries should be fully defined within the data access layer or use well-defined specification patterns.

Testing Strategy:

Domain Layer: Pure unit tests with no external dependencies.

Application Layer: Unit tests, mocking repository interfaces and other infrastructure dependencies.

Infrastructure Layer: Integration tests against a real (or test instance of) database or external services.

Presentation Layer: Integration tests (testing API endpoints, e.g., using `WebApplicationFactory`).