Guide · Open source
How to use CleanArchitecture: template setup and structure
Updated · written with AI from the project's own documentation and checked against our catalogue data
CleanArchitecture by ardalis is a starting-point solution template for ASP.NET Core. It gives you a pre-organized solution split into layers such as Core, Use Cases, Infrastructure and Web, so you do not have to design that structure yourself. This guide explains what the template is, how to get it, and how to choose between its full and minimal versions.
Clean Architectureardalis/CleanArchitecture · ★ 18.5k · MIT Install options & downloads Quick start
- 1Install the .NET SDK. The .NET SDK is the listed prerequisite. Install it before you create the project.
- 2Clone the repository. Run git clone https://github.com/ardalis/CleanArchitecture to get the template source.
- 3Pick full or minimal. Choose clean-arch for the full template or min-clean for the minimal one, based on the README comparison.
- 4Review the layers. Read the sections on Core, Use Cases, Infrastructure, Web and SharedKernel to see where code belongs.
- 5Set up HTTPS and migrations. Trust the self-signed developer certificate for localhost and follow the Running Migrations section.
- 6Add your web approach. Add Ardalis.ApiEndpoints, Controllers or Razor Pages, following the matching README section.
What the CleanArchitecture template is
The template is a Visual Studio and dotnet CLI project template for a Clean Architecture solution in ASP.NET Core. The README notes that Clean Architecture is also called hexagonal, ports-and-adapters, or onion architecture, since these are different names for the same loosely coupled, dependency-inverted design.
It is a starting point. You build your application on top of the layers it provides.
- Core: the domain layer
- Use Cases: application logic
- Infrastructure: data and external concerns
- Web: the ASP.NET Core project
Install the template and prerequisites
The listed prerequisite is the .NET SDK. The README's install step is to clone the repository with git. The template is also published as a NuGet package named Ardalis.CleanArchitecture.Template, and the README links to it.
The main branch targets .NET 9, which corresponds with NuGet package version 10.x. For older versions, see the project's Releases page.
git clone https://github.com/ardalis/CleanArchitectureChoose the full or minimal template
The dotnet CLI template comes in two variants. Full Clean Architecture uses the short name clean-arch. Minimal Clean Architecture uses the short name min-clean. The README includes a template comparison and a section titled Which Template Should I Use? to help you decide.
If you are unsure, read the comparison section in the README before you create the project. The source excerpt here does not list the differences between the two in detail.
- Full: short name clean-arch
- Minimal: short name min-clean
Understand the layers before you change code
The template keeps the domain separate from the web and infrastructure code. The README has dedicated sections for each project: The Core Project, The Use Cases Project, The Infrastructure Project, The Web Project, The SharedKernel Package and The Test Projects. Reading these first shows where each kind of code belongs.
The README also covers Where To Validate and Domain Events under Patterns Used. Use these as reference points when you add features.
Run the app and set up the database
By default the site uses HTTPS and expects a self-signed developer certificate for localhost. If Chrome shows an error, the README points to a Stack Overflow answer with mitigation steps.
The README has a Running Migrations section, which covers the database setup. Check that section for the exact steps for your version.
Add controllers, Razor Pages or endpoints
The README has a section called What about Controllers and Razor Pages? It covers adding Ardalis.ApiEndpoints, adding Controllers, and adding Razor Pages. Pick the approach that fits your team and follow the matching subsection.
The template is meant to be extended, so these additions are part of normal use.
What people use it for
- Starting a new ASP.NET Core backend service with a structured layout
- Learning Clean Architecture or domain-driven design using a working example
- Giving a team a shared starting structure for backend services
- Comparing a full and a minimal template before starting a project
Frequently asked questions
Is CleanArchitecture free to use?
Yes. The project is licensed under the MIT licence, as listed in its details. The MIT licence permits use, though you should read its terms for your own situation.
What do I need to install before using it?
The listed prerequisite is the .NET SDK. The README's install step is to clone the repository from GitHub.
What is the difference between clean-arch and min-clean?
clean-arch is the full Clean Architecture template and min-clean is the minimal one. The README has a Template Comparison section that explains the choice. The source excerpt here does not list the differences in detail.
Does it work with ASP.NET Core?
Yes. The template is a Clean Architecture solution for ASP.NET Core. It is specific to that framework, so it is not suited to projects that need a different one.
Why does Chrome show an error when I run the site?
By default the site uses HTTPS and expects a self-signed developer certificate for localhost. The README links to a Stack Overflow answer with mitigation instructions for Chrome errors.
How does it compare to jasontaylordev/CleanArchitecture or eShopOnWeb?
Comparable projects include jasontaylordev/CleanArchitecture, dotnet-architecture/eShopOnWeb and EduardoPires/EquinoxProject. The source excerpt does not compare their features, so check each project's documentation to decide.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this template if you are an ASP.NET Core developer who wants a structured Clean Architecture starting point, or you are learning the pattern with a working example. Pick something else if you are new to C# or .NET, need a different language or framework, or want a finished application rather than a base to build on.
Install options & downloads