Building Scalable .NET Core Applications: The 12-Factor App with Clean Architecture

In today’s fast-paced world, developing scalable and maintainable software-as-a-service (SaaS) applications is crucial. The 12-factor app methodology provides a set of guidelines for building such applications, while Clean Architecture helps maintain a separation of concerns and promotes testability. In this blog post, we’ll explore how to implement the 12-factor app principles using .NET Core and the Clean Architecture pattern, with code examples.

1. Codebase

Keeping the codebase well-organized and manageable is essential. In Clean Architecture, you can structure your codebase into separate projects such as Catalog.API, Catalog.Application, Catalog.Core, and Catalog.Infrastructure where each project represents a different layer of your application.


2. Dependencies

Explicitly managing dependencies is crucial for maintaining control over your application. Utilize a package manager like NuGet to declare and manage dependencies in your .NET Core projects. This ensures that all required libraries are easily tracked and updated.


<!-- MyApp.Infrastructure.csproj -->
  <PackageReference Include="EntityFrameworkCore" Version="3.1.10" />
  <PackageReference Include="Dapper" Version="2.0.78" />

3. Config

Storing configuration in a centralized and easily manageable way is vital. In .NET Core, you can leverage the appsettings.json file to store configuration settings. Additionally, you can use environment-specific configuration files like appsettings.Development.json to accommodate different deployment environments.

// appsettings.json
  "ConnectionStrings": {
    "DefaultConnection": "Server=myServer;Database=myDb;User=myUser;Password=myPassword;"
  "Logging": {
    "LogLevel": {
      "Default": "Information"

4. Backing services

Interacting with backing services, such as databases or external APIs, should be done via encapsulated interfaces or repositories. In Clean Architecture, create repositories within the MyApp.Infrastructure project to handle data access and integrate with these backing services.


// MyApp.Infrastructure/CatalogRepository.cs
public class CatalogRepository : ICatalogRepository
    private readonly IDbConnection _dbConnection;

    public CatalogRepository(IDbConnection dbConnection)
        _dbConnection = dbConnection;

    public User GetById(int id)
        // Implement the logic to fetch the user from the database using the provided IDbConnection
        // ...

    // Other repository methods...

5. Build, release, run

Separating the build, release, and run stages helps ensure a smooth deployment process. Utilize build tools like MSBuild or the dotnet CLI to compile and package your application. This separation allows for a clear distinction between the build artifacts and the runtime environment.


# Build the application
dotnet build

# Create a release build
dotnet publish --configuration Release

# Run the application
dotnet run --project Catalog.API

6. Processes

Treating your application as one or more stateless processes promotes scalability and resilience. In .NET Core, you can deploy your application as a self-contained executable or containerized app, which allows for easy scaling and distribution across multiple instances.


# Build a self-contained executable
dotnet publish --configuration Release --output ./publish --self-contained true --runtime linux-x64

# Build a Docker image
docker build -t Catalog.API:latest .

7. Port binding

Exporting services via port binding enables external systems to interact with your application. In Clean Architecture, expose your application’s functionalities through controllers or endpoints, making them accessible to consumers via well-defined APIs.


public class CatalogController : ControllerBase
    private readonly ICatalogRepository _catalogRepository;

    public CatalogController(ICatalogRepository catalogRepository)
        _catalogRepository = catalogRepository;

    public IActionResult GetCatalogById(int id)
        var catalog = _catalogRepository.GetById(id);
        if (catalog == null)
            return NotFound();
        return Ok(user);

    // Other controller actions...

8. Concurrency

Scaling your application horizontally is crucial to handle increased workloads. In .NET Core, you can achieve this by running multiple instances of your application behind a load balancer. The clean separation of concerns in the Clean Architecture pattern allows for effective scaling without compromising the integrity of your application.

9. Disposability

Ensuring that your application starts up quickly and shuts down gracefully enhances its robustness. Implement health checks, use dependency injection to manage resources efficiently, and handle exceptions gracefully. This allows for seamless scaling, restarting, or recovering from failures without causing significant disruptions.

10. Dev/prod parity

Striving for consistency across development, staging, and production environments is essential. Utilize containerization or infrastructure-as-code tools to create reproducible environments. This ensures that the differences between these environments are minimized, reducing the chance of unexpected issues during deployment or runtime.

11. Logs

Treating logs as event streams is crucial for monitoring and debugging purposes. In .NET Core, you can leverage popular logging frameworks such as Serilog or NLog. Output logs to a centralized location or use a log aggregation service to gather and analyze logs effectively.

12. Admin processes

Running administrative or management tasks as one-off processes ensures proper maintenance and operation of your application. For instance, you can develop command-line tools or scheduled jobs to perform tasks like database migrations or other administrative tasks.

Conclusion: By adhering to the 12-factor app principles and leveraging the Clean Architecture pattern, you can build scalable and maintainable .NET Core applications. These practices ensure separation of concerns, clean codebase organization, and effective utilization of dependencies and configurations. Implementing these guidelines will help you develop robust and scalable applications that can adapt to changing requirements and handle increased workloads.

This above snippet gives a basic understanding of the overall concept of a 12-factor app, including its structure and implementation in an application. If you’re interested in creating a complete suite of Microservices applications and following the best practices, I recommend checking out the following series. It will provide you with step-by-step guidance and valuable insights to help you successfully navigate the world of Microservices development. In this entire journey, you will be implementing below architecture right from the scratch.

Course 1: Creating .NET Core Microservices using Clean Architecture

Course 2: Securing Microservices using Identity Server 4

Course 3: Implementing Cross Cutting Concerns

Course 4: Versioning Microservices

Course 5: Building Ecommerce Angular Application

Course 6: Deploying Microservices to Kubernetes and AKS

And for all these courses, you need to have working knowledge of Docker and Kubernetes. In case, if you guys don’t have that knowledge, then you can check out this course as well.

Docker & Kubernetes for .Net and Angular Developers

Thanks for Joining me.



Happy Coding

Also published on Medium.