Installation & Setup - Hybrid DDD Architecture .NET

System Requirements

Before installing the template, ensure your development environment meets these requirements:

Required

.NET 8 SDK - The template targets .NET 8
Git - For cloning the repository
Code Editor - Visual Studio 2022, VS Code, or JetBrains Rider

Optional (Database)

Choose at least one database provider:

SQL Server - LocalDB, Express, or full edition
MySQL - Version 8.0 or higher
MariaDB - Version 10.5 or higher
MongoDB - Version 4.4 or higher

Optional (Event Bus)

RabbitMQ - For event-driven architecture and microservices communication

Installing .NET 8 SDK

Windows
macOS
Linux

Download the .NET 8 SDK installer from dotnet.microsoft.com
Run the installer and follow the prompts
Verify installation:

dotnet --version
# Should output: 8.0.x

Using Homebrew:

brew install dotnet@8
dotnet --version

Or download the installer from dotnet.microsoft.com

Ubuntu/Debian:

wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y dotnet-sdk-8.0
dotnet --version

For other distributions, see the official documentation.

Database Setup

Choose and configure your preferred database provider:

SQL Server

LocalDB (Windows)
SQL Server (Full)
Docker

LocalDB comes with Visual Studio or can be installed separately:

# Verify LocalDB is installed
sqllocaldb info

# Start LocalDB instance
sqllocaldb start MSSQLLocalDB

# Create database (optional - EF will create it)
sqllocaldb create MSSQLLocalDB

Connection string for appsettings.json:

"SqlConnection": "Data Source=(localdb)\\MSSQLLocalDB;Initial Catalog=HybridDDDArchitecture;Integrated Security=True;"

For SQL Server Express or full edition:

"SqlConnection": "Server=localhost;Database=HybridDDDArchitecture;User Id=sa;Password=YourStrong@Password;"

Use strong passwords and never commit credentials to source control. Use user secrets or environment variables.

Run SQL Server in Docker:

docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=YourStrong@Password" \
  -p 1433:1433 --name sqlserver \
  -d mcr.microsoft.com/mssql/server:2022-latest

Connection string:

"SqlConnection": "Server=localhost,1433;Database=HybridDDDArchitecture;User Id=sa;Password=YourStrong@Password;TrustServerCertificate=True;"

MySQL/MariaDB

MySQL
MariaDB
Docker

Install MySQL 8.0+ and configure:

{
  "Configurations": {
    "UseDatabase": "mysql"
  },
  "ConnectionStrings": {
    "SqlConnection": "Server=localhost;Database=HybridDDDArchitecture;User=root;Password=yourpassword;"
  }
}

Install MariaDB 10.5+ and configure:

{
  "Configurations": {
    "UseDatabase": "mariadb"
  },
  "ConnectionStrings": {
    "SqlConnection": "Server=localhost;Database=HybridDDDArchitecture;User=root;Password=yourpassword;"
  }
}

Run MySQL in Docker:

docker run --name mysql -e MYSQL_ROOT_PASSWORD=yourpassword \
  -e MYSQL_DATABASE=HybridDDDArchitecture \
  -p 3306:3306 -d mysql:8.0

MongoDB

Local Installation
Docker
MongoDB Atlas

Install MongoDB Community Edition and configure:

{
  "Configurations": {
    "UseDatabase": "mongodb"
  },
  "ConnectionStrings": {
    "MongoConnection": "mongodb://localhost:27017/HybridDDDArchitecture"
  }
}

Run MongoDB in Docker:

docker run --name mongodb -p 27017:27017 -d mongo:latest

Connection string:

"MongoConnection": "mongodb://localhost:27017/HybridDDDArchitecture"

For cloud-hosted MongoDB:

"MongoConnection": "mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/HybridDDDArchitecture?retryWrites=true&w=majority"

RabbitMQ Setup (Optional)

For event-driven architecture with the event bus:

Docker
CloudAMQP
Local Installation

Easiest way to run RabbitMQ locally:

docker run -d --name rabbitmq \
  -p 5672:5672 -p 15672:15672 \
  rabbitmq:3-management

Access management UI at http://localhost:15672 (guest/guest)Connection string for appsettings.json:

"RabbitMqEventBus": {
  "Connectionstring": "amqp://guest:guest@localhost:5672/"
}

For cloud-hosted RabbitMQ, use CloudAMQP:

"RabbitMqEventBus": {
  "Connectionstring": "amqps://username:password@your-host.cloudamqp.com/vhost"
}

Project Installation

Step 1: Clone the Repository

git clone https://github.com/FedeJG82/HybridArchitecture.NET.git
cd HybridArchitecture.NET/HybridDDDArchitecture

Step 2: Restore Dependencies

dotnet restore

This will restore all NuGet packages for the solution.

Step 3: Configure Settings

Edit Template-API/appsettings.json with your database and event bus settings:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Configurations": {
    "UseDatabase": "sqlserver"  // Options: "mongodb", "mysql", "sqlserver", "mariadb"
  },
  "ConnectionStrings": {
    "MongoConnection": "mongodb://localhost:27017/HybridDDDArchitecture",
    "SqlConnection": "Data Source=(localdb)\\MSSQLLocalDB;Initial Catalog=HybridDDDArchitecture;Integrated Security=True;"
  },
  "RabbitMqEventBus": {
    "Connectionstring": "amqp://guest:guest@localhost:5672/"
  }
}

The UseDatabase configuration is read by the DatabaseFactory which selects the appropriate repository implementation at runtime.

Step 4: Create Database Migration (SQL Only)

If using SQL Server, MySQL, or MariaDB:

dotnet ef migrations add Initial \
  --project Infrastructure/Infrastructure.csproj \
  --startup-project Template-API/Template-API.csproj

This creates the migration files in the Infrastructure project.

Migrations are automatically applied on application startup thanks to this code in Infrastructure/Factories/DatabaseFactory.cs:39-40:

var context = services.BuildServiceProvider().GetRequiredService<Repositories.Sql.StoreDbContext>();
context.Database.Migrate();

Step 5: Build the Solution

dotnet build

Verify that all 13 projects compile successfully.

Step 6: Run the Application

dotnet run --project Template-API/Template-API.csproj

Or open the solution in Visual Studio and press F5.

Project Structure

Understanding the solution organization:

HybridDDDArchitecture/
├── Core/                                    # Reusable infrastructure
│   ├── Core.Domain/                        # Base domain entity classes
│   ├── Core.Application.ComandQueryBus/    # CQRS bus with MediatR
│   ├── Core.Application.EventBus/          # Event bus abstractions
│   ├── Core.Application.Repositories/       # Repository interfaces
│   ├── Core.Application.Adapters.Http/     # HTTP adapter abstractions
│   ├── Core.Application.Mapping/           # AutoMapper configuration
│   ├── Core.Infraestructure.Repositories.Sql/      # SQL implementations
│   ├── Core.Infraestructure.Repositories.MongoDb/  # MongoDB implementations
│   ├── Core.Infraestructure.EventBus.RabbitMq/     # RabbitMQ implementation
│   └── Core.Infraestructure.Adapters.Http/         # HTTP client implementation
│
├── Layers/                                  # Business-specific code
│   ├── Domain/                             # Business entities, validators
│   │   ├── Entities/                       # Domain entities (DummyEntity)
│   │   ├── Enums/                          # Domain enumerations
│   │   ├── Constants/                      # Domain constants
│   │   └── Validators/                     # FluentValidation validators
│   │
│   ├── Application/                        # Use cases and application logic
│   │   ├── UseCases/                       # Commands and queries
│   │   ├── ApplicationServices/            # Application services
│   │   ├── DataTransferObjects/            # DTOs
│   │   ├── DomainEvents/                   # Domain event handlers
│   │   ├── Integrations/                   # Integration events
│   │   ├── Mappings/                       # AutoMapper profiles
│   │   └── Repositories/                   # Repository interfaces
│   │
│   ├── Infrastructure/                     # Infrastructure implementations
│   │   ├── Repositories/                   # Repository implementations
│   │   │   ├── Sql/                        # SQL repositories
│   │   │   └── Mongo/                      # MongoDB repositories
│   │   ├── Factories/                      # Database factory
│   │   └── Registrations/                  # DI registrations
│   │
│   └── Template-API/                       # Web API layer
│       ├── Controllers/                    # API controllers
│       ├── Filters/                        # Exception filters
│       ├── Program.cs                      # Application entry point
│       ├── Startup.cs                      # Service configuration
│       └── appsettings.json                # Configuration
│
└── HybridDDDArchitecture.sln               # Solution file

Configuration Options

Key configuration sections in appsettings.json:

Database Configuration

"Configurations": {
  "UseDatabase": "sqlserver"  // Determines which repository implementation to use
}

Valid values:

"sqlserver" - Uses Entity Framework Core with SQL Server
"mysql" - Uses Entity Framework Core with MySQL
"mariadb" - Uses Entity Framework Core with MariaDB
"mongodb" - Uses MongoDB driver

Implementation location: Infrastructure/Factories/DatabaseFactory.cs:14-29

Connection Strings

"ConnectionStrings": {
  "SqlConnection": "[Your SQL connection string]",      // For SQL databases
  "MongoConnection": "[Your MongoDB connection string]"  // For MongoDB
}

Event Bus Configuration

"RabbitMqEventBus": {
  "Connectionstring": "[Your RabbitMQ connection string]"
}

Logging Configuration

"Logging": {
  "LogLevel": {
    "Default": "Information",           // General logging level
    "Microsoft.AspNetCore": "Warning"   // ASP.NET Core logging level
  }
}

Development Environment Setup

Visual Studio 2022

Open HybridDDDArchitecture.sln
Set Template-API as the startup project
Press F5 to run with debugging

Visual Studio Code

Install the C# extension
Open the folder containing HybridDDDArchitecture.sln
Run: dotnet run --project Template-API/Template-API.csproj

JetBrains Rider

Open HybridDDDArchitecture.sln
Configure run configuration for Template-API
Run or debug

User Secrets (Recommended)

For sensitive configuration, use .NET User Secrets instead of appsettings.json:

cd Template-API
dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:SqlConnection" "Server=localhost;Database=HybridDDD;User=sa;Password=YourPassword;"
dotnet user-secrets set "RabbitMqEventBus:Connectionstring" "amqp://user:password@localhost:5672/"

Never commit passwords, API keys, or connection strings to source control. Use user secrets for development and secure configuration providers for production.

Docker Setup (Optional)

The template includes Docker support:

Build Docker Image

docker build -t hybrid-ddd-api -f Template-API/Dockerfile .

Run Container

docker run -p 8080:80 \
  -e ConnectionStrings__SqlConnection="Server=host.docker.internal;Database=HybridDDD;User=sa;Password=YourPassword;" \
  hybrid-ddd-api

Use host.docker.internal to access services running on your host machine from within Docker.

Verifying Installation

After setup, verify everything works:

Build succeeds

dotnet build
# Should complete with 0 errors

Application starts

dotnet run --project Template-API/Template-API.csproj
# Should show "Now listening on: https://localhost:5001"

Swagger loads

Open https://localhost:5001/swagger in your browserShould display the Swagger UI with DummyEntity endpoints

Database is created

Check that the database exists:

SQL: Use SSMS or Azure Data Studio
MongoDB: Use MongoDB Compass or mongosh

The database should contain the entities defined in your DbContext

API responds

Test the GET endpoint:

curl -k https://localhost:5001/api/v1/DummyEntity?pageIndex=1&pageSize=10

Should return a paginated response (may be empty initially)

Next Steps

Quickstart

Follow the quickstart guide to test the API

Architecture Overview

Learn about the architectural patterns

Creating Entities

Create your first domain entity

Database Setup

Advanced database configuration

Get Started

Architecture

Core Modules

Guides

​System Requirements

​Required

​Optional (Database)

​Optional (Event Bus)

​Installing .NET 8 SDK

​Database Setup

​SQL Server

​MySQL/MariaDB

​MongoDB

​RabbitMQ Setup (Optional)

​Project Installation

​Step 1: Clone the Repository

​Step 2: Restore Dependencies

​Step 3: Configure Settings

​Step 4: Create Database Migration (SQL Only)

​Step 5: Build the Solution

​Step 6: Run the Application

​Project Structure

​Configuration Options

​Database Configuration

​Connection Strings

​Event Bus Configuration

​Logging Configuration

​Development Environment Setup

​Visual Studio 2022

​Visual Studio Code

​JetBrains Rider

​User Secrets (Recommended)

​Docker Setup (Optional)

​Build Docker Image

​Run Container

​Verifying Installation

​Next Steps

Quickstart

Architecture Overview

Creating Entities

Database Setup

Build docs developers (and LLMs) love

System Requirements

Required

Optional (Database)

Optional (Event Bus)

Installing .NET 8 SDK

Database Setup

SQL Server

MySQL/MariaDB

MongoDB

RabbitMQ Setup (Optional)

Project Installation

Step 1: Clone the Repository

Step 2: Restore Dependencies

Step 3: Configure Settings

Step 4: Create Database Migration (SQL Only)

Step 5: Build the Solution

Step 6: Run the Application

Project Structure

Configuration Options

Database Configuration

Connection Strings

Event Bus Configuration

Logging Configuration

Development Environment Setup

Visual Studio 2022

Visual Studio Code

JetBrains Rider

User Secrets (Recommended)

Docker Setup (Optional)

Build Docker Image

Run Container

Verifying Installation

Next Steps