Clean Architecture Template

This is a configurable template for creating .NET Core Web API projects following the principles of Clean Architecture and Domain-driven design approach. The template is available as a NuGet package.

Installation

The easiest way to get started with the template is to install it by executing the following command:

~$ dotnet new --install Clean.Architecture.Template::6.0.0

When that command is executed, the cleanarch template will appear on the list of available templates for the dotnet new command.

Usage

Create project

To create a new project, you can run the following command:

~$ dotnet new cleanarch -n MyAwesomeProject

After executing this command, the project will be created in a new folder named MyAwesomeProject. If you want to create your project in the current folder, execute the following command:

~$ dotnet new cleanarch

The output of running that command is below:

Template options

The cleanarch template has additional options that you can pass with this command. To display these options, execute the following command:

~$ dotnet new cleanarch --help

The template has the following additional options:

examples

1. To create a new solution additionally with docker and swagger support, but without test projects, you can run the following command:

~$ dotnet new cleanarch -n MyAwesomeProject --tests false --docker --swagger

    The output of running that command is below:

2. To create a new solution additionally with Docker, MongoDB, git init and tests based on NUnit Framework (By default XUnit), but with skips the automatic restore of the project on creating, you can run the following command:

~$ dotnet new cleanarch -n MyAwesomeProject --docker --mongo --git --nunit --no-restore

    or a shorter version of the above command:

~$ dotnet new cleanarch -n MyAwesomeProject -d -m --g -nu --no-restore

How to start the solution?

locally

The API can be started locally within /src/your_project_name.Api directory (by default it will be available under https://localhost:5001) using the following command:

~$ dotnet run

or by running ./scripts/start.sh shell script in the main directory.

Docker

You can also run the API using Docker:

1. Make sure you are in the main directory and run the following command to build your image:

~$ docker build --tag tag_name .

2. Run the following command to start a container based on your new image:

~$ docker run -p 5001:5001 -d --name container_name tag_name

    *to run the container in the background use -d options.

If you want to start the entire infrastructure (MongoDB, Seq, etc. ). The easiest way to run it is by using docker-compose. For this case, navigate to /scripts/compose and execute the following commands:

~$ cd scripts/compose
~$ docker-compose -f infrastructure.yml up -d

The API service can be also started with docker-compose:

~$ cd scripts/compose
~$ docker-compose -f api.yml up -d

    *to run in the background use -d options.

Or just install the entire infrastructure locally on your machine.

Database migration

If you add PostgreSQL to the solution, you need to create a migration. To create an initial database migration execute the migration command in the Package Manager Console inside Visual Studio. In Package Manager Console select your_project_name.Infrastructure project and run the following command:

PM> Add-Migration migration_name

Migration can be run from the CLI, but before that, you must install dotnet-ef tools, by executing the following commands:

~$ dotnet tool install --global dotnet-ef

~$ dotnet restore

     or by running ./scripts/install_dotnet-ef_cli.sh shell script in the main directory.
To create an initial database migration via CLI. Navigate to /src/your_project_name.Infrastructure and run the following command:

~$ dotnet ef migrations add migration_name

     or by running ./scripts/create-migration.sh shell script in the main directory. The script takes the name of the migration as a parameter. If no name is given then it generates a migration called 'Initial' (example: ./scripts/create-migration.sh migration_name). There are also scripts for removal and revert migration available in the scripts directory.

Give a star! ⭐

If you like this project, learned something or you are using it to start your solution, please give it a star. Thanks!

Issues

If you have discovered a bug or having some issues, please let me know by reporting a new issue.

Roadmap

List of features to add:

NOTE: If you have a proposal for a new feature or a change to the existing code, please don't hesitate to report it. All proposals will be considered.