Clean Architecture docs on Ardalis Clean Architecture

Upgrading from v10.x to v11.x

Mon, 01 Jan 0001 00:00:00 +0000

Upgrading from v10.x to v11.x#

If you started your project with version 10.0.1 (or similar) of the template and want to incorporate the architectural upgrades of version 11.0.0, follow this guide.

The “Diff” Strategy#

Since this template serves as a starting point, the most reliable way to upgrade an existing project is to perform a differential comparison:

Generate a brand new solution using the v11 template (e.g., dotnet new clean-arch -o Your.ProjectName).
Use a diff tool (like Beyond Compare, WinMerge, or git diff) to compare the newly generated solution against the original v10 vanilla template you started with (or your current codebase).
Manually apply the structural or package changes to your existing project.

Key Changes in v11.x#

Several dependencies and implementation details were altered in this release. The most significant changes include:

ADR 001: Replace Autofac with .NET DI

Mon, 01 Jan 0001 00:00:00 +0000

ADR 001: Replace Autofac with .NET Core Dependency Injection#

Status#

Accepted

Context#

Initially, this repository employed Autofac for dependency injection. At the time of adoption, Autofac was preferred due to its robust feature set, including:

Support for advanced scenarios such as decorators and modules, which could be placed close to their corresponding implementations.
A well-established history of stability and maturity, having been used in various projects before .NET Core’s built-in DI was fully featured.

As the .NET ecosystem evolved, the built-in DI container began to meet the needs of our project without introducing the added complexity associated with Autofac. The .NET DI framework has matured significantly, offering sufficient functionality for typical use cases, including:

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started#

To use this template, there are two template options:

Full Clean Architecture (clean-arch) - Complete multi-project solution with Core, UseCases, Infrastructure, and Web
Minimal Clean Architecture (min-clean) - Simplified single-project vertical slice architecture

Choose based on your project’s complexity and team preferences. See Template Comparison below.

Template Installation#

Install the templates from NuGet:

# Full Clean Architecture template
dotnet new install Ardalis.CleanArchitecture.Template

# Minimal Clean Architecture template 
dotnet new install Ardalis.MinimalClean.Template

Using the dotnet CLI template#

Full Clean Architecture (`clean-arch`)#

First, install the template from NuGet (https://www.nuget.org/packages/Ardalis.CleanArchitecture.Template/):

Goals & Design Decisions

Mon, 01 Jan 0001 00:00:00 +0000

Goals#

The goal of this repository is to provide a basic solution structure that can be used to build Domain-Driven Design (DDD)-based or simply well-factored, SOLID applications using .NET Core. Learn more about these topics here:

If you’re used to building applications as single-project or as a set of projects that follow the traditional UI -> Business Layer -> Data Access Layer “N-Tier” architecture, I recommend you check out these two courses (ideally before DDD Fundamentals):

Minimal Clean Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Minimal Clean Architecture#

Overview#

The Minimal Clean Architecture template provides a simplified, pragmatic approach to Clean Architecture for ASP.NET Core applications. It maintains the core principles of Clean Architecture—separation of concerns, dependency inversion, and testability—while reducing complexity through a single-project Vertical Slice Architecture (VSA).

Philosophy#

Core Principles#

Simplicity First: Minimize unnecessary abstractions and project boundaries
Vertical Slices: Organize by feature rather than technical layer
Pragmatic DDD: Use domain patterns where they add value, not everywhere
Progressive Enhancement: Start simple, add complexity only when needed

Clean Architecture Principles Maintained#

✅ Dependency Inversion: Domain doesn’t depend on infrastructure
✅ Testability: Business logic can be tested in isolation
✅ Separation of Concerns: Clear boundaries between domain, infrastructure, and presentation
✅ Framework Independence: Domain logic isn’t coupled to ASP.NET Core

Simplifications from Full Template#

Single Project: All code in one Web project instead of 4+ projects
Simplified DDD: Essential patterns only (entities, aggregates) without extensive value objects, specifications
Optional CQRS: Mediator is optional; logic can live in endpoints
Direct Data Access: Can use DbContext directly or simple repositories instead of complex repository pattern
Vertical Organization: Group by feature (Cart, Order, Product) instead of by layer

Architecture#

Project Structure#

MinimalClean.Architecture.Web/
├── Domain/ # Domain Layer
│ ├── CartAggregate/
│ │ ├── Cart.cs # Aggregate root
│ │ ├── CartItem.cs # Entity
│ │ └── Events/ # Domain events (optional)
│ ├── OrderAggregate/
│ └── ProductAggregate/
├── Infrastructure/ # Infrastructure Layer
│ ├── Data/
│ │ ├── AppDbContext.cs # EF Core DbContext
│ │ ├── Config/ # EF configurations
│ │ │ ├── CartConfiguration.cs
│ │ │ └── OrderConfiguration.cs
│ │ └── Migrations/ # EF migrations
│ ├── Email/ # External services
│ └── Services/ # Infrastructure services
├── Endpoints/ # Presentation Layer
│ ├── Cart/
│ │ ├── Create.cs # Create cart endpoint
│ │ ├── AddItem.cs # Add item to cart
│ │ └── List.cs # List carts
│ ├── Order/
│ └── Product/
└── Program.cs # Application startup

Vertical Slice Organization#

Each feature (Cart, Order, Product) contains:

Mon, 01 Jan 0001 00:00:00 +0000

Architecture Decision Records (ADR)#

What is an Architecture Decision Record (ADR)?#

An Architecture Decision Record (ADR) documents significant architecture decisions made throughout a project, capturing the context, rationale, and consequences of each decision. This promotes transparency and provides a historical reference for future design considerations.

Purpose of ADRs#

Knowledge Management: Consolidates architectural knowledge and decisions.
Collaboration: Enhances team communication by documenting discussions and outcomes.
Clarity: Provides clear reasoning behind design choices, making it easier for new team members to understand past decisions.

Best Practices for Writing ADRs#

Be Specific: Each ADR should address a single architectural decision. Avoid conflating multiple decisions into one record.
Document Context: Clearly explain the project’s context and relevant considerations that influenced the decision. Include team dynamics and priorities.
Rationale and Consequences: Describe the reasons for the decision, including pros and cons, and outline the implications of the decision for the project and

future architecture. 4. Immutable Records: Once an ADR is created, avoid altering it. Instead, create a new ADR to reflect any changes or updates. 5. Timestamp Entries: Include timestamps to track when each decision was made, especially for aspects that may evolve over time (e.g., costs, schedules). 6. Use Templates: Utilize established templates for consistency and completeness in documenting ADRs.

Clean Architecture docs on Ardalis Clean Architecture

Upgrading from v10.x to v11.x

Upgrading from v10.x to v11.x#

The “Diff” Strategy#

Key Changes in v11.x#

ADR 001: Replace Autofac with .NET DI

ADR 001: Replace Autofac with .NET Core Dependency Injection#

Status#

Context#

Getting Started

Getting Started#

Template Installation#

Using the dotnet CLI template#

Full Clean Architecture (clean-arch)#

Goals & Design Decisions

Goals#

Minimal Clean Architecture

Minimal Clean Architecture#

Overview#

Philosophy#

Core Principles#

Clean Architecture Principles Maintained#

Simplifications from Full Template#

Architecture#

Project Structure#

Vertical Slice Organization#

Architecture Decision Records (ADR)#

What is an Architecture Decision Record (ADR)?#

Purpose of ADRs#

Best Practices for Writing ADRs#

Full Clean Architecture (`clean-arch`)#