Implementing Clean Architecture in ASP.NET Core Web API

In the previous article, we explored Clean Architecture, its core principles, and the responsibilities of its different layers. Now, let's take the next step and understand how to implement Clean Architecture in a real-world application using ASP.NET Core Web API and C#.

As applications grow, maintaining a well-organized codebase becomes increasingly challenging. Mixing business logic, database operations, and API-related code within a single project can lead to tight coupling, making applications difficult to maintain, test, and extend.

Clean Architecture helps solve these challenges by separating an application into independent layers, ensuring that business logic remains independent of external frameworks, databases, and other technical dependencies.

In this tutorial, we will build an Employee Management Web API using Clean Architecture in ASP.NET Core. We will create separate projects for the Domain, Application, Infrastructure, and Presentation layers and understand how these layers communicate with each other.

By the end of this tutorial, you will understand how to structure an ASP.NET Core Web API using Clean Architecture, implement CRUD operations, integrate Entity Framework Core with SQL Server, and configure dependency injection to maintain loose coupling between layers.

Implementing Clean Architecture in ASP.NET Core Web API Using C#

What We Are Going to Build

In this demonstration, we will build an Employee Management Web API using Clean Architecture in ASP.NET Core. We will separate business logic, application workflows, infrastructure concerns, and API endpoints into independent layers.

The API will support basic employee management operations such as creating, retrieving, updating, and deleting employees.

Prerequisites

Visual Studio 2022
.NET 8 or .NET 10 SDK (choose one target framework for the tutorial)
C#
ASP.NET Core Web API
Entity Framework Core
SQL Server
Swagger / OpenAPI

Create the Solution and Projects

The first step in implementing Clean Architecture is to create a solution and organize the application into separate projects. Each project will represent a specific layer of the architecture and have clearly defined responsibilities.

We will create four separate projects:

CleanArchitectureDemo.Domain: Contains core business entities, value objects, and business rules.
CleanArchitectureDemo.Application: Contains application use cases, interfaces, DTOs, and business workflows.
CleanArchitectureDemo.Infrastructure: Handles database operations, repository implementations, and external service integrations.
CleanArchitectureDemo.API: Acts as the presentation layer and exposes HTTP endpoints through ASP.NET Core Web API.

Step 1: Create a New Solution

Open Visual Studio 2022 and follow these steps:

Select Create a new project.
Search for Blank Solution.
Select the Blank Solution template.
Click Next.
Enter the solution name as CleanArchitectureDemo.
Select your preferred location.
Click Create.

Step 2: Create the Domain Project

Right-click the solution and select Add → New Project.

Search for Class Library.
Select the Class Library template.
Set the project name to CleanArchitectureDemo.Domain.
Select the target framework.
Click Create.

The Domain project contains the core business entities and rules of the application.

Step 3: Create the Application And Infrastructure Project

Repeat the same process to create another two Class Library projects. Set the project name to

CleanArchitectureDemo.Application
CleanArchitectureDemo.Infrastructure

The Application project will contain application-specific logic, interfaces, DTOs, and use cases.

Similarly Infrastructure project will contain the implementations of interfaces defined in the Application Layer, database configurations, Entity Framework Core DbContext, and repository implementations.

Step 4: Create the API Project

Now, create the presentation layer using ASP.NET Core Web API.

Right-click the solution and select Add → New Project.
Search for ASP.NET Core Web API.
Select the ASP.NET Core Web API template.
Set the project name to CleanArchitectureDemo.API.
Select your target framework.
Enable OpenAPI support.
Click Create.

This project will expose the application functionality through REST API endpoints.

Step 5: Configure Project References

After creating all four projects, we need to configure project references to maintain the dependency rules of Clean Architecture.

Right-click the Application project.
Select Add → Project Reference.
Select the Domain project and click OK.
Right-click the Infrastructure project and select Add → Project Reference.
Select both Domain and Application projects.
Right-click the API project and select Add → Project Reference.
Select both Application and Infrastructure projects.

Alternatively, you can use the .NET CLI commands to add project references quickly:

</> Bash
dotnet add CleanArchitectureDemo.Application reference CleanArchitectureDemo.Domain

dotnet add CleanArchitectureDemo.Infrastructure reference CleanArchitectureDemo.Application

dotnet add CleanArchitectureDemo.Infrastructure reference CleanArchitectureDemo.Domain

dotnet add CleanArchitectureDemo.API reference CleanArchitectureDemo.Application

dotnet add CleanArchitectureDemo.API reference CleanArchitectureDemo.Infrastructure

Step 6: Solution Structure

After completing these steps, your solution should look like this:

</> Plain Text
CleanArchitectureDemo
│
├── CleanArchitectureDemo.Domain
│   └── Class1.cs
│
├── CleanArchitectureDemo.Application
│   └── Class1.cs
│
├── CleanArchitectureDemo.Infrastructure
│   └── Class1.cs
│
└── CleanArchitectureDemo.API
    ├── Controllers
    ├── Program.cs
    ├── appsettings.json
    └── Properties

Remove the default Class1.cs files from the Class Library projects because we will create our own classes in the upcoming sections.

Now we have created 4 pojects to represent architecture layer's. The next step is implement the Domain Layer

Implement the Domain Layer

The Domain Layer is the core of Clean Architecture. It contains the application's business entities, value objects, domain events, and business rules.

In our Employee Management Web API, the Domain Layer will contain the Employee entity, which represents an employee in the application.

Create the Employee Entity

Right-click the Domain project.
Select Add → New Folder.
Name the folder Entities. We will keep all our domain entities inside this folder.
Right-click the Entities folder and select Add → Class.
Name the class Employee.cs.
Add the following properties to represent an employee:
```
</> C#
      namespace CleanArchitectureDemo.Domain.Entities;
      {
        public class Employee
        {
          public int Id { get; set; }
          public string Name { get; set; }
          public string Email { get; set; }
          public decimal Salary { get; set; }
        }
      }
  	
```
Let's understand the important parts of this entity.
- Id: Uniquely identifies an employee.
- Name: Stores the employee's name.
- Email: Stores the employee's email address.
- Salary: Stores the employee's salary.
- Constructor: Initializes an employee with valid information.
- UpdateDetails(): Updates employee information while enforcing basic business rules.

The Domain Layer represents the heart of our application. It defines the core business entities and rules without depending on external technologies. In the next step, we will implement the Application Layer, where we define the use cases, service interfaces, and business workflows of our Employee Management application.

Summary

In this tutorial, we explored how to implement Clean Architecture in an ASP.NET Core Web API using C# by building a practical Employee Management application.

We created separate projects for the Domain, Application, Infrastructure, and Presentation layers, with each layer having clearly defined responsibilities. Also we implemented the Domain Layer and in my next article we will implement the Application Layer.

I hope this step-by-step demonstration helps you understand how to structure and implement Clean Architecture in your ASP.NET Core Web API projects. You can apply the same principles to your own applications to create a clean, modular, and maintainable codebase.

Thanks