Skip to main content

​
Get Started in Minutes

This guide will help you quickly set up and run the Hybrid DDD Architecture template. You’ll have a working REST API with Swagger documentation running locally.
Prerequisites: Make sure you have .NET 8 SDK installed. Download it here if needed.

​
Quick Setup

1

Clone the repository

Start by cloning the template repository to your local machine:
git clone https://github.com/FedeJG82/HybridArchitecture.NET.git
cd HybridArchitecture.NET/HybridDDDArchitecture
2

Configure database connection

The template supports multiple databases. Choose your preferred option in Template-API/appsettings.json:
{
  "Configurations": {
    "UseDatabase": "sqlserver"
  },
  "ConnectionStrings": {
    "SqlConnection": "Data Source=(localdb)\\MSSQLLocalDB;Initial Catalog=HybridDDDArchitecture;Integrated Security=True;"
  }
}
The UseDatabase setting accepts: "sqlserver", "mysql", "mariadb", or "mongodb"
3

Run database migrations (SQL databases only)

If using SQL Server, MySQL, or MariaDB, create the initial database migration:
dotnet ef migrations add Initial --project Infrastructure/Infrastructure.csproj --startup-project Template-API/Template-API.csproj
The application automatically applies migrations on startup, so you don’t need to run dotnet ef database update manually.
For MongoDB, no migrations are needed. The database and collections are created automatically.
4

Start the API

Build and run the Template-API project:
dotnet run --project Template-API/Template-API.csproj
You should see output similar to:
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
5

Test with Swagger

Open your browser and navigate to:
https://localhost:5001/swagger
You’ll see the Hybrid Architecture Project v1 Swagger UI with the DummyEntity endpoints:
  • GET /api/v1/DummyEntity - Get all entities with pagination
  • GET /api/v1/DummyEntity/{id} - Get entity by ID
  • POST /api/v1/DummyEntity - Create new entity
  • PUT /api/v1/DummyEntity - Update existing entity
  • DELETE /api/v1/DummyEntity/{id} - Delete entity
Try creating your first entity by clicking on the POST endpoint and using this JSON:
{
  "dummyPropertyOne": "Test Value",
  "dummyPropertyTwo": 1
}

​
What You Just Did

Congratulations! You now have:
A running .NET 8 REST API with Swagger documentation
Database configured (SQL Server or MongoDB)
CQRS pattern with command and query bus
Domain entities with FluentValidation
Repository pattern with your chosen database
Exception handling and standardized API responses

​
Exploring the Example Implementation

The template includes a complete DummyEntity implementation to demonstrate all patterns:

​
Domain Entity

Location: Domain/Entities/DummyEntity.cs 
public class DummyEntity : DomainEntity<string, DummyEntityValidator>
{
    public string DummyPropertyOne { get; private set; }
    public DummyValues DummyPropertyTwo { get; private set; }

    public DummyEntity(string dummyPropertyOne, DummyValues dummyPropertyTwo)
    {
        Id = Guid.NewGuid().ToString();
        SetdummyPropertyOne(dummyPropertyOne);
        DummyPropertyTwo = dummyPropertyTwo;
    }

    public void SetdummyPropertyOne(string value)
    {
        DummyPropertyOne = value ?? throw new ArgumentNullException(nameof(value));
    }
}

​
Command Example

Location: Application/UseCases/DummyEntity/Commands/CreateDummyEntity/CreateDummyEntityCommand.cs 
public class CreateDummyEntityCommand : IRequestCommand<string>
{
    [Required]
    public string dummyPropertyOne { get; set; }
    public DummyValues dummyPropertyTwo { get; set; }
}

​
Controller Example

Location: Template-API/Controllers/DummyEntityController.cs 
[ApiController]
public class DummyEntityController(ICommandQueryBus commandQueryBus) : BaseController
{
    private readonly ICommandQueryBus _commandQueryBus = commandQueryBus;

    [HttpPost("api/v1/[Controller]")]
    public async Task<IActionResult> Create(CreateDummyEntityCommand command)
    {
        if (command is null) return BadRequest();
        var id = await _commandQueryBus.Send(command);
        return Created($"api/[Controller]/{id}", new { Id = id });
    }
}

​
Next Steps

Now that you have the template running, here’s what to explore next:

Architecture Overview

Understand the layers and design patterns

Creating Entities

Add your first domain entity

Database Setup

Configure different database providers

Event Bus

Set up RabbitMQ for event-driven communication
Security Note: The default appsettings.json includes example connection strings. Make sure to update these with your actual credentials and never commit sensitive data to version control. Use user secrets or environment variables for production.

​
Troubleshooting

If using LocalDB and getting connection errors:
  1. Verify SQL Server LocalDB is installed: sqllocaldb info
  2. Start LocalDB if needed: sqllocaldb start MSSQLLocalDB
  3. Check the connection string in appsettings.json
For other SQL providers, ensure the server is running and credentials are correct.
If Entity Framework migrations fail:
  1. Ensure you’re in the solution directory
  2. Check that the --project and --startup-project paths are correct
  3. Verify the database connection string is valid
  4. Delete the Migrations folder and try creating a new migration
If ports 5000 or 5001 are already in use, you can change them in Template-API/Properties/launchSettings.json or run with a custom URL:
dotnet run --project Template-API/Template-API.csproj --urls "https://localhost:7001;http://localhost:7000"
Swagger is only enabled in Development mode. Ensure the ASPNETCORE_ENVIRONMENT is set to Development:
export ASPNETCORE_ENVIRONMENT=Development  # Linux/macOS
set ASPNETCORE_ENVIRONMENT=Development     # Windows CMD
$env:ASPNETCORE_ENVIRONMENT="Development"  # PowerShell

​
Getting Help

Community Support

Found a bug or have questions? Open an issue on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us