🚀 .NET Boilerplate Project

A production-ready .NET 10 boilerplate project following Clean Architecture principles with MongoDB (Azure Cosmos DB) integration.

📋 Table of Contents

Architecture
Project Structure
Technology Stack
Getting Started
Design Patterns
Code Conventions
MongoDB Integration
Configuration
API Design
Testing
Deployment
Useful Commands

🏗️ Architecture

Clean Architecture (4 Layers)

Boilerplate/
├── API/              # Presentation Layer
├── Application/      # Application Layer (Use Cases)
├── Domain/           # Domain Layer (Business Logic)
└── Infra/            # Infrastructure Layer (External Services)

Dependency Flow: API → Application → Domain ← Infra

Key Principles:

✅ Domain is independent (no external dependencies)
✅ Application contains business use cases (CQRS with MediatR)
✅ Infrastructure implements interfaces from Domain
✅ API is thin (controllers delegate to Application layer)

📁 Project Structure

API (Presentation Layer)

API/
├── Controllers/
│   ├── BaseController.cs           # Base controller with TryExecuteAsync pattern
│   └── SampleController.cs          # CRUD endpoints
├── DTOs/
│   ├── Request/
│   │   ├── CreateSampleRequestDto.cs # No Id (generated by DB)
│   │   ├── GetSampleRequestDto.cs    # With string Id
│   │   ├── UpdateSampleRequestDto.cs # With string Id
│   │   └── Validators/              # FluentValidation validators
│   └── Response/
│       ├── BaseResponseDto.cs       # Generic response wrapper
│       └── *ResponseDto.cs          # Specific response DTOs
├── Exceptions/
│   ├── BadRequestException.cs
│   ├── DuplicateException.cs
│   └── FormValidationException.cs
└── appsettings.json                # Configuration (secrets in User Secrets)

Application (Use Cases)

Application/
├── Commands/
│   ├── CreateSampleCommand.cs
│   ├── CreateSampleCommandHandler.cs
│   ├── UpdateSampleCommand.cs
│   └── UpdateSampleCommandHandler.cs
├── Queries/
│   ├── SampleQuery.cs
│   └── SampleQueryHandler.cs
└── Clients/
    └── ISampleClient.cs             # Interface for external APIs

Domain (Business Logic)

Domain/
├── Models/
│   └── Sample.cs                    # Domain model (string Id for MongoDB)
├── Entities/
│   ├── BaseEntity.cs                # MongoDB base (Id, CreatedAt, UpdatedAt)
│   └── SampleEntity.cs              # MongoDB-specific entity
├── Repositories/
│   └── ISampleRepository.cs         # Repository interface
├── MappingConfiguration/
│   ├── SampleToSampleDto.cs         # Mapster mappings
│   └── SampleEntityMapping.cs       # Entity ↔ Model mapping
└── Enums/
    └── ErrorType.cs

Infra (Infrastructure)

Infra/
├── Repositories/
│   └── SampleRepository.cs          # MongoDB implementation
├── Clients/
│   └── SampleClient.cs              # External API client
├── Settings/
│   ├── MongoDbSettings.cs
│   └── SampleConfiguration.cs
├── Extensions/
│   ├── UrlExtensions.cs
│   └── JsonExtension.cs
└── Infrastructure.cs                # DI registration

🛠️ Technology Stack

Component	Technology	Version
Framework	.NET	10
Language	C#	14.0
Database	Azure Cosmos DB	MongoDB API
Driver	MongoDB.Driver	Latest
Mediator	MediatR	Latest
Mapping	Mapster	Latest
Validation	FluentValidation	Latest
Logging	Serilog	Latest
Testing	xUnit + Moq	Latest

🚀 Getting Started

Prerequisites

.NET 10 SDK
Azure Cosmos DB account (MongoDB API) or local MongoDB
Visual Studio 2022 / VS Code / Rider

Installation

1. Clone the repository

git clone https://github.com/throwExceptions/thenorsound.git
cd thenorsound/Boilerplate

2. Install packages

dotnet restore

3. Set up User Secrets (for local development)

cd API
dotnet user-secrets init
dotnet user-secrets set "MongoDbSettings:ConnectionString" "mongodb+srv://user:password@..."
dotnet user-secrets set "MongoDbSettings:DatabaseName" "boilerplate-mongodb"
dotnet user-secrets set "MongoDbSettings:SampleCollectionName" "Samples"

4. Run the application

dotnet run --project API

5. Open Swagger UI

https://localhost:5001

🎯 Design Patterns & Principles

1. CQRS (Command Query Responsibility Segregation)

Commands (Write operations):

CreateSampleCommand → CreateSampleCommandHandler
UpdateSampleCommand → UpdateSampleCommandHandler

Queries (Read operations):

SampleQuery → SampleQueryHandler

2. Repository Pattern

Domain defines ISampleRepository interface
Infrastructure implements SampleRepository with MongoDB logic
Application uses repository through DI

3. Dependency Injection

Using Primary Constructors (C# 12+):

public class SampleController(IMediator mediator, ILogger logger)
{
    public async Task<IActionResult> Create(CreateSampleRequestDto request)
    {
        var command = new CreateSampleCommand(request);
        var result = await mediator.Send(command);
        return Ok(result);
    }
}

📐 Code Conventions

C# Language Features

// ✅ Primary Constructors
public class SampleController(IMediator mediator, ILogger logger)

// ✅ File-scoped namespaces
namespace API.Controllers;

// ✅ Expression-bodied members
public DateTime? UpdatedAt { get => _updatedAt; set => _updatedAt = value; }

// ✅ Using statements inside namespace (StyleCop SA1200)
namespace API.Controllers;
using System;
using MediatR;

Naming Conventions

Type	Convention	Example
Classes	PascalCase	`SampleController`
Interfaces	IPascalCase	`ISampleRepository`
Methods	PascalCase	`GetByIdAsync`
Properties	PascalCase	`ConnectionString`
Private fields	_camelCase	`_samples`
Parameters	camelCase	`request`
Async methods	SuffixAsync	`CreateAsync`

StyleCop Rules

File Header (SA1633): Include license headers in all source files

// Copyright (c) ThenorSound. All rights reserved.
// Licensed under the MIT License.
namespace API.Controllers;

🗄️ MongoDB Integration

BaseEntity Pattern

public abstract class BaseEntity
{
    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; }

    [BsonElement("createdAt")]
    public DateTime CreatedAt { get; set; }

    [BsonElement("updatedAt")]
    public DateTime? UpdatedAt { get; set; }
}

MongoDB ObjectId

Type: string
Format: 24 hexadecimal characters (e.g., 507f1f77bcf86cd799439011)
Validation: .Length(24).Matches("^[a-f0-9]{24}$")

Important Rules:

CreatedAt is set automatically when entity is first saved (lazy getter)
UpdatedAt is set explicitly in Repository's UpdateAsync method
ObjectId is always a string in this architecture

🔐 Configuration & Secrets

Local Development: User Secrets

Never commit secrets to Git!

cd API
dotnet user-secrets init
dotnet user-secrets set "MongoDbSettings:ConnectionString" "mongodb+srv://user:password@..."
dotnet user-secrets set "MongoDbSettings:DatabaseName" "boilerplate-mongodb"
dotnet user-secrets set "MongoDbSettings:SampleCollectionName" "Samples"

Azure Deployment: Environment Variables

In Azure App Service → Configuration → Application settings:

MongoDbSettings__ConnectionString = mongodb+srv://...
MongoDbSettings__DatabaseName = boilerplate-mongodb
MongoDbSettings__SampleCollectionName = Samples

⚠️ Note: Use double underscore __ instead of colon : for nested config.

Configuration Priority

User Secrets (highest - local development)
Environment Variables (Azure)
appsettings.json (lowest - defaults)

🎨 API Design

DTO Design Rules

DTO Type	Id Field	Usage
CreateRequestDto	❌ No Id	Create new resource
GetRequestDto	✅ string Id	Retrieve resource
UpdateRequestDto	✅ string Id	Update resource
ResponseDto	✅ string Id	Return data

🧪 Testing

Unit Tests with xUnit

public class SampleControllerTests
{
    [Fact]
    public async Task Create_WithValidRequest_ReturnsOk()
    {
        // Arrange
        var mediatorMock = new Mock<IMediator>();
        var controller = new SampleController(mediatorMock.Object, Mock.Of<ILogger>());
        var request = new CreateSampleRequestDto { Name = "Test" };

        // Act
        var result = await controller.Create(request);

        // Assert
        Assert.IsType<OkObjectResult>(result);
    }
}

🚀 Deployment

Azure Cosmos DB Setup

1. Create Cosmos DB Account

API: MongoDB
Tier: Free tier (for development)
Location: North Europe

2. Database & Collection

Database: boilerplate-mongodb (auto-created on first write)
Collection: Samples (auto-created on first write)

3. Networking

Enable Public Access
Add your IP address
Allow Azure services

4. Get Connection String

Cosmos DB → Connection strings
Copy "Self (always this cluster)" connection string

Azure App Service Deployment

1. Create App Service

az webapp create \
  --resource-group rg-boilerplate \
  --plan boilerplate-plan \
  --name boilerplate-api \
  --runtime "DOTNET|10.0"

2. Configure Environment Variables

az webapp config appsettings set \
  --name boilerplate-api \
  --resource-group rg-boilerplate \
  --settings \
  MongoDbSettings__ConnectionString="mongodb+srv://..." \
  MongoDbSettings__DatabaseName="boilerplate-mongodb" \
  MongoDbSettings__SampleCollectionName="Samples"

3. Deploy

dotnet publish -c Release
az webapp deploy \
  --resource-group rg-boilerplate \
  --name boilerplate-api \
  --src-path ./bin/Release/net10.0/publish.zip

📝 Useful Commands

Build

dotnet build

Run

dotnet run --project API

Test

dotnet test

Watch mode (auto-rebuild on changes)

dotnet watch --project API

User Secrets

dotnet user-secrets init --project API
dotnet user-secrets set "Key" "Value" --project API
dotnet user-secrets list --project API
dotnet user-secrets clear --project API

Add NuGet Package

dotnet add [Project] package [PackageName]

Update packages

dotnet list package --outdated
dotnet add package [PackageName]

📚 Project Dependencies

API

Microsoft.AspNetCore.OpenApi
Swashbuckle.AspNetCore
FluentValidation
Serilog.AspNetCore
Serilog.Sinks.Console
Serilog.Sinks.File

Application

MediatR
Mapster

Domain

MongoDB.Bson
Mapster

Infra

MongoDB.Driver
Mapster
MapsterMapper

🔧 Infrastructure Setup

MongoDB Registration (Infrastructure.cs)

public static IServiceCollection AddInfrastructure(
    this IServiceCollection services,
    IConfiguration configuration)
{
    services.Configure<MongoDbSettings>(
        configuration.GetSection(nameof(MongoDbSettings)));

    services.AddSingleton<IMongoClient>(
        new MongoClient(configuration["MongoDbSettings:ConnectionString"]));

    services.AddScoped<ISampleRepository, SampleRepository>();
    services.AddScoped<ISampleClient, SampleClient>();

    return services;
}

Mapster Registration

public static IServiceCollection AddMappings(this IServiceCollection services)
{
    TypeAdapterConfig.GlobalSettings
        .Scan(typeof(SampleToSampleDto).Assembly);

    services.AddScoped<IMapper, ServiceMapper>();

    return services;
}

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Follow StyleCop rules (SA*)
All public members must have XML documentation
Use primary constructors where possible
Prefer this. prefix for all class members
Use file-scoped namespaces
Use expression-bodied members when appropriate

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Clean Architecture by Robert C. Martin
MediatR for CQRS implementation
Mapster for high-performance object mapping
FluentValidation for validation rules
MongoDB.Driver for database access
Serilog for structured logging

📞 Contact

Project Link: https://github.com/throwExceptions/thenorsound

🎓 Key Takeaways

For New Developers on this Project:

Architecture: Follow Clean Architecture - Domain is the core, never reference infrastructure
IDs: Always use string for MongoDB ObjectIds (24 hex characters)
Timestamps: CreatedAt uses lazy getter, UpdatedAt is set explicitly in Repository
DTOs: Create requests don't have Id, Get/Update requests do
Secrets: Use User Secrets locally, Environment Variables in Azure
Mapping: Use Mapster with .Ignore() for auto-managed properties
Validation: FluentValidation for all request DTOs
Testing: xUnit + Moq for unit tests
Conventions: Follow StyleCop rules, use primary constructors

Built with ❤️ using .NET 10 and Clean Architecture

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
API.Test		API.Test
API		API
Application		Application
Domain		Domain
Infra.Test		Infra.Test
Infra		Infra
.editorconfig		.editorconfig
.gitignore		.gitignore
Boilerplate.slnx		Boilerplate.slnx
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation