README.md
· 758 B · Markdown
Surowy
## How to use
### 🍎 Linux / macOS
Run the following command in your terminal. Replace `MyProjectName` with your desired solution name.
```bash
# Syntax: curl [url] | bash -s -- [ProjectName]
curl -fsSL https://opengist.rmrf.online/weehong/7548f80484b4419b9ba93ca45e784638/raw/HEAD/scaffold.sh | bash -s -- MyCleanApp
bash -c "$(curl -fsSL https://opengist.rmrf.online/weehong/7548f80484b4419b9ba93ca45e784638/raw/HEAD/scaffold_project.sh)"
```
### 🪟 Windows (PowerShell)
Run this command to scaffold the solution.
```powershell
# Syntax: irm [url] | % { & ([scriptblock]::Create($_)) [ProjectName] }
irm "https://opengist.rmrf.online/weehong/7548f80484b4419b9ba93ca45e784638/raw/HEAD/scaffold.ps1" | % { & ([scriptblock]::Create($_)) Tidverse }
```
How to use
🍎 Linux / macOS
Run the following command in your terminal. Replace MyProjectName with your desired solution name.
# Syntax: curl [url] | bash -s -- [ProjectName]
curl -fsSL https://opengist.rmrf.online/weehong/7548f80484b4419b9ba93ca45e784638/raw/HEAD/scaffold.sh | bash -s -- MyCleanApp
bash -c "$(curl -fsSL https://opengist.rmrf.online/weehong/7548f80484b4419b9ba93ca45e784638/raw/HEAD/scaffold_project.sh)"
🪟 Windows (PowerShell)
Run this command to scaffold the solution.
# Syntax: irm [url] | % { & ([scriptblock]::Create($_)) [ProjectName] }
irm "https://opengist.rmrf.online/weehong/7548f80484b4419b9ba93ca45e784638/raw/HEAD/scaffold.ps1" | % { & ([scriptblock]::Create($_)) Tidverse }
dotnet-10-clean-architecture-boilerplate-guide.md
· 49 KiB · Markdown
Surowy
# The Ultimate .NET 10 Clean Architecture Boilerplate: Step-by-Step Implementation Guide
This guide is an exhaustive, detail-oriented manual for recreating a .NET 10 Clean Architecture and CQRS boilerplate from scratch. It documents every file in the repository in strict chronological order—you will build the core first, and layer dependencies outward, so you never have to reference a file that doesn't exist yet.
## Table of Contents
1. [Architecture Overview](#1-architecture-overview)
2. [Prerequisites & Environment Setup](#2-prerequisites--environment-setup)
3. [Solution & Project Scaffolding](#3-solution--project-scaffolding)
4. [Root Configuration Files](#4-root-configuration-files)
5. [Layer 1: Domain](#5-layer-1-domain)
6. [Layer 2: Application](#6-layer-2-application)
7. [Layer 3: Infrastructure](#7-layer-3-infrastructure)
8. [Layer 4: API / Presentation](#8-layer-4-api--presentation)
9. [Docker & Dev Environment](#9-docker--dev-environment)
10. [Test Projects](#10-test-projects)
11. [CI/CD Pipeline](#11-cicd-pipeline)
12. [AI-Assisted Development](#12-ai-assisted-development)
13. [Running the Project](#13-running-the-project)
14. [Appendix A: Outbox Pattern (Optional)](#appendix-a-outbox-pattern-optional)
---
## 1. Architecture Overview
Clean Architecture organises code into concentric layers where dependencies **always point inward**.
- **Domain** references nothing.
- **Application** references Domain only.
- **Infrastructure** references Application (and transitively, Domain).
- **API** references Application and Infrastructure.
This guarantees the Domain and Application layers are fully testable without a database, web server, or framework.
---
## 2. Prerequisites & Environment Setup
Ensure you have the **.NET 10 SDK**, **Docker**, and your preferred IDE installed.
To make this guide copy-paste friendly, open your terminal and set your project variables. We use two variables: one for C# PascalCase naming, and one for lowercase systems (Docker/PostgreSQL).
```bash
export PROJECT="Inventory"
export PROJECT_LOWER="inventory"
```
---
## 3. Solution & Project Scaffolding
Create the root directory and initialize the solution and projects using your variables:
```bash
mkdir ${PROJECT_LOWER}-api
cd ${PROJECT_LOWER}-api
# Create the solution (slnx = lightweight XML format)
dotnet new slnx -n ${PROJECT}
# Create the source projects
dotnet new webapi -n ${PROJECT}.Api -o src/${PROJECT}.Api
dotnet new classlib -n ${PROJECT}.Application -o src/${PROJECT}.Application
dotnet new classlib -n ${PROJECT}.Domain -o src/${PROJECT}.Domain
dotnet new classlib -n ${PROJECT}.Infrastructure -o src/${PROJECT}.Infrastructure
# Create the test projects
dotnet new xunit -n ${PROJECT}.Application.Tests -o tests/${PROJECT}.Application.Tests
dotnet new xunit -n ${PROJECT}.Domain.Tests -o tests/${PROJECT}.Domain.Tests
dotnet new xunit -n ${PROJECT}.IntegrationTests -o tests/${PROJECT}.IntegrationTests
# Add source projects to the solution
dotnet sln ${PROJECT}.slnx add src/${PROJECT}.Api/${PROJECT}.Api.csproj --solution-folder src
dotnet sln ${PROJECT}.slnx add src/${PROJECT}.Application/${PROJECT}.Application.csproj --solution-folder src
dotnet sln ${PROJECT}.slnx add src/${PROJECT}.Domain/${PROJECT}.Domain.csproj --solution-folder src
dotnet sln ${PROJECT}.slnx add src/${PROJECT}.Infrastructure/${PROJECT}.Infrastructure.csproj --solution-folder src
# Add test projects to the solution
dotnet sln ${PROJECT}.slnx add tests/${PROJECT}.Application.Tests/${PROJECT}.Application.Tests.csproj --solution-folder tests
dotnet sln ${PROJECT}.slnx add tests/${PROJECT}.Domain.Tests/${PROJECT}.Domain.Tests.csproj --solution-folder tests
dotnet sln ${PROJECT}.slnx add tests/${PROJECT}.IntegrationTests/${PROJECT}.IntegrationTests.csproj --solution-folder tests
# Configure Clean Architecture Dependencies
dotnet add src/${PROJECT}.Application/${PROJECT}.Application.csproj reference src/${PROJECT}.Domain/${PROJECT}.Domain.csproj
dotnet add src/${PROJECT}.Infrastructure/${PROJECT}.Infrastructure.csproj reference src/${PROJECT}.Application/${PROJECT}.Application.csproj
dotnet add src/${PROJECT}.Api/${PROJECT}.Api.csproj reference src/${PROJECT}.Application/${PROJECT}.Application.csproj
dotnet add src/${PROJECT}.Api/${PROJECT}.Api.csproj reference src/${PROJECT}.Infrastructure/${PROJECT}.Infrastructure.csproj
```
---
## 4. Root Configuration Files
These files lock SDK versions and manage NuGet packages centrally. Create them at the repository root.
### `global.json`
```json
{
"sdk": {
"rollForward": "latestFeature",
"version": "10.0.103"
}
}
```
### `Directory.Build.props`
```xml
<Project>
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
</Project>
```
### `Directory.Packages.props`
```xml
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="Asp.Versioning.Mvc" Version="10.0.0-preview.2"/>
<PackageVersion Include="Asp.Versioning.Mvc.ApiExplorer" Version="10.0.0-preview.2"/>
<PackageVersion Include="AspNetCore.HealthChecks.NpgSql" Version="9.0.0"/>
<PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.5"/>
<PackageVersion Include="Serilog.AspNetCore" Version="10.0.0"/>
<PackageVersion Include="Serilog.Enrichers.Environment" Version="3.0.1"/>
<PackageVersion Include="Serilog.Enrichers.Thread" Version="4.0.0"/>
<PackageVersion Include="FluentValidation" Version="12.1.1"/>
<PackageVersion Include="FluentValidation.DependencyInjectionExtensions" Version="12.1.1"/>
<PackageVersion Include="MediatR" Version="14.1.0"/>
<PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.5"/>
<PackageVersion Include="Newtonsoft.Json" Version="13.0.4"/>
<PackageVersion Include="Quartz.Extensions.Hosting" Version="3.16.1"/>
<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="10.0.5"/>
<PackageVersion Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.5"/>
<PackageVersion Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.5"/>
<PackageVersion Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.1"/>
<PackageVersion Include="coverlet.collector" Version="8.0.0"/>
<PackageVersion Include="FluentAssertions" Version="8.8.0"/>
<PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.5"/>
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.3.0"/>
<PackageVersion Include="Moq" Version="4.20.72"/>
<PackageVersion Include="xunit" Version="2.9.3"/>
<PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5"/>
</ItemGroup>
</Project>
```
### Apply NuGet Packages to Projects
Now that versioning is centralized, add the packages to your projects.
```bash
# Application Layer
dotnet add src/${PROJECT}.Application package MediatR
dotnet add src/${PROJECT}.Application package FluentValidation
dotnet add src/${PROJECT}.Application package FluentValidation.DependencyInjectionExtensions
dotnet add src/${PROJECT}.Application package Microsoft.Extensions.Logging.Abstractions
# Infrastructure Layer
dotnet add src/${PROJECT}.Infrastructure package Microsoft.EntityFrameworkCore
dotnet add src/${PROJECT}.Infrastructure package Microsoft.EntityFrameworkCore.Design
dotnet add src/${PROJECT}.Infrastructure package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add src/${PROJECT}.Infrastructure package Newtonsoft.Json
dotnet add src/${PROJECT}.Infrastructure package Quartz.Extensions.Hosting
# API Layer
dotnet add src/${PROJECT}.Api package Serilog.AspNetCore
dotnet add src/${PROJECT}.Api package Serilog.Enrichers.Environment
dotnet add src/${PROJECT}.Api package Serilog.Enrichers.Thread
dotnet add src/${PROJECT}.Api package AspNetCore.HealthChecks.NpgSql
dotnet add src/${PROJECT}.Api package Microsoft.AspNetCore.OpenApi
dotnet add src/${PROJECT}.Api package Microsoft.EntityFrameworkCore.Tools
dotnet add src/${PROJECT}.Api package Asp.Versioning.Mvc
dotnet add src/${PROJECT}.Api package Asp.Versioning.Mvc.ApiExplorer
# Test Projects (Domain)
dotnet add tests/${PROJECT}.Domain.Tests package Microsoft.NET.Test.Sdk
dotnet add tests/${PROJECT}.Domain.Tests package xunit
dotnet add tests/${PROJECT}.Domain.Tests package xunit.runner.visualstudio
dotnet add tests/${PROJECT}.Domain.Tests package coverlet.collector
dotnet add tests/${PROJECT}.Domain.Tests package FluentAssertions
dotnet add tests/${PROJECT}.Domain.Tests package Moq
# Test Projects (Application)
dotnet add tests/${PROJECT}.Application.Tests package Microsoft.NET.Test.Sdk
dotnet add tests/${PROJECT}.Application.Tests package xunit
dotnet add tests/${PROJECT}.Application.Tests package xunit.runner.visualstudio
dotnet add tests/${PROJECT}.Application.Tests package coverlet.collector
dotnet add tests/${PROJECT}.Application.Tests package FluentAssertions
dotnet add tests/${PROJECT}.Application.Tests package Moq
# Test Projects (Integration)
dotnet add tests/${PROJECT}.IntegrationTests package Microsoft.NET.Test.Sdk
dotnet add tests/${PROJECT}.IntegrationTests package xunit
dotnet add tests/${PROJECT}.IntegrationTests package xunit.runner.visualstudio
dotnet add tests/${PROJECT}.IntegrationTests package coverlet.collector
dotnet add tests/${PROJECT}.IntegrationTests package FluentAssertions
dotnet add tests/${PROJECT}.IntegrationTests package Moq
dotnet add tests/${PROJECT}.IntegrationTests package Microsoft.AspNetCore.Mvc.Testing
```
---
## 5. Layer 1: Domain
*The innermost layer. Contains entities, value objects, domain events, the Result pattern, and repository abstractions. It has **zero** NuGet dependencies.*
### `src/${PROJECT}.Domain/Common/IDomainEvent.cs`
```csharp
namespace ${PROJECT}.Domain.Common;
public interface IDomainEvent
{
DateTime OccurredOn { get; }
}
```
### `src/${PROJECT}.Domain/Common/BaseEntity.cs`
```csharp
namespace ${PROJECT}.Domain.Common;
public abstract class BaseEntity
{
private readonly List<IDomainEvent> _domainEvents = [];
public Guid Id { get; private init; } = Guid.NewGuid();
public IReadOnlyCollection<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();
public void AddDomainEvent(IDomainEvent domainEvent) => _domainEvents.Add(domainEvent);
public void RemoveDomainEvent(IDomainEvent domainEvent) => _domainEvents.Remove(domainEvent);
public void ClearDomainEvents() => _domainEvents.Clear();
}
```
### `src/${PROJECT}.Domain/Common/AuditableEntity.cs`
```csharp
namespace ${PROJECT}.Domain.Common;
public abstract class AuditableEntity : BaseEntity
{
public DateTime CreatedAt { get; private set; }
public DateTime? UpdatedAt { get; private set; }
public void SetCreatedAt(DateTime createdAt) => CreatedAt = createdAt;
public void SetUpdatedAt(DateTime updatedAt) => UpdatedAt = updatedAt;
}
```
### `src/${PROJECT}.Domain/Common/Error.cs`
```csharp
namespace ${PROJECT}.Domain.Common;
public enum ErrorType { None = 0, Failure = 1, Validation = 2, NotFound = 3, Conflict = 4 }
public sealed record Error(string Code, string Description, ErrorType Type)
{
public static readonly Error None = new(string.Empty, string.Empty, ErrorType.None);
public static readonly Error NullValue = new("Error.NullValue", "A null value was provided.", ErrorType.Failure);
public static readonly Error NotFound = new("Error.NotFound", "The requested resource was not found.", ErrorType.NotFound);
public static readonly Error Conflict = new("Error.Conflict", "A conflict occurred with the current state.", ErrorType.Conflict);
public static readonly Error Validation = new("Error.Validation", "A validation error occurred.", ErrorType.Validation);
}
```
### `src/${PROJECT}.Domain/Common/Result.cs`
```csharp
namespace ${PROJECT}.Domain.Common;
public interface IValidationResult
{
static abstract Result Failure(Error error);
}
public class Result : IValidationResult
{
protected Result(bool isSuccess, Error error)
{
if (isSuccess && error != Error.None) throw new InvalidOperationException("A successful result cannot have an error.");
if (!isSuccess && error == Error.None) throw new InvalidOperationException("A failed result must have an error.");
IsSuccess = isSuccess;
Error = error;
}
public bool IsSuccess { get; }
public bool IsFailure => !IsSuccess;
public Error Error { get; }
public static Result Success() => new(true, Error.None);
public static Result<T> Success<T>(T value) => Result<T>.Success(value);
public static Result Failure(Error error) => new(false, error);
public static Result<T> Failure<T>(Error error) => Result<T>.Failure(error);
}
public class Result<T> : Result, IValidationResult
{
private readonly T? _value;
private Result(T? value, bool isSuccess, Error error) : base(isSuccess, error)
{
_value = value;
}
public T Value => IsSuccess ? _value! : throw new InvalidOperationException("Cannot access the value of a failed result.");
public static Result<T> Success(T value) => new(value, true, Error.None);
public new static Result<T> Failure(Error error) => new(default, false, error);
public static implicit operator Result<T>(T value) => Success(value);
}
```
### `src/${PROJECT}.Domain/Abstractions/IUnitOfWork.cs`
```csharp
namespace ${PROJECT}.Domain.Abstractions;
public interface IUnitOfWork
{
Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}
```
---
## 6. Layer 2: Application
*Contains use cases (commands, queries, handlers), validation, mapping, and MediatR pipeline behaviors. References Domain only.*
### `src/${PROJECT}.Application/Abstractions/Messaging/ICommand.cs`
```csharp
using MediatR;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Application.Abstractions.Messaging;
public interface ICommand : IRequest<Result>;
public interface ICommand<TResponse> : IRequest<Result<TResponse>>;
```
### `src/${PROJECT}.Application/Abstractions/Messaging/ICommandHandler.cs`
```csharp
using MediatR;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Application.Abstractions.Messaging;
public interface ICommandHandler<in TCommand> : IRequestHandler<TCommand, Result> where TCommand : ICommand;
public interface ICommandHandler<in TCommand, TResponse> : IRequestHandler<TCommand, Result<TResponse>> where TCommand : ICommand<TResponse>;
```
### `src/${PROJECT}.Application/Abstractions/IDomainEventHandler.cs`
```csharp
using MediatR;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Application.Abstractions;
public sealed class DomainEventNotification<TDomainEvent>(TDomainEvent domainEvent) : INotification where TDomainEvent : IDomainEvent
{
public TDomainEvent DomainEvent { get; } = domainEvent;
}
public interface IDomainEventHandler<TDomainEvent> : INotificationHandler<DomainEventNotification<TDomainEvent>> where TDomainEvent : IDomainEvent;
```
### `src/${PROJECT}.Application/Behaviors/LoggingBehavior.cs`
```csharp
using System.Diagnostics;
using MediatR;
using Microsoft.Extensions.Logging;
namespace ${PROJECT}.Application.Behaviors;
public sealed class LoggingBehavior<TRequest, TResponse>(ILogger<LoggingBehavior<TRequest, TResponse>> logger) : IPipelineBehavior<TRequest, TResponse> where TRequest : IRequest<TResponse>
{
public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
{
var requestName = typeof(TRequest).Name;
logger.LogInformation("Handling {RequestName}", requestName);
var stopwatch = Stopwatch.StartNew();
var response = await next(cancellationToken);
stopwatch.Stop();
logger.LogInformation("Handled {RequestName} in {ElapsedMilliseconds}ms", requestName, stopwatch.ElapsedMilliseconds);
return response;
}
}
```
### `src/${PROJECT}.Application/Behaviors/ValidationBehavior.cs`
```csharp
using FluentValidation;
using MediatR;
using Microsoft.Extensions.Logging;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Application.Behaviors;
public sealed class ValidationBehavior<TRequest, TResponse>(
IEnumerable<IValidator<TRequest>> validators,
ILogger<ValidationBehavior<TRequest, TResponse>> logger)
: IPipelineBehavior<TRequest, TResponse>
where TRequest : IRequest<TResponse>
where TResponse : Result, IValidationResult
{
public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
{
var validatorList = validators as IReadOnlyList<IValidator<TRequest>> ?? [.. validators];
if (validatorList.Count == 0) return await next(cancellationToken);
var context = new ValidationContext<TRequest>(request);
var validationResults = await Task.WhenAll(validatorList.Select(v => v.ValidateAsync(context, cancellationToken)));
var failures = validationResults.SelectMany(r => r.Errors).Where(f => f is not null).ToList();
if (failures.Count != 0)
{
var errorMessage = string.Join("; ", failures.Select(f => f.ErrorMessage));
var error = new Error("Validation", errorMessage, ErrorType.Validation);
logger.LogWarning("Validation failed for {RequestName}: {ErrorMessage}", typeof(TRequest).Name, errorMessage);
// Direct call to static abstract Failure method. No reflection!
return (TResponse)TResponse.Failure(error);
}
return await next(cancellationToken);
}
}
```
### `src/${PROJECT}.Application/DependencyInjection.cs`
```csharp
using FluentValidation;
using MediatR;
using Microsoft.Extensions.DependencyInjection;
using ${PROJECT}.Application.Behaviors;
namespace ${PROJECT}.Application;
public static class DependencyInjection
{
public static IServiceCollection AddApplication(this IServiceCollection services)
{
var assembly = typeof(DependencyInjection).Assembly;
services.AddMediatR(cfg =>
{
cfg.RegisterServicesFromAssembly(assembly);
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
});
services.AddValidatorsFromAssembly(assembly);
return services;
}
}
```
---
## 7. Layer 3: Infrastructure
*Implements the abstractions defined in Domain and Application. Contains the EF Core `DbContext` and interceptors.*
### `src/${PROJECT}.Infrastructure/Persistence/Interceptors/AuditableEntityInterceptor.cs`
```csharp
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Diagnostics;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Infrastructure.Persistence.Interceptors;
public sealed class AuditableEntityInterceptor : SaveChangesInterceptor
{
public override ValueTask<InterceptionResult<int>> SavingChangesAsync(DbContextEventData eventData, InterceptionResult<int> result, CancellationToken cancellationToken = default)
{
UpdateAuditableEntities(eventData.Context);
return base.SavingChangesAsync(eventData, result, cancellationToken);
}
private static void UpdateAuditableEntities(DbContext? context)
{
if (context is null) return;
var utcNow = DateTime.UtcNow;
foreach (var entry in context.ChangeTracker.Entries<AuditableEntity>())
{
if (entry.State == EntityState.Added) entry.Entity.SetCreatedAt(utcNow);
if (entry.State == EntityState.Modified) entry.Entity.SetUpdatedAt(utcNow);
}
}
}
```
### `src/${PROJECT}.Infrastructure/Persistence/Interceptors/DomainEventInterceptor.cs`
```csharp
using MediatR;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Diagnostics;
using ${PROJECT}.Application.Abstractions;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Infrastructure.Persistence.Interceptors;
public sealed class DomainEventInterceptor(IPublisher publisher) : SaveChangesInterceptor
{
public override async ValueTask<int> SavedChangesAsync(SaveChangesCompletedEventData eventData, int result, CancellationToken cancellationToken = default)
{
if (eventData.Context is not null)
await PublishDomainEventsAsync(eventData.Context, cancellationToken);
return await base.SavedChangesAsync(eventData, result, cancellationToken);
}
private async Task PublishDomainEventsAsync(DbContext context, CancellationToken cancellationToken)
{
var entities = context.ChangeTracker.Entries<BaseEntity>().Where(e => e.Entity.DomainEvents.Count != 0).Select(e => e.Entity).ToList();
var domainEvents = entities.SelectMany(e => e.DomainEvents).ToList();
entities.ForEach(e => e.ClearDomainEvents());
foreach (var domainEvent in domainEvents)
{
var notificationType = typeof(DomainEventNotification<>).MakeGenericType(domainEvent.GetType());
var notification = Activator.CreateInstance(notificationType, domainEvent)!;
await publisher.Publish(notification, cancellationToken);
}
}
}
```
### `src/${PROJECT}.Infrastructure/Persistence/ApplicationDbContext.cs`
```csharp
using Microsoft.EntityFrameworkCore;
using ${PROJECT}.Domain.Abstractions;
namespace ${PROJECT}.Infrastructure.Persistence;
public sealed class ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : DbContext(options), IUnitOfWork
{
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
base.OnModelCreating(modelBuilder);
}
}
```
### `src/${PROJECT}.Infrastructure/DependencyInjection.cs`
```csharp
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using ${PROJECT}.Domain.Abstractions;
using ${PROJECT}.Infrastructure.Persistence;
using ${PROJECT}.Infrastructure.Persistence.Interceptors;
namespace ${PROJECT}.Infrastructure;
public static class DependencyInjection
{
public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration configuration)
{
services.AddSingleton<AuditableEntityInterceptor>();
services.AddScoped<DomainEventInterceptor>();
services.AddDbContext<ApplicationDbContext>((sp, options) =>
{
var auditableInterceptor = sp.GetRequiredService<AuditableEntityInterceptor>();
var domainEventInterceptor = sp.GetRequiredService<DomainEventInterceptor>();
options.UseNpgsql(configuration.GetConnectionString("DefaultConnection"))
.AddInterceptors(auditableInterceptor, domainEventInterceptor);
});
services.AddScoped<IUnitOfWork>(sp => sp.GetRequiredService<ApplicationDbContext>());
return services;
}
}
```
---
## 8. Layer 4: API / Presentation
*The composition root where all layers meet. Controllers, Middleware, and Program.cs.*
### `src/${PROJECT}.Api/appsettings.json`
```json
{
"ConnectionStrings": {
"DefaultConnection": ""
},
"Serilog": {
"Using": ["Serilog.Sinks.Console"],
"MinimumLevel": {
"Default": "Information",
"Override": { "Microsoft.AspNetCore": "Warning", "Microsoft.EntityFrameworkCore": "Warning" }
},
"WriteTo": [
{ "Name": "Console", "Args": { "outputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] {SourceContext}{CorrelationId: [{CorrelationId}]} {Message:lj}{NewLine}{Exception}" } }
],
"Enrich": ["FromLogContext", "WithMachineName", "WithThreadId"]
},
"AllowedHosts": "*"
}
```
### `src/${PROJECT}.Api/Extensions/ServiceCollectionExtensions.cs`
```csharp
using Asp.Versioning;
using Serilog;
using ${PROJECT}.Application;
using ${PROJECT}.Infrastructure;
namespace ${PROJECT}.Api.Extensions;
public static class ServiceCollectionExtensions
{
public static WebApplicationBuilder AddServices(this WebApplicationBuilder builder)
{
builder.Host.UseSerilog((context, loggerConfiguration) =>
loggerConfiguration.ReadFrom.Configuration(context.Configuration));
builder.Services.AddControllers();
builder.Services.AddOpenApi();
builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
.AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});
builder.Services.AddApplication();
builder.Services.AddInfrastructure(builder.Configuration);
var connectionString = builder.Configuration.GetConnectionString("DefaultConnection")
?? throw new InvalidOperationException("Connection string 'DefaultConnection' is not configured.");
builder.Services.AddHealthChecks().AddNpgSql(connectionString);
return builder;
}
}
```
### `src/${PROJECT}.Api/Extensions/WebApplicationExtensions.cs`
```csharp
namespace ${PROJECT}.Api.Extensions;
public static class WebApplicationExtensions
{
public static WebApplication ConfigurePipeline(this WebApplication app)
{
if (app.Environment.IsDevelopment())
app.MapOpenApi();
app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.MapHealthChecks("/health");
return app;
}
}
```
### `src/${PROJECT}.Api/Program.cs`
```csharp
using Serilog;
using ${PROJECT}.Api.Extensions;
var builder = WebApplication.CreateBuilder(args);
builder.AddServices();
var app = builder.Build();
app.ConfigurePipeline();
try
{
Log.Information("Starting ${PROJECT} API in {Environment} environment", app.Environment.EnvironmentName);
app.Run();
}
catch (Exception ex)
{
Log.Fatal(ex, "Application terminated unexpectedly");
}
finally
{
Log.CloseAndFlush();
}
public partial class Program; // Needed for integration tests
```
---
## 9. Docker & Dev Environment
Create these files in your repository root.
### `.env.example`
```bash
DOCKER_IMAGE=your-dockerhub-username/${PROJECT_LOWER}-api
IMAGE_TAG=latest
ASPNETCORE_ENVIRONMENT=Development
API_PORT=5212
POSTGRES_DB=${PROJECT_LOWER}_dev
POSTGRES_USER=postgres
POSTGRES_PASSWORD=change-me-to-a-strong-password
DB_PORT=5432
CONNECTION_STRING=Host=db;Port=5432;Database=${PROJECT_LOWER}_dev;Username=postgres;Password=change-me-to-a-strong-password
```
### `compose.yml`
```yaml
services:
api:
container_name: ${PROJECT_LOWER}-api
image: ${DOCKER_IMAGE:-${PROJECT_LOWER}-api}:${IMAGE_TAG:-latest}
build:
context: .
dockerfile: Dockerfile
ports:
- "${API_PORT:-5212}:8080"
environment:
- ASPNETCORE_ENVIRONMENT=${ASPNETCORE_ENVIRONMENT:-Development}
- ConnectionStrings__DefaultConnection=${CONNECTION_STRING:-Host=db;Port=5432;Database=${PROJECT_LOWER}_dev;Username=postgres;Password=postgres}
depends_on:
db:
condition: service_healthy
db:
container_name: ${PROJECT_LOWER}-db
image: postgres:17-alpine
ports:
- "${DB_PORT:-5432}:5432"
environment:
POSTGRES_DB: ${POSTGRES_DB:-${PROJECT_LOWER}_dev}
POSTGRES_USER: ${POSTGRES_USER:-postgres}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 5
volumes:
postgres_data:
```
### `Dockerfile`
```dockerfile
FROM [mcr.microsoft.com/dotnet/aspnet:10.0](https://mcr.microsoft.com/dotnet/aspnet:10.0) AS base
WORKDIR /app
EXPOSE 8080
FROM [mcr.microsoft.com/dotnet/sdk:10.0](https://mcr.microsoft.com/dotnet/sdk:10.0) AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY global.json .
COPY Directory.Build.props .
COPY Directory.Packages.props .
COPY src/${PROJECT}.Api/${PROJECT}.Api.csproj src/${PROJECT}.Api/
COPY src/${PROJECT}.Application/${PROJECT}.Application.csproj src/${PROJECT}.Application/
COPY src/${PROJECT}.Domain/${PROJECT}.Domain.csproj src/${PROJECT}.Domain/
COPY src/${PROJECT}.Infrastructure/${PROJECT}.Infrastructure.csproj src/${PROJECT}.Infrastructure/
RUN dotnet restore src/${PROJECT}.Api/${PROJECT}.Api.csproj
COPY . .
RUN dotnet build src/${PROJECT}.Api -c $BUILD_CONFIGURATION --no-restore
FROM build AS publish
ARG BUILD_CONFIGURATION=Release
RUN dotnet publish src/${PROJECT}.Api -c $BUILD_CONFIGURATION --no-build -o /app/publish /p:UseAppHost=false
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "${PROJECT}.Api.dll"]
```
---
## 10. Test Projects
### Test Strategy
The boilerplate scaffolds three test projects, each targeting a different layer and testing style:
| Project | Tests | Style |
|---|---|---|
| `${PROJECT}.Domain.Tests` | Entities, value objects, Result pattern, domain logic | Pure unit tests — no mocks needed (Domain has zero dependencies) |
| `${PROJECT}.Application.Tests` | Command/query handlers, validators, pipeline behaviors | Unit tests with mocked `ApplicationDbContext` and `IUnitOfWork` |
| `${PROJECT}.IntegrationTests` | Full HTTP request/response cycle through the API | Integration tests using `WebApplicationFactory<Program>` with a real PostgreSQL instance |
**Shared test tooling across all projects:**
- **xUnit** — test framework (`[Fact]`, `[Theory]`)
- **FluentAssertions** — expressive assertions (`result.Should().Be(...)`)
- **Moq** — mocking framework for isolating dependencies
- **coverlet.collector** — code coverage collection (used by CI pipeline)
**Integration test additions:**
- **`Microsoft.AspNetCore.Mvc.Testing`** — provides `WebApplicationFactory<Program>` for in-process HTTP testing
### Test File Naming Convention
Test files follow the pattern `{ClassUnderTest}Tests.cs`. For example:
- `ResultTests.cs` tests `Result.cs`
- `ValidationBehaviorTests.cs` tests `ValidationBehavior.cs`
### Project References
Each test project references only the layer it tests:
- `Domain.Tests` → `Domain`
- `Application.Tests` → `Application` (which transitively includes Domain)
- `IntegrationTests` → `Api` (which transitively includes everything)
This mirrors the Clean Architecture dependency rule — test projects never reach across layers.
---
## 11. CI/CD Pipeline
The CI/CD pipeline is split into two conceptual sections:
1. **Standard CI** (test, SonarCloud, Qodana) — reusable as-is across projects. Just update repository variables.
2. **Deployment** (Docker build/push, SSH deploy) — project-specific. Customize the deployment target, Tailscale config, and SSH details.
### `qodana.yaml`
Configuration for JetBrains Qodana static analysis. Points to the `.slnx` solution file and uses the starter inspection profile.
```yaml
#-------------------------------------------------------------------------------#
# Qodana analysis is configured by qodana.yaml file #
# [https://www.jetbrains.com/help/qodana/qodana-yaml.html](https://www.jetbrains.com/help/qodana/qodana-yaml.html) #
#-------------------------------------------------------------------------------#
#################################################################################
# WARNING: Do not store sensitive information in this file, #
# as its contents will be included in the Qodana report. #
#################################################################################
version: "1.0"
#Specify IDE code to run analysis without container (Applied in CI/CD pipeline)
ide: QDNET
#Specify the .NET solution to analyze
dotnet:
solution: ${PROJECT}.slnx
#Specify inspection profile for code analysis
profile:
name: qodana.starter
#Enable inspections
#include:
# - name: <SomeEnabledInspectionId>
#Disable inspections
#exclude:
# - name: <SomeDisabledInspectionId>
# paths:
# - <path/where/not/run/inspection>
#Execute shell command before Qodana execution (Applied in CI/CD pipeline)
#bootstrap: sh ./prepare-qodana.sh
#Install IDE plugins before Qodana execution (Applied in CI/CD pipeline)
#plugins:
# - id: <plugin.id> #(plugin id can be found at [https://plugins.jetbrains.com](https://plugins.jetbrains.com))
# Quality gate. Will fail the CI/CD pipeline if any condition is not met
# severityThresholds - configures maximum thresholds for different problem severities
# testCoverageThresholds - configures minimum code coverage on a whole project and newly added code
# Code Coverage is available in Ultimate and Ultimate Plus plans
#failureConditions:
# severityThresholds:
# any: 15
# critical: 5
# testCoverageThresholds:
# fresh: 70
# total: 50
```
### `.github/workflows/ci.yml`
Full CI/CD pipeline with four jobs:
```yaml
name: CI/CD Pipeline
on:
push:
branches: [main, dev]
pull_request:
branches: [main, dev]
env:
DOTNET_VERSION: "10.0.x"
JAVA_VERSION: "17"
DOCKER_IMAGE: ${{ vars.DOCKERHUB_USERNAME }}/${PROJECT_LOWER}-api
jobs:
# ─────────────────────────────────────────────────────────────────
# Job 1: Build, test, and collect coverage
# ─────────────────────────────────────────────────────────────────
test:
name: Build & Test
runs-on: ubuntu-latest
services:
postgres:
image: postgres:17-alpine
env:
POSTGRES_DB: ${PROJECT_LOWER}_test
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U postgres"
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: ${{ env.DOTNET_VERSION }}
- name: Restore dependencies
run: dotnet restore
- name: Build solution
run: dotnet build --no-restore --configuration Release
- name: Run tests
run: >-
dotnet test
--no-build
--configuration Release
--logger "trx;LogFileName=test-results.trx"
--collect:"XPlat Code Coverage"
--results-directory ./TestResults
env:
ConnectionStrings__DefaultConnection: "Host=localhost;Port=5432;Database=${PROJECT_LOWER}_test;Username=postgres;Password=postgres"
- name: Upload test results
uses: actions/upload-artifact@v4
if: always()
with:
name: test-results
path: ./TestResults
retention-days: 7
# ─────────────────────────────────────────────────────────────────
# Job 2: SonarCloud analysis
# ─────────────────────────────────────────────────────────────────
sonar:
name: SonarCloud Analysis
runs-on: ubuntu-latest
needs: test
services:
postgres:
image: postgres:17-alpine
env:
POSTGRES_DB: ${PROJECT_LOWER}_test
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U postgres"
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: ${{ env.DOTNET_VERSION }}
- name: Setup Java
uses: actions/setup-java@v4
with:
distribution: "temurin"
java-version: ${{ env.JAVA_VERSION }}
- name: Install SonarScanner
run: dotnet tool install --global dotnet-sonarscanner
- name: Begin SonarCloud analysis
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
run: >-
dotnet sonarscanner begin
/k:"${{ vars.SONAR_PROJECT_KEY }}"
/o:"${{ vars.SONAR_ORGANIZATION_KEY }}"
/d:sonar.token="${{ secrets.SONAR_TOKEN }}"
/d:sonar.host.url="[https://sonarcloud.io](https://sonarcloud.io)"
/d:sonar.cs.opencover.reportsPaths="**/TestResults/**/coverage.opencover.xml"
/d:sonar.exclusions="**/obj/**,**/bin/**"
/d:sonar.coverage.exclusions="**/obj/**,**/bin/**,**/Migrations/**"
- name: Build solution
run: dotnet build --configuration Release
- name: Run tests with coverage
run: >-
dotnet test
--no-build
--configuration Release
--collect:"XPlat Code Coverage;Format=opencover"
--results-directory ./TestResults
env:
ConnectionStrings__DefaultConnection: "Host=localhost;Port=5432;Database=${PROJECT_LOWER}_test;Username=postgres;Password=postgres"
- name: End SonarCloud analysis
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
run: dotnet sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}"
- name: Check SonarCloud Quality Gate
uses: sonarsource/sonarqube-quality-gate-action@v1.2.0
timeout-minutes: 5
continue-on-error: true
with:
scanMetadataReportFile: .sonarqube/out/.sonar/report-task.txt
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
# ─────────────────────────────────────────────────────────────────
# Job 3: Qodana analysis (parallel with SonarCloud)
# ─────────────────────────────────────────────────────────────────
qodana:
name: Qodana Analysis
runs-on: ubuntu-latest
needs: test
permissions:
contents: write
pull-requests: write
checks: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Qodana Scan
uses: JetBrains/qodana-action@v2025.1
env:
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
# ─────────────────────────────────────────────────────────────────
# Job 4: Build, push, and deploy
# ─────────────────────────────────────────────────────────────────
deploy:
name: Deploy to Server
runs-on: ubuntu-latest
needs: [sonar, qodana]
if: github.ref == 'refs/heads/dev' && github.event_name == 'push'
environment: Development
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Build and push Docker image
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: |
${{ env.DOCKER_IMAGE }}:latest
${{ env.DOCKER_IMAGE }}:${{ github.sha }}
cache-from: type=gha
cache-to: type=gha,mode=max
- name: Connect to Tailscale
uses: tailscale/github-action@v4
with:
oauth-client-id: ${{ vars.TS_OAUTH_CLIENT_ID }}
oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
tags: tag:ci
- name: Copy compose file to server
uses: appleboy/scp-action@v1.0.0
with:
host: ${{ vars.SSH_HOST }}
username: ${{ vars.SSH_USERNAME }}
key: ${{ secrets.SSH_KEY }}
port: ${{ vars.SSH_PORT }}
source: "compose.yml,.env.example"
target: ${{ vars.DEPLOY_PATH }}
- name: Deploy via SSH
uses: appleboy/ssh-action@v1.2.0
with:
host: ${{ vars.SSH_HOST }}
username: ${{ vars.SSH_USERNAME }}
key: ${{ secrets.SSH_KEY }}
port: ${{ vars.SSH_PORT }}
envs: DOCKER_IMAGE,IMAGE_TAG
script: |
cd ${{ vars.DEPLOY_PATH }}
if [ ! -f .env ]; then
cp .env.example .env
chmod 600 .env
fi
# Update DOCKER_IMAGE and IMAGE_TAG in .env with values from CI
sed -i "s|^DOCKER_IMAGE=.*|DOCKER_IMAGE=${DOCKER_IMAGE}|" .env
sed -i "s|^IMAGE_TAG=.*|IMAGE_TAG=${IMAGE_TAG}|" .env
docker compose pull
docker compose up -d
sleep 10
# Verify all expected services are running
EXPECTED=2
RUNNING=$(docker compose ps --status running --quiet | wc -l)
if [ "$RUNNING" -lt "$EXPECTED" ]; then
echo "Expected $EXPECTED services, found $RUNNING running"
docker compose logs --tail=50
exit 1
fi
env:
DOCKER_IMAGE: ${{ env.DOCKER_IMAGE }}
IMAGE_TAG: ${{ github.sha }}
```
### Required GitHub Secrets and Variables
| Type | Name | Description |
|---|---|---|
| **Secret** | `SONAR_TOKEN` | SonarCloud authentication token |
| **Secret** | `QODANA_TOKEN` | Qodana Cloud authentication token |
| **Secret** | `DOCKERHUB_TOKEN` | Docker Hub access token |
| **Secret** | `SSH_KEY` | Private SSH key for deployment server |
| **Secret** | `TS_OAUTH_SECRET` | Tailscale OAuth secret |
| **Variable** | `DOCKERHUB_USERNAME` | Docker Hub username |
| **Variable** | `SONAR_PROJECT_KEY` | SonarCloud project key |
| **Variable** | `SONAR_ORGANIZATION_KEY` | SonarCloud organization key |
| **Variable** | `SSH_HOST` | Deployment server hostname (Tailscale IP) |
| **Variable** | `SSH_USERNAME` | SSH username on deployment server |
| **Variable** | `SSH_PORT` | SSH port on deployment server |
| **Variable** | `TS_OAUTH_CLIENT_ID` | Tailscale OAuth client ID |
| **Variable** | `DEPLOY_PATH` | Path on server where app is deployed |
---
## 12. AI-Assisted Development
### `.github/copilot-instructions.md`
This file provides project-specific context to GitHub Copilot (and other AI assistants that read it). It documents:
- **Git commit conventions** — execute commits directly, no `Co-authored-by` trailers
- **Build & run commands** — `dotnet build`, `dotnet run`, `dotnet test`, EF Core migrations
- **Architecture** — Clean Architecture dependency flow, layer responsibilities
- **Key conventions** — CQRS with MediatR, Result pattern, Domain layer rules
- **Testing conventions** — xUnit, Moq, FluentAssertions, `WebApplicationFactory<Program>`
- **Tech stack** — .NET 10, PostgreSQL, MediatR 14, FluentValidation 12, Serilog
This file is automatically picked up by Copilot in VS Code and GitHub.com, providing contextual suggestions that align with the project's architecture and conventions.
---
## 13. Running the Project
### Local Development (without Docker)
```bash
# Start PostgreSQL (via Docker or locally)
docker compose up db -d
# Run the API
dotnet run --project src/${PROJECT}.Api
# API available at http://localhost:5212
# Health check: http://localhost:5212/health
# OpenAPI spec: http://localhost:5212/openapi/v1.json (dev only)
```
### Docker Compose (full stack)
```bash
# Build and start everything
docker compose up --build -d
# API available at http://localhost:5212
# Health check: http://localhost:5212/health
```
### Running Tests
```bash
# All tests
dotnet test
# Specific test project
dotnet test tests/${PROJECT}.Domain.Tests
dotnet test tests/${PROJECT}.Application.Tests
dotnet test tests/${PROJECT}.IntegrationTests
# Single test by name
dotnet test --filter "FullyQualifiedName~MyTestMethod"
```
### EF Core Migrations
```bash
# Add a new migration
dotnet ef migrations add <MigrationName> \
--project src/${PROJECT}.Infrastructure \
--startup-project src/${PROJECT}.Api
# Apply migrations
dotnet ef database update \
--project src/${PROJECT}.Infrastructure \
--startup-project src/${PROJECT}.Api
```
---
## Appendix A: Outbox Pattern (Optional)
> **This section is an optional enhancement.** The boilerplate uses EF Core's `DomainEventInterceptor` to dispatch domain events in-process during `SaveChanges`. The outbox pattern is the next evolution — use it when you need **guaranteed delivery** of domain events to external systems (message brokers, other microservices) with at-least-once semantics.
### The Problem
The current `DomainEventInterceptor` dispatches events via MediatR *inside* the `SaveChanges` pipeline. This works well for in-process handlers (updating read models, sending notifications, etc.), but has two limitations:
1. **No guarantee of delivery to external systems** — if the application crashes after `SaveChanges` but before an external message is sent, the event is lost.
2. **Coupling to the transaction boundary** — if an event handler calls an external API or publishes to a message broker, you're mixing I/O with the database transaction.
### The Outbox Pattern Solution
Instead of dispatching events immediately, write them as rows in an `OutboxMessages` table within the **same database transaction** as the business data. A background job (Quartz.NET, which is already included in this boilerplate) polls the table and publishes events to external consumers.
**Flow:**
1. Handler modifies entity + raises domain event
2. `SaveChanges` interceptor serializes domain events into `OutboxMessages` table (same transaction)
3. Transaction commits — business data and outbox messages are atomically consistent
4. Quartz.NET background job polls `OutboxMessages`, publishes to message broker, marks as processed
### Implementation Sketch
**1. Outbox entity (Domain or Infrastructure layer):**
```csharp
public sealed class OutboxMessage
{
public Guid Id { get; init; }
public string Type { get; init; } = string.Empty; // Event CLR type name
public string Content { get; init; } = string.Empty; // Serialized event payload (JSON)
public DateTime OccurredOnUtc { get; init; }
public DateTime? ProcessedOnUtc { get; set; }
public string? Error { get; set; }
}
```
**2. Modified interceptor (writes to outbox instead of dispatching):**
```csharp
// In SaveChangesInterceptor, replace MediatR Publish with:
var outboxMessages = domainEvents.Select(e => new OutboxMessage
{
Id = Guid.NewGuid(),
Type = e.GetType().Name,
Content = JsonConvert.SerializeObject(e, new JsonSerializerSettings
{
TypeNameHandling = TypeNameHandling.All
}),
OccurredOnUtc = DateTime.UtcNow
});
dbContext.Set<OutboxMessage>().AddRange(outboxMessages);
// Events are persisted in the same SaveChanges transaction
```
**3. Quartz.NET background job:**
```csharp
[DisallowConcurrentExecution]
public sealed class ProcessOutboxMessagesJob(
ApplicationDbContext dbContext,
IPublisher publisher) : IJob
{
public async Task Execute(IJobExecutionContext context)
{
var messages = await dbContext.Set<OutboxMessage>()
.Where(m => m.ProcessedOnUtc == null)
.OrderBy(m => m.OccurredOnUtc)
.Take(20)
.ToListAsync(context.CancellationToken);
foreach (var message in messages)
{
try
{
var domainEvent = JsonConvert.DeserializeObject<IDomainEvent>(
message.Content,
new JsonSerializerSettings { TypeNameHandling = TypeNameHandling.All });
if (domainEvent is not null)
await publisher.Publish(domainEvent, context.CancellationToken);
message.ProcessedOnUtc = DateTime.UtcNow;
}
catch (Exception ex)
{
message.Error = ex.ToString();
}
}
await dbContext.SaveChangesAsync(context.CancellationToken);
}
}
```
### When to Adopt This
- You're publishing events to a message broker (RabbitMQ, Azure Service Bus, Kafka)
- You need at-least-once delivery guarantees
- You're in a microservices architecture where services communicate via events
For purely in-process event handling (the common case in a monolith), the existing `DomainEventInterceptor` approach is simpler and sufficient.
```
The Ultimate .NET 10 Clean Architecture Boilerplate: Step-by-Step Implementation Guide
This guide is an exhaustive, detail-oriented manual for recreating a .NET 10 Clean Architecture and CQRS boilerplate from scratch. It documents every file in the repository in strict chronological order—you will build the core first, and layer dependencies outward, so you never have to reference a file that doesn't exist yet.
Table of Contents
- Architecture Overview
- Prerequisites & Environment Setup
- Solution & Project Scaffolding
- Root Configuration Files
- Layer 1: Domain
- Layer 2: Application
- Layer 3: Infrastructure
- Layer 4: API / Presentation
- Docker & Dev Environment
- Test Projects
- CI/CD Pipeline
- AI-Assisted Development
- Running the Project
- Appendix A: Outbox Pattern (Optional)
1. Architecture Overview
Clean Architecture organises code into concentric layers where dependencies always point inward.
- Domain references nothing.
- Application references Domain only.
- Infrastructure references Application (and transitively, Domain).
- API references Application and Infrastructure.
This guarantees the Domain and Application layers are fully testable without a database, web server, or framework.
2. Prerequisites & Environment Setup
Ensure you have the .NET 10 SDK, Docker, and your preferred IDE installed.
To make this guide copy-paste friendly, open your terminal and set your project variables. We use two variables: one for C# PascalCase naming, and one for lowercase systems (Docker/PostgreSQL).
export PROJECT="Inventory"
export PROJECT_LOWER="inventory"
3. Solution & Project Scaffolding
Create the root directory and initialize the solution and projects using your variables:
mkdir ${PROJECT_LOWER}-api
cd ${PROJECT_LOWER}-api
# Create the solution (slnx = lightweight XML format)
dotnet new slnx -n ${PROJECT}
# Create the source projects
dotnet new webapi -n ${PROJECT}.Api -o src/${PROJECT}.Api
dotnet new classlib -n ${PROJECT}.Application -o src/${PROJECT}.Application
dotnet new classlib -n ${PROJECT}.Domain -o src/${PROJECT}.Domain
dotnet new classlib -n ${PROJECT}.Infrastructure -o src/${PROJECT}.Infrastructure
# Create the test projects
dotnet new xunit -n ${PROJECT}.Application.Tests -o tests/${PROJECT}.Application.Tests
dotnet new xunit -n ${PROJECT}.Domain.Tests -o tests/${PROJECT}.Domain.Tests
dotnet new xunit -n ${PROJECT}.IntegrationTests -o tests/${PROJECT}.IntegrationTests
# Add source projects to the solution
dotnet sln ${PROJECT}.slnx add src/${PROJECT}.Api/${PROJECT}.Api.csproj --solution-folder src
dotnet sln ${PROJECT}.slnx add src/${PROJECT}.Application/${PROJECT}.Application.csproj --solution-folder src
dotnet sln ${PROJECT}.slnx add src/${PROJECT}.Domain/${PROJECT}.Domain.csproj --solution-folder src
dotnet sln ${PROJECT}.slnx add src/${PROJECT}.Infrastructure/${PROJECT}.Infrastructure.csproj --solution-folder src
# Add test projects to the solution
dotnet sln ${PROJECT}.slnx add tests/${PROJECT}.Application.Tests/${PROJECT}.Application.Tests.csproj --solution-folder tests
dotnet sln ${PROJECT}.slnx add tests/${PROJECT}.Domain.Tests/${PROJECT}.Domain.Tests.csproj --solution-folder tests
dotnet sln ${PROJECT}.slnx add tests/${PROJECT}.IntegrationTests/${PROJECT}.IntegrationTests.csproj --solution-folder tests
# Configure Clean Architecture Dependencies
dotnet add src/${PROJECT}.Application/${PROJECT}.Application.csproj reference src/${PROJECT}.Domain/${PROJECT}.Domain.csproj
dotnet add src/${PROJECT}.Infrastructure/${PROJECT}.Infrastructure.csproj reference src/${PROJECT}.Application/${PROJECT}.Application.csproj
dotnet add src/${PROJECT}.Api/${PROJECT}.Api.csproj reference src/${PROJECT}.Application/${PROJECT}.Application.csproj
dotnet add src/${PROJECT}.Api/${PROJECT}.Api.csproj reference src/${PROJECT}.Infrastructure/${PROJECT}.Infrastructure.csproj
4. Root Configuration Files
These files lock SDK versions and manage NuGet packages centrally. Create them at the repository root.
global.json
{
"sdk": {
"rollForward": "latestFeature",
"version": "10.0.103"
}
}
Directory.Build.props
<Project>
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
</Project>
Directory.Packages.props
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="Asp.Versioning.Mvc" Version="10.0.0-preview.2"/>
<PackageVersion Include="Asp.Versioning.Mvc.ApiExplorer" Version="10.0.0-preview.2"/>
<PackageVersion Include="AspNetCore.HealthChecks.NpgSql" Version="9.0.0"/>
<PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.5"/>
<PackageVersion Include="Serilog.AspNetCore" Version="10.0.0"/>
<PackageVersion Include="Serilog.Enrichers.Environment" Version="3.0.1"/>
<PackageVersion Include="Serilog.Enrichers.Thread" Version="4.0.0"/>
<PackageVersion Include="FluentValidation" Version="12.1.1"/>
<PackageVersion Include="FluentValidation.DependencyInjectionExtensions" Version="12.1.1"/>
<PackageVersion Include="MediatR" Version="14.1.0"/>
<PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.5"/>
<PackageVersion Include="Newtonsoft.Json" Version="13.0.4"/>
<PackageVersion Include="Quartz.Extensions.Hosting" Version="3.16.1"/>
<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="10.0.5"/>
<PackageVersion Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.5"/>
<PackageVersion Include="Microsoft.EntityFrameworkCore.Tools" Version="10.0.5"/>
<PackageVersion Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.1"/>
<PackageVersion Include="coverlet.collector" Version="8.0.0"/>
<PackageVersion Include="FluentAssertions" Version="8.8.0"/>
<PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.5"/>
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.3.0"/>
<PackageVersion Include="Moq" Version="4.20.72"/>
<PackageVersion Include="xunit" Version="2.9.3"/>
<PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5"/>
</ItemGroup>
</Project>
Apply NuGet Packages to Projects
Now that versioning is centralized, add the packages to your projects.
# Application Layer
dotnet add src/${PROJECT}.Application package MediatR
dotnet add src/${PROJECT}.Application package FluentValidation
dotnet add src/${PROJECT}.Application package FluentValidation.DependencyInjectionExtensions
dotnet add src/${PROJECT}.Application package Microsoft.Extensions.Logging.Abstractions
# Infrastructure Layer
dotnet add src/${PROJECT}.Infrastructure package Microsoft.EntityFrameworkCore
dotnet add src/${PROJECT}.Infrastructure package Microsoft.EntityFrameworkCore.Design
dotnet add src/${PROJECT}.Infrastructure package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add src/${PROJECT}.Infrastructure package Newtonsoft.Json
dotnet add src/${PROJECT}.Infrastructure package Quartz.Extensions.Hosting
# API Layer
dotnet add src/${PROJECT}.Api package Serilog.AspNetCore
dotnet add src/${PROJECT}.Api package Serilog.Enrichers.Environment
dotnet add src/${PROJECT}.Api package Serilog.Enrichers.Thread
dotnet add src/${PROJECT}.Api package AspNetCore.HealthChecks.NpgSql
dotnet add src/${PROJECT}.Api package Microsoft.AspNetCore.OpenApi
dotnet add src/${PROJECT}.Api package Microsoft.EntityFrameworkCore.Tools
dotnet add src/${PROJECT}.Api package Asp.Versioning.Mvc
dotnet add src/${PROJECT}.Api package Asp.Versioning.Mvc.ApiExplorer
# Test Projects (Domain)
dotnet add tests/${PROJECT}.Domain.Tests package Microsoft.NET.Test.Sdk
dotnet add tests/${PROJECT}.Domain.Tests package xunit
dotnet add tests/${PROJECT}.Domain.Tests package xunit.runner.visualstudio
dotnet add tests/${PROJECT}.Domain.Tests package coverlet.collector
dotnet add tests/${PROJECT}.Domain.Tests package FluentAssertions
dotnet add tests/${PROJECT}.Domain.Tests package Moq
# Test Projects (Application)
dotnet add tests/${PROJECT}.Application.Tests package Microsoft.NET.Test.Sdk
dotnet add tests/${PROJECT}.Application.Tests package xunit
dotnet add tests/${PROJECT}.Application.Tests package xunit.runner.visualstudio
dotnet add tests/${PROJECT}.Application.Tests package coverlet.collector
dotnet add tests/${PROJECT}.Application.Tests package FluentAssertions
dotnet add tests/${PROJECT}.Application.Tests package Moq
# Test Projects (Integration)
dotnet add tests/${PROJECT}.IntegrationTests package Microsoft.NET.Test.Sdk
dotnet add tests/${PROJECT}.IntegrationTests package xunit
dotnet add tests/${PROJECT}.IntegrationTests package xunit.runner.visualstudio
dotnet add tests/${PROJECT}.IntegrationTests package coverlet.collector
dotnet add tests/${PROJECT}.IntegrationTests package FluentAssertions
dotnet add tests/${PROJECT}.IntegrationTests package Moq
dotnet add tests/${PROJECT}.IntegrationTests package Microsoft.AspNetCore.Mvc.Testing
5. Layer 1: Domain
The innermost layer. Contains entities, value objects, domain events, the Result pattern, and repository abstractions. It has zero NuGet dependencies.
src/${PROJECT}.Domain/Common/IDomainEvent.cs
namespace ${PROJECT}.Domain.Common;
public interface IDomainEvent
{
DateTime OccurredOn { get; }
}
src/${PROJECT}.Domain/Common/BaseEntity.cs
namespace ${PROJECT}.Domain.Common;
public abstract class BaseEntity
{
private readonly List<IDomainEvent> _domainEvents = [];
public Guid Id { get; private init; } = Guid.NewGuid();
public IReadOnlyCollection<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();
public void AddDomainEvent(IDomainEvent domainEvent) => _domainEvents.Add(domainEvent);
public void RemoveDomainEvent(IDomainEvent domainEvent) => _domainEvents.Remove(domainEvent);
public void ClearDomainEvents() => _domainEvents.Clear();
}
src/${PROJECT}.Domain/Common/AuditableEntity.cs
namespace ${PROJECT}.Domain.Common;
public abstract class AuditableEntity : BaseEntity
{
public DateTime CreatedAt { get; private set; }
public DateTime? UpdatedAt { get; private set; }
public void SetCreatedAt(DateTime createdAt) => CreatedAt = createdAt;
public void SetUpdatedAt(DateTime updatedAt) => UpdatedAt = updatedAt;
}
src/${PROJECT}.Domain/Common/Error.cs
namespace ${PROJECT}.Domain.Common;
public enum ErrorType { None = 0, Failure = 1, Validation = 2, NotFound = 3, Conflict = 4 }
public sealed record Error(string Code, string Description, ErrorType Type)
{
public static readonly Error None = new(string.Empty, string.Empty, ErrorType.None);
public static readonly Error NullValue = new("Error.NullValue", "A null value was provided.", ErrorType.Failure);
public static readonly Error NotFound = new("Error.NotFound", "The requested resource was not found.", ErrorType.NotFound);
public static readonly Error Conflict = new("Error.Conflict", "A conflict occurred with the current state.", ErrorType.Conflict);
public static readonly Error Validation = new("Error.Validation", "A validation error occurred.", ErrorType.Validation);
}
src/${PROJECT}.Domain/Common/Result.cs
namespace ${PROJECT}.Domain.Common;
public interface IValidationResult
{
static abstract Result Failure(Error error);
}
public class Result : IValidationResult
{
protected Result(bool isSuccess, Error error)
{
if (isSuccess && error != Error.None) throw new InvalidOperationException("A successful result cannot have an error.");
if (!isSuccess && error == Error.None) throw new InvalidOperationException("A failed result must have an error.");
IsSuccess = isSuccess;
Error = error;
}
public bool IsSuccess { get; }
public bool IsFailure => !IsSuccess;
public Error Error { get; }
public static Result Success() => new(true, Error.None);
public static Result<T> Success<T>(T value) => Result<T>.Success(value);
public static Result Failure(Error error) => new(false, error);
public static Result<T> Failure<T>(Error error) => Result<T>.Failure(error);
}
public class Result<T> : Result, IValidationResult
{
private readonly T? _value;
private Result(T? value, bool isSuccess, Error error) : base(isSuccess, error)
{
_value = value;
}
public T Value => IsSuccess ? _value! : throw new InvalidOperationException("Cannot access the value of a failed result.");
public static Result<T> Success(T value) => new(value, true, Error.None);
public new static Result<T> Failure(Error error) => new(default, false, error);
public static implicit operator Result<T>(T value) => Success(value);
}
src/${PROJECT}.Domain/Abstractions/IUnitOfWork.cs
namespace ${PROJECT}.Domain.Abstractions;
public interface IUnitOfWork
{
Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}
6. Layer 2: Application
Contains use cases (commands, queries, handlers), validation, mapping, and MediatR pipeline behaviors. References Domain only.
src/${PROJECT}.Application/Abstractions/Messaging/ICommand.cs
using MediatR;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Application.Abstractions.Messaging;
public interface ICommand : IRequest<Result>;
public interface ICommand<TResponse> : IRequest<Result<TResponse>>;
src/${PROJECT}.Application/Abstractions/Messaging/ICommandHandler.cs
using MediatR;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Application.Abstractions.Messaging;
public interface ICommandHandler<in TCommand> : IRequestHandler<TCommand, Result> where TCommand : ICommand;
public interface ICommandHandler<in TCommand, TResponse> : IRequestHandler<TCommand, Result<TResponse>> where TCommand : ICommand<TResponse>;
src/${PROJECT}.Application/Abstractions/IDomainEventHandler.cs
using MediatR;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Application.Abstractions;
public sealed class DomainEventNotification<TDomainEvent>(TDomainEvent domainEvent) : INotification where TDomainEvent : IDomainEvent
{
public TDomainEvent DomainEvent { get; } = domainEvent;
}
public interface IDomainEventHandler<TDomainEvent> : INotificationHandler<DomainEventNotification<TDomainEvent>> where TDomainEvent : IDomainEvent;
src/${PROJECT}.Application/Behaviors/LoggingBehavior.cs
using System.Diagnostics;
using MediatR;
using Microsoft.Extensions.Logging;
namespace ${PROJECT}.Application.Behaviors;
public sealed class LoggingBehavior<TRequest, TResponse>(ILogger<LoggingBehavior<TRequest, TResponse>> logger) : IPipelineBehavior<TRequest, TResponse> where TRequest : IRequest<TResponse>
{
public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
{
var requestName = typeof(TRequest).Name;
logger.LogInformation("Handling {RequestName}", requestName);
var stopwatch = Stopwatch.StartNew();
var response = await next(cancellationToken);
stopwatch.Stop();
logger.LogInformation("Handled {RequestName} in {ElapsedMilliseconds}ms", requestName, stopwatch.ElapsedMilliseconds);
return response;
}
}
src/${PROJECT}.Application/Behaviors/ValidationBehavior.cs
using FluentValidation;
using MediatR;
using Microsoft.Extensions.Logging;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Application.Behaviors;
public sealed class ValidationBehavior<TRequest, TResponse>(
IEnumerable<IValidator<TRequest>> validators,
ILogger<ValidationBehavior<TRequest, TResponse>> logger)
: IPipelineBehavior<TRequest, TResponse>
where TRequest : IRequest<TResponse>
where TResponse : Result, IValidationResult
{
public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
{
var validatorList = validators as IReadOnlyList<IValidator<TRequest>> ?? [.. validators];
if (validatorList.Count == 0) return await next(cancellationToken);
var context = new ValidationContext<TRequest>(request);
var validationResults = await Task.WhenAll(validatorList.Select(v => v.ValidateAsync(context, cancellationToken)));
var failures = validationResults.SelectMany(r => r.Errors).Where(f => f is not null).ToList();
if (failures.Count != 0)
{
var errorMessage = string.Join("; ", failures.Select(f => f.ErrorMessage));
var error = new Error("Validation", errorMessage, ErrorType.Validation);
logger.LogWarning("Validation failed for {RequestName}: {ErrorMessage}", typeof(TRequest).Name, errorMessage);
// Direct call to static abstract Failure method. No reflection!
return (TResponse)TResponse.Failure(error);
}
return await next(cancellationToken);
}
}
src/${PROJECT}.Application/DependencyInjection.cs
using FluentValidation;
using MediatR;
using Microsoft.Extensions.DependencyInjection;
using ${PROJECT}.Application.Behaviors;
namespace ${PROJECT}.Application;
public static class DependencyInjection
{
public static IServiceCollection AddApplication(this IServiceCollection services)
{
var assembly = typeof(DependencyInjection).Assembly;
services.AddMediatR(cfg =>
{
cfg.RegisterServicesFromAssembly(assembly);
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
});
services.AddValidatorsFromAssembly(assembly);
return services;
}
}
7. Layer 3: Infrastructure
Implements the abstractions defined in Domain and Application. Contains the EF Core DbContext and interceptors.
src/${PROJECT}.Infrastructure/Persistence/Interceptors/AuditableEntityInterceptor.cs
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Diagnostics;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Infrastructure.Persistence.Interceptors;
public sealed class AuditableEntityInterceptor : SaveChangesInterceptor
{
public override ValueTask<InterceptionResult<int>> SavingChangesAsync(DbContextEventData eventData, InterceptionResult<int> result, CancellationToken cancellationToken = default)
{
UpdateAuditableEntities(eventData.Context);
return base.SavingChangesAsync(eventData, result, cancellationToken);
}
private static void UpdateAuditableEntities(DbContext? context)
{
if (context is null) return;
var utcNow = DateTime.UtcNow;
foreach (var entry in context.ChangeTracker.Entries<AuditableEntity>())
{
if (entry.State == EntityState.Added) entry.Entity.SetCreatedAt(utcNow);
if (entry.State == EntityState.Modified) entry.Entity.SetUpdatedAt(utcNow);
}
}
}
src/${PROJECT}.Infrastructure/Persistence/Interceptors/DomainEventInterceptor.cs
using MediatR;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Diagnostics;
using ${PROJECT}.Application.Abstractions;
using ${PROJECT}.Domain.Common;
namespace ${PROJECT}.Infrastructure.Persistence.Interceptors;
public sealed class DomainEventInterceptor(IPublisher publisher) : SaveChangesInterceptor
{
public override async ValueTask<int> SavedChangesAsync(SaveChangesCompletedEventData eventData, int result, CancellationToken cancellationToken = default)
{
if (eventData.Context is not null)
await PublishDomainEventsAsync(eventData.Context, cancellationToken);
return await base.SavedChangesAsync(eventData, result, cancellationToken);
}
private async Task PublishDomainEventsAsync(DbContext context, CancellationToken cancellationToken)
{
var entities = context.ChangeTracker.Entries<BaseEntity>().Where(e => e.Entity.DomainEvents.Count != 0).Select(e => e.Entity).ToList();
var domainEvents = entities.SelectMany(e => e.DomainEvents).ToList();
entities.ForEach(e => e.ClearDomainEvents());
foreach (var domainEvent in domainEvents)
{
var notificationType = typeof(DomainEventNotification<>).MakeGenericType(domainEvent.GetType());
var notification = Activator.CreateInstance(notificationType, domainEvent)!;
await publisher.Publish(notification, cancellationToken);
}
}
}
src/${PROJECT}.Infrastructure/Persistence/ApplicationDbContext.cs
using Microsoft.EntityFrameworkCore;
using ${PROJECT}.Domain.Abstractions;
namespace ${PROJECT}.Infrastructure.Persistence;
public sealed class ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : DbContext(options), IUnitOfWork
{
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
base.OnModelCreating(modelBuilder);
}
}
src/${PROJECT}.Infrastructure/DependencyInjection.cs
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using ${PROJECT}.Domain.Abstractions;
using ${PROJECT}.Infrastructure.Persistence;
using ${PROJECT}.Infrastructure.Persistence.Interceptors;
namespace ${PROJECT}.Infrastructure;
public static class DependencyInjection
{
public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration configuration)
{
services.AddSingleton<AuditableEntityInterceptor>();
services.AddScoped<DomainEventInterceptor>();
services.AddDbContext<ApplicationDbContext>((sp, options) =>
{
var auditableInterceptor = sp.GetRequiredService<AuditableEntityInterceptor>();
var domainEventInterceptor = sp.GetRequiredService<DomainEventInterceptor>();
options.UseNpgsql(configuration.GetConnectionString("DefaultConnection"))
.AddInterceptors(auditableInterceptor, domainEventInterceptor);
});
services.AddScoped<IUnitOfWork>(sp => sp.GetRequiredService<ApplicationDbContext>());
return services;
}
}
8. Layer 4: API / Presentation
The composition root where all layers meet. Controllers, Middleware, and Program.cs.
src/${PROJECT}.Api/appsettings.json
{
"ConnectionStrings": {
"DefaultConnection": ""
},
"Serilog": {
"Using": ["Serilog.Sinks.Console"],
"MinimumLevel": {
"Default": "Information",
"Override": { "Microsoft.AspNetCore": "Warning", "Microsoft.EntityFrameworkCore": "Warning" }
},
"WriteTo": [
{ "Name": "Console", "Args": { "outputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] {SourceContext}{CorrelationId: [{CorrelationId}]} {Message:lj}{NewLine}{Exception}" } }
],
"Enrich": ["FromLogContext", "WithMachineName", "WithThreadId"]
},
"AllowedHosts": "*"
}
src/${PROJECT}.Api/Extensions/ServiceCollectionExtensions.cs
using Asp.Versioning;
using Serilog;
using ${PROJECT}.Application;
using ${PROJECT}.Infrastructure;
namespace ${PROJECT}.Api.Extensions;
public static class ServiceCollectionExtensions
{
public static WebApplicationBuilder AddServices(this WebApplicationBuilder builder)
{
builder.Host.UseSerilog((context, loggerConfiguration) =>
loggerConfiguration.ReadFrom.Configuration(context.Configuration));
builder.Services.AddControllers();
builder.Services.AddOpenApi();
builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
.AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});
builder.Services.AddApplication();
builder.Services.AddInfrastructure(builder.Configuration);
var connectionString = builder.Configuration.GetConnectionString("DefaultConnection")
?? throw new InvalidOperationException("Connection string 'DefaultConnection' is not configured.");
builder.Services.AddHealthChecks().AddNpgSql(connectionString);
return builder;
}
}
src/${PROJECT}.Api/Extensions/WebApplicationExtensions.cs
namespace ${PROJECT}.Api.Extensions;
public static class WebApplicationExtensions
{
public static WebApplication ConfigurePipeline(this WebApplication app)
{
if (app.Environment.IsDevelopment())
app.MapOpenApi();
app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.MapHealthChecks("/health");
return app;
}
}
src/${PROJECT}.Api/Program.cs
using Serilog;
using ${PROJECT}.Api.Extensions;
var builder = WebApplication.CreateBuilder(args);
builder.AddServices();
var app = builder.Build();
app.ConfigurePipeline();
try
{
Log.Information("Starting ${PROJECT} API in {Environment} environment", app.Environment.EnvironmentName);
app.Run();
}
catch (Exception ex)
{
Log.Fatal(ex, "Application terminated unexpectedly");
}
finally
{
Log.CloseAndFlush();
}
public partial class Program; // Needed for integration tests
9. Docker & Dev Environment
Create these files in your repository root.
.env.example
DOCKER_IMAGE=your-dockerhub-username/${PROJECT_LOWER}-api
IMAGE_TAG=latest
ASPNETCORE_ENVIRONMENT=Development
API_PORT=5212
POSTGRES_DB=${PROJECT_LOWER}_dev
POSTGRES_USER=postgres
POSTGRES_PASSWORD=change-me-to-a-strong-password
DB_PORT=5432
CONNECTION_STRING=Host=db;Port=5432;Database=${PROJECT_LOWER}_dev;Username=postgres;Password=change-me-to-a-strong-password
compose.yml
services:
api:
container_name: ${PROJECT_LOWER}-api
image: ${DOCKER_IMAGE:-${PROJECT_LOWER}-api}:${IMAGE_TAG:-latest}
build:
context: .
dockerfile: Dockerfile
ports:
- "${API_PORT:-5212}:8080"
environment:
- ASPNETCORE_ENVIRONMENT=${ASPNETCORE_ENVIRONMENT:-Development}
- ConnectionStrings__DefaultConnection=${CONNECTION_STRING:-Host=db;Port=5432;Database=${PROJECT_LOWER}_dev;Username=postgres;Password=postgres}
depends_on:
db:
condition: service_healthy
db:
container_name: ${PROJECT_LOWER}-db
image: postgres:17-alpine
ports:
- "${DB_PORT:-5432}:5432"
environment:
POSTGRES_DB: ${POSTGRES_DB:-${PROJECT_LOWER}_dev}
POSTGRES_USER: ${POSTGRES_USER:-postgres}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 5
volumes:
postgres_data:
Dockerfile
FROM [mcr.microsoft.com/dotnet/aspnet:10.0](https://mcr.microsoft.com/dotnet/aspnet:10.0) AS base
WORKDIR /app
EXPOSE 8080
FROM [mcr.microsoft.com/dotnet/sdk:10.0](https://mcr.microsoft.com/dotnet/sdk:10.0) AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY global.json .
COPY Directory.Build.props .
COPY Directory.Packages.props .
COPY src/${PROJECT}.Api/${PROJECT}.Api.csproj src/${PROJECT}.Api/
COPY src/${PROJECT}.Application/${PROJECT}.Application.csproj src/${PROJECT}.Application/
COPY src/${PROJECT}.Domain/${PROJECT}.Domain.csproj src/${PROJECT}.Domain/
COPY src/${PROJECT}.Infrastructure/${PROJECT}.Infrastructure.csproj src/${PROJECT}.Infrastructure/
RUN dotnet restore src/${PROJECT}.Api/${PROJECT}.Api.csproj
COPY . .
RUN dotnet build src/${PROJECT}.Api -c $BUILD_CONFIGURATION --no-restore
FROM build AS publish
ARG BUILD_CONFIGURATION=Release
RUN dotnet publish src/${PROJECT}.Api -c $BUILD_CONFIGURATION --no-build -o /app/publish /p:UseAppHost=false
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "${PROJECT}.Api.dll"]
10. Test Projects
Test Strategy
The boilerplate scaffolds three test projects, each targeting a different layer and testing style:
| Project | Tests | Style |
|---|---|---|
${PROJECT}.Domain.Tests |
Entities, value objects, Result pattern, domain logic | Pure unit tests — no mocks needed (Domain has zero dependencies) |
${PROJECT}.Application.Tests |
Command/query handlers, validators, pipeline behaviors | Unit tests with mocked ApplicationDbContext and IUnitOfWork |
${PROJECT}.IntegrationTests |
Full HTTP request/response cycle through the API | Integration tests using WebApplicationFactory<Program> with a real PostgreSQL instance |
Shared test tooling across all projects:
- xUnit — test framework (
[Fact],[Theory]) - FluentAssertions — expressive assertions (
result.Should().Be(...)) - Moq — mocking framework for isolating dependencies
- coverlet.collector — code coverage collection (used by CI pipeline)
Integration test additions:
Microsoft.AspNetCore.Mvc.Testing— providesWebApplicationFactory<Program>for in-process HTTP testing
Test File Naming Convention
Test files follow the pattern {ClassUnderTest}Tests.cs. For example:
ResultTests.cstestsResult.csValidationBehaviorTests.cstestsValidationBehavior.cs
Project References
Each test project references only the layer it tests:
Domain.Tests→DomainApplication.Tests→Application(which transitively includes Domain)IntegrationTests→Api(which transitively includes everything)
This mirrors the Clean Architecture dependency rule — test projects never reach across layers.
11. CI/CD Pipeline
The CI/CD pipeline is split into two conceptual sections:
- Standard CI (test, SonarCloud, Qodana) — reusable as-is across projects. Just update repository variables.
- Deployment (Docker build/push, SSH deploy) — project-specific. Customize the deployment target, Tailscale config, and SSH details.
qodana.yaml
Configuration for JetBrains Qodana static analysis. Points to the .slnx solution file and uses the starter inspection profile.
#-------------------------------------------------------------------------------#
# Qodana analysis is configured by qodana.yaml file #
# [https://www.jetbrains.com/help/qodana/qodana-yaml.html](https://www.jetbrains.com/help/qodana/qodana-yaml.html) #
#-------------------------------------------------------------------------------#
#################################################################################
# WARNING: Do not store sensitive information in this file, #
# as its contents will be included in the Qodana report. #
#################################################################################
version: "1.0"
#Specify IDE code to run analysis without container (Applied in CI/CD pipeline)
ide: QDNET
#Specify the .NET solution to analyze
dotnet:
solution: ${PROJECT}.slnx
#Specify inspection profile for code analysis
profile:
name: qodana.starter
#Enable inspections
#include:
# - name: <SomeEnabledInspectionId>
#Disable inspections
#exclude:
# - name: <SomeDisabledInspectionId>
# paths:
# - <path/where/not/run/inspection>
#Execute shell command before Qodana execution (Applied in CI/CD pipeline)
#bootstrap: sh ./prepare-qodana.sh
#Install IDE plugins before Qodana execution (Applied in CI/CD pipeline)
#plugins:
# - id: <plugin.id> #(plugin id can be found at [https://plugins.jetbrains.com](https://plugins.jetbrains.com))
# Quality gate. Will fail the CI/CD pipeline if any condition is not met
# severityThresholds - configures maximum thresholds for different problem severities
# testCoverageThresholds - configures minimum code coverage on a whole project and newly added code
# Code Coverage is available in Ultimate and Ultimate Plus plans
#failureConditions:
# severityThresholds:
# any: 15
# critical: 5
# testCoverageThresholds:
# fresh: 70
# total: 50
.github/workflows/ci.yml
Full CI/CD pipeline with four jobs:
name: CI/CD Pipeline
on:
push:
branches: [main, dev]
pull_request:
branches: [main, dev]
env:
DOTNET_VERSION: "10.0.x"
JAVA_VERSION: "17"
DOCKER_IMAGE: ${{ vars.DOCKERHUB_USERNAME }}/${PROJECT_LOWER}-api
jobs:
# ─────────────────────────────────────────────────────────────────
# Job 1: Build, test, and collect coverage
# ─────────────────────────────────────────────────────────────────
test:
name: Build & Test
runs-on: ubuntu-latest
services:
postgres:
image: postgres:17-alpine
env:
POSTGRES_DB: ${PROJECT_LOWER}_test
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U postgres"
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: ${{ env.DOTNET_VERSION }}
- name: Restore dependencies
run: dotnet restore
- name: Build solution
run: dotnet build --no-restore --configuration Release
- name: Run tests
run: >-
dotnet test
--no-build
--configuration Release
--logger "trx;LogFileName=test-results.trx"
--collect:"XPlat Code Coverage"
--results-directory ./TestResults
env:
ConnectionStrings__DefaultConnection: "Host=localhost;Port=5432;Database=${PROJECT_LOWER}_test;Username=postgres;Password=postgres"
- name: Upload test results
uses: actions/upload-artifact@v4
if: always()
with:
name: test-results
path: ./TestResults
retention-days: 7
# ─────────────────────────────────────────────────────────────────
# Job 2: SonarCloud analysis
# ─────────────────────────────────────────────────────────────────
sonar:
name: SonarCloud Analysis
runs-on: ubuntu-latest
needs: test
services:
postgres:
image: postgres:17-alpine
env:
POSTGRES_DB: ${PROJECT_LOWER}_test
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready -U postgres"
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: ${{ env.DOTNET_VERSION }}
- name: Setup Java
uses: actions/setup-java@v4
with:
distribution: "temurin"
java-version: ${{ env.JAVA_VERSION }}
- name: Install SonarScanner
run: dotnet tool install --global dotnet-sonarscanner
- name: Begin SonarCloud analysis
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
run: >-
dotnet sonarscanner begin
/k:"${{ vars.SONAR_PROJECT_KEY }}"
/o:"${{ vars.SONAR_ORGANIZATION_KEY }}"
/d:sonar.token="${{ secrets.SONAR_TOKEN }}"
/d:sonar.host.url="[https://sonarcloud.io](https://sonarcloud.io)"
/d:sonar.cs.opencover.reportsPaths="**/TestResults/**/coverage.opencover.xml"
/d:sonar.exclusions="**/obj/**,**/bin/**"
/d:sonar.coverage.exclusions="**/obj/**,**/bin/**,**/Migrations/**"
- name: Build solution
run: dotnet build --configuration Release
- name: Run tests with coverage
run: >-
dotnet test
--no-build
--configuration Release
--collect:"XPlat Code Coverage;Format=opencover"
--results-directory ./TestResults
env:
ConnectionStrings__DefaultConnection: "Host=localhost;Port=5432;Database=${PROJECT_LOWER}_test;Username=postgres;Password=postgres"
- name: End SonarCloud analysis
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
run: dotnet sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}"
- name: Check SonarCloud Quality Gate
uses: sonarsource/sonarqube-quality-gate-action@v1.2.0
timeout-minutes: 5
continue-on-error: true
with:
scanMetadataReportFile: .sonarqube/out/.sonar/report-task.txt
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
# ─────────────────────────────────────────────────────────────────
# Job 3: Qodana analysis (parallel with SonarCloud)
# ─────────────────────────────────────────────────────────────────
qodana:
name: Qodana Analysis
runs-on: ubuntu-latest
needs: test
permissions:
contents: write
pull-requests: write
checks: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Qodana Scan
uses: JetBrains/qodana-action@v2025.1
env:
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
# ─────────────────────────────────────────────────────────────────
# Job 4: Build, push, and deploy
# ─────────────────────────────────────────────────────────────────
deploy:
name: Deploy to Server
runs-on: ubuntu-latest
needs: [sonar, qodana]
if: github.ref == 'refs/heads/dev' && github.event_name == 'push'
environment: Development
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Build and push Docker image
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: |
${{ env.DOCKER_IMAGE }}:latest
${{ env.DOCKER_IMAGE }}:${{ github.sha }}
cache-from: type=gha
cache-to: type=gha,mode=max
- name: Connect to Tailscale
uses: tailscale/github-action@v4
with:
oauth-client-id: ${{ vars.TS_OAUTH_CLIENT_ID }}
oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
tags: tag:ci
- name: Copy compose file to server
uses: appleboy/scp-action@v1.0.0
with:
host: ${{ vars.SSH_HOST }}
username: ${{ vars.SSH_USERNAME }}
key: ${{ secrets.SSH_KEY }}
port: ${{ vars.SSH_PORT }}
source: "compose.yml,.env.example"
target: ${{ vars.DEPLOY_PATH }}
- name: Deploy via SSH
uses: appleboy/ssh-action@v1.2.0
with:
host: ${{ vars.SSH_HOST }}
username: ${{ vars.SSH_USERNAME }}
key: ${{ secrets.SSH_KEY }}
port: ${{ vars.SSH_PORT }}
envs: DOCKER_IMAGE,IMAGE_TAG
script: |
cd ${{ vars.DEPLOY_PATH }}
if [ ! -f .env ]; then
cp .env.example .env
chmod 600 .env
fi
# Update DOCKER_IMAGE and IMAGE_TAG in .env with values from CI
sed -i "s|^DOCKER_IMAGE=.*|DOCKER_IMAGE=${DOCKER_IMAGE}|" .env
sed -i "s|^IMAGE_TAG=.*|IMAGE_TAG=${IMAGE_TAG}|" .env
docker compose pull
docker compose up -d
sleep 10
# Verify all expected services are running
EXPECTED=2
RUNNING=$(docker compose ps --status running --quiet | wc -l)
if [ "$RUNNING" -lt "$EXPECTED" ]; then
echo "Expected $EXPECTED services, found $RUNNING running"
docker compose logs --tail=50
exit 1
fi
env:
DOCKER_IMAGE: ${{ env.DOCKER_IMAGE }}
IMAGE_TAG: ${{ github.sha }}
Required GitHub Secrets and Variables
| Type | Name | Description |
|---|---|---|
| Secret | SONAR_TOKEN |
SonarCloud authentication token |
| Secret | QODANA_TOKEN |
Qodana Cloud authentication token |
| Secret | DOCKERHUB_TOKEN |
Docker Hub access token |
| Secret | SSH_KEY |
Private SSH key for deployment server |
| Secret | TS_OAUTH_SECRET |
Tailscale OAuth secret |
| Variable | DOCKERHUB_USERNAME |
Docker Hub username |
| Variable | SONAR_PROJECT_KEY |
SonarCloud project key |
| Variable | SONAR_ORGANIZATION_KEY |
SonarCloud organization key |
| Variable | SSH_HOST |
Deployment server hostname (Tailscale IP) |
| Variable | SSH_USERNAME |
SSH username on deployment server |
| Variable | SSH_PORT |
SSH port on deployment server |
| Variable | TS_OAUTH_CLIENT_ID |
Tailscale OAuth client ID |
| Variable | DEPLOY_PATH |
Path on server where app is deployed |
12. AI-Assisted Development
.github/copilot-instructions.md
This file provides project-specific context to GitHub Copilot (and other AI assistants that read it). It documents:
- Git commit conventions — execute commits directly, no
Co-authored-bytrailers - Build & run commands —
dotnet build,dotnet run,dotnet test, EF Core migrations - Architecture — Clean Architecture dependency flow, layer responsibilities
- Key conventions — CQRS with MediatR, Result pattern, Domain layer rules
- Testing conventions — xUnit, Moq, FluentAssertions,
WebApplicationFactory<Program> - Tech stack — .NET 10, PostgreSQL, MediatR 14, FluentValidation 12, Serilog
This file is automatically picked up by Copilot in VS Code and GitHub.com, providing contextual suggestions that align with the project's architecture and conventions.
13. Running the Project
Local Development (without Docker)
# Start PostgreSQL (via Docker or locally)
docker compose up db -d
# Run the API
dotnet run --project src/${PROJECT}.Api
# API available at http://localhost:5212
# Health check: http://localhost:5212/health
# OpenAPI spec: http://localhost:5212/openapi/v1.json (dev only)
Docker Compose (full stack)
# Build and start everything
docker compose up --build -d
# API available at http://localhost:5212
# Health check: http://localhost:5212/health
Running Tests
# All tests
dotnet test
# Specific test project
dotnet test tests/${PROJECT}.Domain.Tests
dotnet test tests/${PROJECT}.Application.Tests
dotnet test tests/${PROJECT}.IntegrationTests
# Single test by name
dotnet test --filter "FullyQualifiedName~MyTestMethod"
EF Core Migrations
# Add a new migration
dotnet ef migrations add <MigrationName> \
--project src/${PROJECT}.Infrastructure \
--startup-project src/${PROJECT}.Api
# Apply migrations
dotnet ef database update \
--project src/${PROJECT}.Infrastructure \
--startup-project src/${PROJECT}.Api
Appendix A: Outbox Pattern (Optional)
This section is an optional enhancement. The boilerplate uses EF Core's
DomainEventInterceptorto dispatch domain events in-process duringSaveChanges. The outbox pattern is the next evolution — use it when you need guaranteed delivery of domain events to external systems (message brokers, other microservices) with at-least-once semantics.
The Problem
The current DomainEventInterceptor dispatches events via MediatR inside the SaveChanges pipeline. This works well for in-process handlers (updating read models, sending notifications, etc.), but has two limitations:
- No guarantee of delivery to external systems — if the application crashes after
SaveChangesbut before an external message is sent, the event is lost. - Coupling to the transaction boundary — if an event handler calls an external API or publishes to a message broker, you're mixing I/O with the database transaction.
The Outbox Pattern Solution
Instead of dispatching events immediately, write them as rows in an OutboxMessages table within the same database transaction as the business data. A background job (Quartz.NET, which is already included in this boilerplate) polls the table and publishes events to external consumers.
Flow:
- Handler modifies entity + raises domain event
SaveChangesinterceptor serializes domain events intoOutboxMessagestable (same transaction)- Transaction commits — business data and outbox messages are atomically consistent
- Quartz.NET background job polls
OutboxMessages, publishes to message broker, marks as processed
Implementation Sketch
1. Outbox entity (Domain or Infrastructure layer):
public sealed class OutboxMessage
{
public Guid Id { get; init; }
public string Type { get; init; } = string.Empty; // Event CLR type name
public string Content { get; init; } = string.Empty; // Serialized event payload (JSON)
public DateTime OccurredOnUtc { get; init; }
public DateTime? ProcessedOnUtc { get; set; }
public string? Error { get; set; }
}
2. Modified interceptor (writes to outbox instead of dispatching):
// In SaveChangesInterceptor, replace MediatR Publish with:
var outboxMessages = domainEvents.Select(e => new OutboxMessage
{
Id = Guid.NewGuid(),
Type = e.GetType().Name,
Content = JsonConvert.SerializeObject(e, new JsonSerializerSettings
{
TypeNameHandling = TypeNameHandling.All
}),
OccurredOnUtc = DateTime.UtcNow
});
dbContext.Set<OutboxMessage>().AddRange(outboxMessages);
// Events are persisted in the same SaveChanges transaction
3. Quartz.NET background job:
[DisallowConcurrentExecution]
public sealed class ProcessOutboxMessagesJob(
ApplicationDbContext dbContext,
IPublisher publisher) : IJob
{
public async Task Execute(IJobExecutionContext context)
{
var messages = await dbContext.Set<OutboxMessage>()
.Where(m => m.ProcessedOnUtc == null)
.OrderBy(m => m.OccurredOnUtc)
.Take(20)
.ToListAsync(context.CancellationToken);
foreach (var message in messages)
{
try
{
var domainEvent = JsonConvert.DeserializeObject<IDomainEvent>(
message.Content,
new JsonSerializerSettings { TypeNameHandling = TypeNameHandling.All });
if (domainEvent is not null)
await publisher.Publish(domainEvent, context.CancellationToken);
message.ProcessedOnUtc = DateTime.UtcNow;
}
catch (Exception ex)
{
message.Error = ex.ToString();
}
}
await dbContext.SaveChangesAsync(context.CancellationToken);
}
}
When to Adopt This
- You're publishing events to a message broker (RabbitMQ, Azure Service Bus, Kafka)
- You need at-least-once delivery guarantees
- You're in a microservices architecture where services communicate via events
For purely in-process event handling (the common case in a monolith), the existing DomainEventInterceptor approach is simpler and sufficient.
scaffold.ps1
· 7.9 KiB · PowerShell
Surowy
param(
[string]$ProjectName,
[ValidateSet("slnx", "sln")]
[string]$Format = "slnx",
[switch]$SkipPackages = $false
)
# --- 1. Setup & Validation ---
if ([string]::IsNullOrWhiteSpace($ProjectName)) {
$ProjectName = Read-Host "Please enter a project name"
}
if ([string]::IsNullOrWhiteSpace($ProjectName)) {
Write-Host "❌ Name required." -ForegroundColor Red; exit 1
}
if (Test-Path $ProjectName) {
Write-Host "❌ Directory '$ProjectName' already exists. Aborting to prevent overwrite." -ForegroundColor Red; exit 1
}
$SlnFile = "$ProjectName.$Format"
Write-Host "🚀 Scaffolding Clean Architecture (DDD) for: $ProjectName" -ForegroundColor Cyan
# Create Root Directory
New-Item -ItemType Directory -Path $ProjectName | Out-Null
Set-Location $ProjectName
# --- 2. Smart SDK Detection ---
$LatestSdk = dotnet --list-sdks | Select-Object -Last 1 | ForEach-Object { $_.Split(' ')[0] }
if ($LatestSdk) {
Write-Host "ℹ️ Detected SDK: $LatestSdk. Pinning global.json..." -ForegroundColor Gray
dotnet new globaljson --sdk-version $LatestSdk --roll-forward latestFeature
}
dotnet new gitignore
# --- 3. Create Solution & Fix NuGet ---
if ($Format -eq "slnx") { dotnet new sln -n $ProjectName --format slnx }
else { dotnet new sln -n $ProjectName }
Write-Host "📦 Configuring NuGet sources..." -ForegroundColor Cyan
dotnet new nugetconfig --force
$CurrentSources = dotnet nuget list source --configfile "nuget.config"
if ($CurrentSources -notmatch "nuget.org") {
dotnet nuget add source "https://api.nuget.org/v3/index.json" -n "nuget.org" --configfile "nuget.config"
}
# --- 4. Create Projects ---
Write-Host "🔨 Creating projects..." -ForegroundColor Cyan
# Source Projects
dotnet new classlib -n "$ProjectName.Domain" -o "src/$ProjectName.Domain"
dotnet new classlib -n "$ProjectName.Application" -o "src/$ProjectName.Application"
dotnet new classlib -n "$ProjectName.Infrastructure" -o "src/$ProjectName.Infrastructure"
dotnet new webapi -n "$ProjectName.Api" -o "src/$ProjectName.Api" --use-controllers
# Test Projects
dotnet new xunit -n "$ProjectName.Domain.Tests" -o "tests/$ProjectName.Domain.Tests"
dotnet new xunit -n "$ProjectName.Application.Tests" -o "tests/$ProjectName.Application.Tests"
dotnet new xunit -n "$ProjectName.IntegrationTests" -o "tests/$ProjectName.IntegrationTests"
# --- 4.1 CLEANUP BOILERPLATE ---
Write-Host "🧹 Removing default template files..." -ForegroundColor Cyan
$FilesToRemove = @(
"src/$ProjectName.Domain/Class1.cs",
"src/$ProjectName.Application/Class1.cs",
"src/$ProjectName.Infrastructure/Class1.cs",
"tests/$ProjectName.Domain.Tests/UnitTest1.cs",
"tests/$ProjectName.Application.Tests/UnitTest1.cs",
"tests/$ProjectName.IntegrationTests/UnitTest1.cs",
"src/$ProjectName.Api/WeatherForecast.cs",
"src/$ProjectName.Api/Controllers/WeatherForecastController.cs",
"src/$ProjectName.Api/$ProjectName.Api.http"
)
foreach ($File in $FilesToRemove) {
if (Test-Path $File) {
Remove-Item $File -Force
}
}
# --- 5. Add to Solution ---
Write-Host "📂 Organizing solution structure..." -ForegroundColor Cyan
# Add Src
dotnet sln $SlnFile add "src/$ProjectName.Domain/$ProjectName.Domain.csproj" -s "src"
dotnet sln $SlnFile add "src/$ProjectName.Application/$ProjectName.Application.csproj" -s "src"
dotnet sln $SlnFile add "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" -s "src"
dotnet sln $SlnFile add "src/$ProjectName.Api/$ProjectName.Api.csproj" -s "src"
# Add Tests
dotnet sln $SlnFile add "tests/$ProjectName.Domain.Tests/$ProjectName.Domain.Tests.csproj" -s "tests"
dotnet sln $SlnFile add "tests/$ProjectName.Application.Tests/$ProjectName.Application.Tests.csproj" -s "tests"
dotnet sln $SlnFile add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" -s "tests"
# --- 6. Add References ---
Write-Host "🔗 Wiring up dependencies..." -ForegroundColor Cyan
# Application -> Domain
dotnet add "src/$ProjectName.Application/$ProjectName.Application.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj"
# Infrastructure -> Application & Domain
dotnet add "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" reference "src/$ProjectName.Application/$ProjectName.Application.csproj"
dotnet add "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj"
# API -> Application & Infrastructure
dotnet add "src/$ProjectName.Api/$ProjectName.Api.csproj" reference "src/$ProjectName.Application/$ProjectName.Application.csproj"
dotnet add "src/$ProjectName.Api/$ProjectName.Api.csproj" reference "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj"
# Tests
dotnet add "tests/$ProjectName.Domain.Tests/$ProjectName.Domain.Tests.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj"
dotnet add "tests/$ProjectName.Application.Tests/$ProjectName.Application.Tests.csproj" reference "src/$ProjectName.Application/$ProjectName.Application.csproj"
# NOTE: Application tests usually need Domain too for entities
dotnet add "tests/$ProjectName.Application.Tests/$ProjectName.Application.Tests.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj"
dotnet add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" reference "src/$ProjectName.Api/$ProjectName.Api.csproj"
dotnet add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" reference "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj"
dotnet add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" reference "src/$ProjectName.Application/$ProjectName.Application.csproj"
dotnet add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj"
# --- 7. Install Nuget Packages (Optional) ---
if (-not $SkipPackages) {
Write-Host "📦 Installing standard Clean Architecture packages..." -ForegroundColor Cyan
function Add-Package {
param ($Project, $Package)
Write-Host " + Adding $Package..." -ForegroundColor Gray
dotnet add $Project package $Package
}
# Application Layer
Add-Package "src/$ProjectName.Application/$ProjectName.Application.csproj" "MediatR"
Add-Package "src/$ProjectName.Application/$ProjectName.Application.csproj" "FluentValidation"
Add-Package "src/$ProjectName.Application/$ProjectName.Application.csproj" "FluentValidation.DependencyInjectionExtensions"
Add-Package "src/$ProjectName.Application/$ProjectName.Application.csproj" "Microsoft.Extensions.Logging.Abstractions"
# Infrastructure Layer
Add-Package "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" "Microsoft.EntityFrameworkCore"
Add-Package "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.SqlServer"
Add-Package "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.Design"
# API Layer
Add-Package "src/$ProjectName.Api/$ProjectName.Api.csproj" "Microsoft.EntityFrameworkCore.Tools"
# Test Projects
$TestProjects = @(
"tests/$ProjectName.Domain.Tests/$ProjectName.Domain.Tests.csproj",
"tests/$ProjectName.Application.Tests/$ProjectName.Application.Tests.csproj",
"tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj"
)
foreach ($proj in $TestProjects) {
Add-Package $proj "FluentAssertions"
Add-Package $proj "Moq"
}
Add-Package "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" "Microsoft.AspNetCore.Mvc.Testing"
}
# --- 8. Final Verification ---
Write-Host "🏗️ Verifying build..." -ForegroundColor Cyan
dotnet build
if ($LASTEXITCODE -eq 0) {
Write-Host "✅ $ProjectName scaffolded successfully!" -ForegroundColor Green
Write-Host " 👉 cd $ProjectName" -ForegroundColor Gray
}
| 1 | param( |
| 2 | [string]$ProjectName, |
| 3 | [ValidateSet("slnx", "sln")] |
| 4 | [string]$Format = "slnx", |
| 5 | [switch]$SkipPackages = $false |
| 6 | ) |
| 7 | |
| 8 | # --- 1. Setup & Validation --- |
| 9 | if ([string]::IsNullOrWhiteSpace($ProjectName)) { |
| 10 | $ProjectName = Read-Host "Please enter a project name" |
| 11 | } |
| 12 | |
| 13 | if ([string]::IsNullOrWhiteSpace($ProjectName)) { |
| 14 | Write-Host "❌ Name required." -ForegroundColor Red; exit 1 |
| 15 | } |
| 16 | |
| 17 | if (Test-Path $ProjectName) { |
| 18 | Write-Host "❌ Directory '$ProjectName' already exists. Aborting to prevent overwrite." -ForegroundColor Red; exit 1 |
| 19 | } |
| 20 | |
| 21 | $SlnFile = "$ProjectName.$Format" |
| 22 | Write-Host "🚀 Scaffolding Clean Architecture (DDD) for: $ProjectName" -ForegroundColor Cyan |
| 23 | |
| 24 | # Create Root Directory |
| 25 | New-Item -ItemType Directory -Path $ProjectName | Out-Null |
| 26 | Set-Location $ProjectName |
| 27 | |
| 28 | # --- 2. Smart SDK Detection --- |
| 29 | $LatestSdk = dotnet --list-sdks | Select-Object -Last 1 | ForEach-Object { $_.Split(' ')[0] } |
| 30 | |
| 31 | if ($LatestSdk) { |
| 32 | Write-Host "ℹ️ Detected SDK: $LatestSdk. Pinning global.json..." -ForegroundColor Gray |
| 33 | dotnet new globaljson --sdk-version $LatestSdk --roll-forward latestFeature |
| 34 | } |
| 35 | |
| 36 | dotnet new gitignore |
| 37 | |
| 38 | # --- 3. Create Solution & Fix NuGet --- |
| 39 | if ($Format -eq "slnx") { dotnet new sln -n $ProjectName --format slnx } |
| 40 | else { dotnet new sln -n $ProjectName } |
| 41 | |
| 42 | Write-Host "📦 Configuring NuGet sources..." -ForegroundColor Cyan |
| 43 | dotnet new nugetconfig --force |
| 44 | $CurrentSources = dotnet nuget list source --configfile "nuget.config" |
| 45 | if ($CurrentSources -notmatch "nuget.org") { |
| 46 | dotnet nuget add source "https://api.nuget.org/v3/index.json" -n "nuget.org" --configfile "nuget.config" |
| 47 | } |
| 48 | |
| 49 | # --- 4. Create Projects --- |
| 50 | Write-Host "🔨 Creating projects..." -ForegroundColor Cyan |
| 51 | |
| 52 | # Source Projects |
| 53 | dotnet new classlib -n "$ProjectName.Domain" -o "src/$ProjectName.Domain" |
| 54 | dotnet new classlib -n "$ProjectName.Application" -o "src/$ProjectName.Application" |
| 55 | dotnet new classlib -n "$ProjectName.Infrastructure" -o "src/$ProjectName.Infrastructure" |
| 56 | dotnet new webapi -n "$ProjectName.Api" -o "src/$ProjectName.Api" --use-controllers |
| 57 | |
| 58 | # Test Projects |
| 59 | dotnet new xunit -n "$ProjectName.Domain.Tests" -o "tests/$ProjectName.Domain.Tests" |
| 60 | dotnet new xunit -n "$ProjectName.Application.Tests" -o "tests/$ProjectName.Application.Tests" |
| 61 | dotnet new xunit -n "$ProjectName.IntegrationTests" -o "tests/$ProjectName.IntegrationTests" |
| 62 | |
| 63 | # --- 4.1 CLEANUP BOILERPLATE --- |
| 64 | Write-Host "🧹 Removing default template files..." -ForegroundColor Cyan |
| 65 | |
| 66 | $FilesToRemove = @( |
| 67 | "src/$ProjectName.Domain/Class1.cs", |
| 68 | "src/$ProjectName.Application/Class1.cs", |
| 69 | "src/$ProjectName.Infrastructure/Class1.cs", |
| 70 | "tests/$ProjectName.Domain.Tests/UnitTest1.cs", |
| 71 | "tests/$ProjectName.Application.Tests/UnitTest1.cs", |
| 72 | "tests/$ProjectName.IntegrationTests/UnitTest1.cs", |
| 73 | "src/$ProjectName.Api/WeatherForecast.cs", |
| 74 | "src/$ProjectName.Api/Controllers/WeatherForecastController.cs", |
| 75 | "src/$ProjectName.Api/$ProjectName.Api.http" |
| 76 | ) |
| 77 | |
| 78 | foreach ($File in $FilesToRemove) { |
| 79 | if (Test-Path $File) { |
| 80 | Remove-Item $File -Force |
| 81 | } |
| 82 | } |
| 83 | |
| 84 | # --- 5. Add to Solution --- |
| 85 | Write-Host "📂 Organizing solution structure..." -ForegroundColor Cyan |
| 86 | |
| 87 | # Add Src |
| 88 | dotnet sln $SlnFile add "src/$ProjectName.Domain/$ProjectName.Domain.csproj" -s "src" |
| 89 | dotnet sln $SlnFile add "src/$ProjectName.Application/$ProjectName.Application.csproj" -s "src" |
| 90 | dotnet sln $SlnFile add "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" -s "src" |
| 91 | dotnet sln $SlnFile add "src/$ProjectName.Api/$ProjectName.Api.csproj" -s "src" |
| 92 | |
| 93 | # Add Tests |
| 94 | dotnet sln $SlnFile add "tests/$ProjectName.Domain.Tests/$ProjectName.Domain.Tests.csproj" -s "tests" |
| 95 | dotnet sln $SlnFile add "tests/$ProjectName.Application.Tests/$ProjectName.Application.Tests.csproj" -s "tests" |
| 96 | dotnet sln $SlnFile add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" -s "tests" |
| 97 | |
| 98 | # --- 6. Add References --- |
| 99 | Write-Host "🔗 Wiring up dependencies..." -ForegroundColor Cyan |
| 100 | |
| 101 | # Application -> Domain |
| 102 | dotnet add "src/$ProjectName.Application/$ProjectName.Application.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj" |
| 103 | |
| 104 | # Infrastructure -> Application & Domain |
| 105 | dotnet add "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" reference "src/$ProjectName.Application/$ProjectName.Application.csproj" |
| 106 | dotnet add "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj" |
| 107 | |
| 108 | # API -> Application & Infrastructure |
| 109 | dotnet add "src/$ProjectName.Api/$ProjectName.Api.csproj" reference "src/$ProjectName.Application/$ProjectName.Application.csproj" |
| 110 | dotnet add "src/$ProjectName.Api/$ProjectName.Api.csproj" reference "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" |
| 111 | |
| 112 | # Tests |
| 113 | dotnet add "tests/$ProjectName.Domain.Tests/$ProjectName.Domain.Tests.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj" |
| 114 | |
| 115 | dotnet add "tests/$ProjectName.Application.Tests/$ProjectName.Application.Tests.csproj" reference "src/$ProjectName.Application/$ProjectName.Application.csproj" |
| 116 | # NOTE: Application tests usually need Domain too for entities |
| 117 | dotnet add "tests/$ProjectName.Application.Tests/$ProjectName.Application.Tests.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj" |
| 118 | |
| 119 | dotnet add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" reference "src/$ProjectName.Api/$ProjectName.Api.csproj" |
| 120 | dotnet add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" reference "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" |
| 121 | dotnet add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" reference "src/$ProjectName.Application/$ProjectName.Application.csproj" |
| 122 | dotnet add "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" reference "src/$ProjectName.Domain/$ProjectName.Domain.csproj" |
| 123 | |
| 124 | # --- 7. Install Nuget Packages (Optional) --- |
| 125 | if (-not $SkipPackages) { |
| 126 | Write-Host "📦 Installing standard Clean Architecture packages..." -ForegroundColor Cyan |
| 127 | |
| 128 | function Add-Package { |
| 129 | param ($Project, $Package) |
| 130 | Write-Host " + Adding $Package..." -ForegroundColor Gray |
| 131 | dotnet add $Project package $Package |
| 132 | } |
| 133 | |
| 134 | # Application Layer |
| 135 | Add-Package "src/$ProjectName.Application/$ProjectName.Application.csproj" "MediatR" |
| 136 | Add-Package "src/$ProjectName.Application/$ProjectName.Application.csproj" "FluentValidation" |
| 137 | Add-Package "src/$ProjectName.Application/$ProjectName.Application.csproj" "FluentValidation.DependencyInjectionExtensions" |
| 138 | Add-Package "src/$ProjectName.Application/$ProjectName.Application.csproj" "Microsoft.Extensions.Logging.Abstractions" |
| 139 | |
| 140 | # Infrastructure Layer |
| 141 | Add-Package "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" "Microsoft.EntityFrameworkCore" |
| 142 | Add-Package "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.SqlServer" |
| 143 | Add-Package "src/$ProjectName.Infrastructure/$ProjectName.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.Design" |
| 144 | |
| 145 | # API Layer |
| 146 | Add-Package "src/$ProjectName.Api/$ProjectName.Api.csproj" "Microsoft.EntityFrameworkCore.Tools" |
| 147 | |
| 148 | # Test Projects |
| 149 | $TestProjects = @( |
| 150 | "tests/$ProjectName.Domain.Tests/$ProjectName.Domain.Tests.csproj", |
| 151 | "tests/$ProjectName.Application.Tests/$ProjectName.Application.Tests.csproj", |
| 152 | "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" |
| 153 | ) |
| 154 | foreach ($proj in $TestProjects) { |
| 155 | Add-Package $proj "FluentAssertions" |
| 156 | Add-Package $proj "Moq" |
| 157 | } |
| 158 | |
| 159 | Add-Package "tests/$ProjectName.IntegrationTests/$ProjectName.IntegrationTests.csproj" "Microsoft.AspNetCore.Mvc.Testing" |
| 160 | } |
| 161 | |
| 162 | # --- 8. Final Verification --- |
| 163 | Write-Host "🏗️ Verifying build..." -ForegroundColor Cyan |
| 164 | dotnet build |
| 165 | if ($LASTEXITCODE -eq 0) { |
| 166 | Write-Host "✅ $ProjectName scaffolded successfully!" -ForegroundColor Green |
| 167 | Write-Host " 👉 cd $ProjectName" -ForegroundColor Gray |
| 168 | } |
scaffold.sh
· 8.2 KiB · Bash
Surowy
#!/bin/bash
# Usage: ./scaffold.sh MyProjectName [slnx|sln] [true|false for packages]
# Example: ./scaffold.sh MyCleanApp slnx
# --- 1. Setup & Validation ---
if [ -z "$1" ]; then
echo "❌ Please provide a project name."
echo "Usage: ./scaffold.sh MyProjectName [slnx|sln]"
exit 1
fi
PROJECT_NAME=$1
FORMAT=${2:-slnx}
INSTALL_PACKAGES=${3:-true} # Default to true
SLN_FILE="$PROJECT_NAME.$FORMAT"
# Check if directory exists to avoid overwriting
if [ -d "$PROJECT_NAME" ]; then
echo "❌ Directory '$PROJECT_NAME' already exists. Aborting."
exit 1
fi
echo "🚀 Scaffolding $FORMAT solution for: $PROJECT_NAME (Clean Architecture + DDD)"
# Create Root Directory and enter it
mkdir "$PROJECT_NAME"
cd "$PROJECT_NAME" || exit
# --- 2. Smart SDK Detection ---
# Get the latest installed SDK version (e.g. 10.0.102)
LATEST_SDK=$(dotnet --list-sdks | tail -n 1 | awk '{print $1}')
if [ -n "$LATEST_SDK" ]; then
echo "ℹ️ Detected SDK: $LATEST_SDK. Pinning global.json..."
dotnet new globaljson --sdk-version "$LATEST_SDK" --roll-forward latestFeature
else
echo "⚠️ No SDK detected. Skipping global.json."
fi
dotnet new gitignore
# --- 3. Create Solution & Fix NuGet ---
if [ "$FORMAT" == "slnx" ]; then
dotnet new sln -n "$PROJECT_NAME" --format slnx
else
dotnet new sln -n "$PROJECT_NAME"
fi
# [FIX] Create a local nuget.config to ensure we can find packages
echo "📦 Configuring NuGet sources..."
dotnet new nugetconfig --force
# Check if nuget.org is already there
if ! dotnet nuget list source --configfile "nuget.config" | grep -q "nuget.org"; then
dotnet nuget add source "https://api.nuget.org/v3/index.json" -n "nuget.org" --configfile "nuget.config"
fi
# --- 4. Create Projects ---
echo "🔨 Creating projects..."
dotnet new classlib -n "$PROJECT_NAME.Domain" -o "src/$PROJECT_NAME.Domain"
dotnet new classlib -n "$PROJECT_NAME.Application" -o "src/$PROJECT_NAME.Application"
dotnet new classlib -n "$PROJECT_NAME.Infrastructure" -o "src/$PROJECT_NAME.Infrastructure"
dotnet new webapi -n "$PROJECT_NAME.Api" -o "src/$PROJECT_NAME.Api" --use-controllers
mkdir -p tests
dotnet new xunit -n "$PROJECT_NAME.Domain.Tests" -o "tests/$PROJECT_NAME.Domain.Tests"
dotnet new xunit -n "$PROJECT_NAME.Application.Tests" -o "tests/$PROJECT_NAME.Application.Tests"
dotnet new xunit -n "$PROJECT_NAME.IntegrationTests" -o "tests/$PROJECT_NAME.IntegrationTests"
# --- 4.1 CLEANUP BOILERPLATE ---
echo "🧹 Removing default template files..."
# Define array of files to remove relative to solution root
FILES_TO_REMOVE=(
"src/$PROJECT_NAME.Domain/Class1.cs"
"src/$PROJECT_NAME.Application/Class1.cs"
"src/$PROJECT_NAME.Infrastructure/Class1.cs"
"tests/$PROJECT_NAME.Domain.Tests/UnitTest1.cs"
"tests/$PROJECT_NAME.Application.Tests/UnitTest1.cs"
"tests/$PROJECT_NAME.IntegrationTests/UnitTest1.cs"
"src/$PROJECT_NAME.Api/WeatherForecast.cs"
"src/$PROJECT_NAME.Api/Controllers/WeatherForecastController.cs"
"src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.http"
)
for file in "${FILES_TO_REMOVE[@]}"; do
if [ -f "$file" ]; then
rm "$file"
echo " - Deleted $file"
fi
done
# --- 5. Add to Solution (With Visual Folders) ---
echo "📂 Organizing solution structure..."
# Source
dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" -s "src"
dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" -s "src"
dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" -s "src"
dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" -s "src"
# Tests
dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" -s "tests"
dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" -s "tests"
dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" -s "tests"
# --- 6. Add References ---
echo "🔗 Wiring up dependencies..."
# Application -> Domain
dotnet add "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
# Infrastructure -> Application AND Domain
dotnet add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj"
dotnet add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
# API -> Application AND Infrastructure
dotnet add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj"
dotnet add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" reference "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj"
# Tests
dotnet add "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
dotnet add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj"
dotnet add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj"
dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj"
dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj"
dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
# --- 7. Install Nuget Packages (Optional) ---
if [ "$INSTALL_PACKAGES" = true ]; then
echo "📦 Installing standard Clean Architecture packages..."
# Helper function to add packages safely
add_package() {
local proj=$1
local pkg=$2
echo " + Adding $pkg..."
dotnet add "$proj" package "$pkg" > /dev/null 2>&1
if [ $? -ne 0 ]; then
echo " ⚠️ Failed to add $pkg. Check connection."
fi
}
# Application Layer
add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "MediatR"
add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "FluentValidation"
add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "FluentValidation.DependencyInjectionExtensions"
add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "Microsoft.Extensions.Logging.Abstractions"
# Infrastructure Layer
add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore"
add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.SqlServer"
add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.Design"
# API Layer
add_package "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" "Microsoft.EntityFrameworkCore.Tools"
# Tests
TEST_PROJECTS=(
"tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj"
"tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj"
"tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj"
)
for proj in "${TEST_PROJECTS[@]}"; do
add_package "$proj" "FluentAssertions"
add_package "$proj" "Moq"
done
add_package "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" "Microsoft.AspNetCore.Mvc.Testing"
fi
# --- 8. Final Verification ---
echo "🏗️ Verifying build..."
dotnet build
if [ $? -eq 0 ]; then
echo "✅ $PROJECT_NAME scaffolded successfully!"
echo "👉 cd $PROJECT_NAME"
else
echo "⚠️ Scaffolding finished, but build failed. Run 'dotnet restore' manually."
fi
| 1 | #!/bin/bash |
| 2 | |
| 3 | # Usage: ./scaffold.sh MyProjectName [slnx|sln] [true|false for packages] |
| 4 | # Example: ./scaffold.sh MyCleanApp slnx |
| 5 | |
| 6 | # --- 1. Setup & Validation --- |
| 7 | if [ -z "$1" ]; then |
| 8 | echo "❌ Please provide a project name." |
| 9 | echo "Usage: ./scaffold.sh MyProjectName [slnx|sln]" |
| 10 | exit 1 |
| 11 | fi |
| 12 | |
| 13 | PROJECT_NAME=$1 |
| 14 | FORMAT=${2:-slnx} |
| 15 | INSTALL_PACKAGES=${3:-true} # Default to true |
| 16 | SLN_FILE="$PROJECT_NAME.$FORMAT" |
| 17 | |
| 18 | # Check if directory exists to avoid overwriting |
| 19 | if [ -d "$PROJECT_NAME" ]; then |
| 20 | echo "❌ Directory '$PROJECT_NAME' already exists. Aborting." |
| 21 | exit 1 |
| 22 | fi |
| 23 | |
| 24 | echo "🚀 Scaffolding $FORMAT solution for: $PROJECT_NAME (Clean Architecture + DDD)" |
| 25 | |
| 26 | # Create Root Directory and enter it |
| 27 | mkdir "$PROJECT_NAME" |
| 28 | cd "$PROJECT_NAME" || exit |
| 29 | |
| 30 | # --- 2. Smart SDK Detection --- |
| 31 | # Get the latest installed SDK version (e.g. 10.0.102) |
| 32 | LATEST_SDK=$(dotnet --list-sdks | tail -n 1 | awk '{print $1}') |
| 33 | |
| 34 | if [ -n "$LATEST_SDK" ]; then |
| 35 | echo "ℹ️ Detected SDK: $LATEST_SDK. Pinning global.json..." |
| 36 | dotnet new globaljson --sdk-version "$LATEST_SDK" --roll-forward latestFeature |
| 37 | else |
| 38 | echo "⚠️ No SDK detected. Skipping global.json." |
| 39 | fi |
| 40 | |
| 41 | dotnet new gitignore |
| 42 | |
| 43 | # --- 3. Create Solution & Fix NuGet --- |
| 44 | if [ "$FORMAT" == "slnx" ]; then |
| 45 | dotnet new sln -n "$PROJECT_NAME" --format slnx |
| 46 | else |
| 47 | dotnet new sln -n "$PROJECT_NAME" |
| 48 | fi |
| 49 | |
| 50 | # [FIX] Create a local nuget.config to ensure we can find packages |
| 51 | echo "📦 Configuring NuGet sources..." |
| 52 | dotnet new nugetconfig --force |
| 53 | |
| 54 | # Check if nuget.org is already there |
| 55 | if ! dotnet nuget list source --configfile "nuget.config" | grep -q "nuget.org"; then |
| 56 | dotnet nuget add source "https://api.nuget.org/v3/index.json" -n "nuget.org" --configfile "nuget.config" |
| 57 | fi |
| 58 | |
| 59 | # --- 4. Create Projects --- |
| 60 | echo "🔨 Creating projects..." |
| 61 | dotnet new classlib -n "$PROJECT_NAME.Domain" -o "src/$PROJECT_NAME.Domain" |
| 62 | dotnet new classlib -n "$PROJECT_NAME.Application" -o "src/$PROJECT_NAME.Application" |
| 63 | dotnet new classlib -n "$PROJECT_NAME.Infrastructure" -o "src/$PROJECT_NAME.Infrastructure" |
| 64 | dotnet new webapi -n "$PROJECT_NAME.Api" -o "src/$PROJECT_NAME.Api" --use-controllers |
| 65 | |
| 66 | mkdir -p tests |
| 67 | dotnet new xunit -n "$PROJECT_NAME.Domain.Tests" -o "tests/$PROJECT_NAME.Domain.Tests" |
| 68 | dotnet new xunit -n "$PROJECT_NAME.Application.Tests" -o "tests/$PROJECT_NAME.Application.Tests" |
| 69 | dotnet new xunit -n "$PROJECT_NAME.IntegrationTests" -o "tests/$PROJECT_NAME.IntegrationTests" |
| 70 | |
| 71 | # --- 4.1 CLEANUP BOILERPLATE --- |
| 72 | echo "🧹 Removing default template files..." |
| 73 | |
| 74 | # Define array of files to remove relative to solution root |
| 75 | FILES_TO_REMOVE=( |
| 76 | "src/$PROJECT_NAME.Domain/Class1.cs" |
| 77 | "src/$PROJECT_NAME.Application/Class1.cs" |
| 78 | "src/$PROJECT_NAME.Infrastructure/Class1.cs" |
| 79 | "tests/$PROJECT_NAME.Domain.Tests/UnitTest1.cs" |
| 80 | "tests/$PROJECT_NAME.Application.Tests/UnitTest1.cs" |
| 81 | "tests/$PROJECT_NAME.IntegrationTests/UnitTest1.cs" |
| 82 | "src/$PROJECT_NAME.Api/WeatherForecast.cs" |
| 83 | "src/$PROJECT_NAME.Api/Controllers/WeatherForecastController.cs" |
| 84 | "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.http" |
| 85 | ) |
| 86 | |
| 87 | for file in "${FILES_TO_REMOVE[@]}"; do |
| 88 | if [ -f "$file" ]; then |
| 89 | rm "$file" |
| 90 | echo " - Deleted $file" |
| 91 | fi |
| 92 | done |
| 93 | |
| 94 | # --- 5. Add to Solution (With Visual Folders) --- |
| 95 | echo "📂 Organizing solution structure..." |
| 96 | # Source |
| 97 | dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" -s "src" |
| 98 | dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" -s "src" |
| 99 | dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" -s "src" |
| 100 | dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" -s "src" |
| 101 | |
| 102 | # Tests |
| 103 | dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" -s "tests" |
| 104 | dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" -s "tests" |
| 105 | dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" -s "tests" |
| 106 | |
| 107 | # --- 6. Add References --- |
| 108 | echo "🔗 Wiring up dependencies..." |
| 109 | |
| 110 | # Application -> Domain |
| 111 | dotnet add "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 112 | |
| 113 | # Infrastructure -> Application AND Domain |
| 114 | dotnet add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" |
| 115 | dotnet add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 116 | |
| 117 | # API -> Application AND Infrastructure |
| 118 | dotnet add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" |
| 119 | dotnet add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" reference "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" |
| 120 | |
| 121 | # Tests |
| 122 | dotnet add "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 123 | |
| 124 | dotnet add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" |
| 125 | dotnet add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 126 | |
| 127 | dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" |
| 128 | dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" |
| 129 | dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" |
| 130 | dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 131 | |
| 132 | # --- 7. Install Nuget Packages (Optional) --- |
| 133 | if [ "$INSTALL_PACKAGES" = true ]; then |
| 134 | echo "📦 Installing standard Clean Architecture packages..." |
| 135 | |
| 136 | # Helper function to add packages safely |
| 137 | add_package() { |
| 138 | local proj=$1 |
| 139 | local pkg=$2 |
| 140 | echo " + Adding $pkg..." |
| 141 | dotnet add "$proj" package "$pkg" > /dev/null 2>&1 |
| 142 | if [ $? -ne 0 ]; then |
| 143 | echo " ⚠️ Failed to add $pkg. Check connection." |
| 144 | fi |
| 145 | } |
| 146 | |
| 147 | # Application Layer |
| 148 | add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "MediatR" |
| 149 | add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "FluentValidation" |
| 150 | add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "FluentValidation.DependencyInjectionExtensions" |
| 151 | add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "Microsoft.Extensions.Logging.Abstractions" |
| 152 | |
| 153 | # Infrastructure Layer |
| 154 | add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore" |
| 155 | add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.SqlServer" |
| 156 | add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.Design" |
| 157 | |
| 158 | # API Layer |
| 159 | add_package "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" "Microsoft.EntityFrameworkCore.Tools" |
| 160 | |
| 161 | # Tests |
| 162 | TEST_PROJECTS=( |
| 163 | "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" |
| 164 | "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" |
| 165 | "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" |
| 166 | ) |
| 167 | |
| 168 | for proj in "${TEST_PROJECTS[@]}"; do |
| 169 | add_package "$proj" "FluentAssertions" |
| 170 | add_package "$proj" "Moq" |
| 171 | done |
| 172 | |
| 173 | add_package "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" "Microsoft.AspNetCore.Mvc.Testing" |
| 174 | fi |
| 175 | |
| 176 | # --- 8. Final Verification --- |
| 177 | echo "🏗️ Verifying build..." |
| 178 | dotnet build |
| 179 | if [ $? -eq 0 ]; then |
| 180 | echo "✅ $PROJECT_NAME scaffolded successfully!" |
| 181 | echo "👉 cd $PROJECT_NAME" |
| 182 | else |
| 183 | echo "⚠️ Scaffolding finished, but build failed. Run 'dotnet restore' manually." |
| 184 | fi |
scaffold_project.sh
· 8.5 KiB · Bash
Surowy
#!/bin/bash
# --- 0. Determine Project Name ---
# Grab the name of the current directory
PROJECT_NAME=$(basename "$PWD")
echo "📂 Using current directory name as project name: $PROJECT_NAME"
# --- 1. Configuration ---
FORMAT="slnx" # Options: "sln" or "slnx"
INSTALL_PACKAGES=true # Set to true to install NuGet packages
echo "🚀 Initializing $PROJECT_NAME (Format: $FORMAT)..."
# --- 1.5 Database Selection ---
echo ""
echo "🗄️ Select your Database Provider for $PROJECT_NAME:"
echo " 1) PostgreSQL (Npgsql) [Default]"
echo " 2) SQL Server"
echo " 3) SQLite"
# < /dev/tty allows interactive prompt when piping via curl
read -p "Enter choice [1-3] (Default: 1): " DB_CHOICE < /dev/tty
case $DB_CHOICE in
2)
DB_PACKAGE="Microsoft.EntityFrameworkCore.SqlServer"
echo " Selected: SQL Server"
;;
3)
DB_PACKAGE="Microsoft.EntityFrameworkCore.Sqlite"
echo " Selected: SQLite"
;;
*)
DB_PACKAGE="Npgsql.EntityFrameworkCore.PostgreSQL"
echo " Selected: PostgreSQL"
;;
esac
echo ""
# --- 2. Smart SDK Detection ---
# Get the latest installed SDK version
LATEST_SDK=$(dotnet --list-sdks | tail -n 1 | awk '{print $1}')
if [ -n "$LATEST_SDK" ]; then
echo "ℹ️ Detected SDK: $LATEST_SDK. Pinning global.json..."
dotnet new globaljson --sdk-version "$LATEST_SDK" --roll-forward latestFeature
else
echo "⚠️ No SDK detected. Skipping global.json."
fi
dotnet new gitignore
# --- 3. Create Solution & Fix NuGet ---
if [ "$FORMAT" = "slnx" ]; then
echo "📄 Creating .slnx solution..."
dotnet new sln -n "$PROJECT_NAME" --format slnx
SLN_FILE="$PROJECT_NAME.slnx"
else
echo "📄 Creating standard .sln solution..."
dotnet new sln -n "$PROJECT_NAME"
SLN_FILE="$PROJECT_NAME.sln"
fi
# Create a local nuget.config to ensure we can find packages
echo "📦 Configuring NuGet sources..."
dotnet new nugetconfig --force
# Check if nuget.org is already there, if not, add it
if ! dotnet nuget list source --configfile "nuget.config" | grep -q "nuget.org"; then
dotnet nuget add source "https://api.nuget.org/v3/index.json" -n "nuget.org" --configfile "nuget.config"
fi
# --- 4. Create Projects ---
echo "🔨 Creating projects..."
dotnet new classlib -n "$PROJECT_NAME.Domain" -o "src/$PROJECT_NAME.Domain"
dotnet new classlib -n "$PROJECT_NAME.Application" -o "src/$PROJECT_NAME.Application"
dotnet new classlib -n "$PROJECT_NAME.Infrastructure" -o "src/$PROJECT_NAME.Infrastructure"
dotnet new webapi -n "$PROJECT_NAME.Api" -o "src/$PROJECT_NAME.Api" --use-controllers
mkdir -p tests
dotnet new xunit -n "$PROJECT_NAME.Domain.Tests" -o "tests/$PROJECT_NAME.Domain.Tests"
dotnet new xunit -n "$PROJECT_NAME.Application.Tests" -o "tests/$PROJECT_NAME.Application.Tests"
dotnet new xunit -n "$PROJECT_NAME.IntegrationTests" -o "tests/$PROJECT_NAME.IntegrationTests"
# --- 4.1 CLEANUP BOILERPLATE ---
echo "🧹 Removing default template files..."
FILES_TO_REMOVE=(
"src/$PROJECT_NAME.Domain/Class1.cs"
"src/$PROJECT_NAME.Application/Class1.cs"
"src/$PROJECT_NAME.Infrastructure/Class1.cs"
"tests/$PROJECT_NAME.Domain.Tests/UnitTest1.cs"
"tests/$PROJECT_NAME.Application.Tests/UnitTest1.cs"
"tests/$PROJECT_NAME.IntegrationTests/UnitTest1.cs"
"src/$PROJECT_NAME.Api/WeatherForecast.cs"
"src/$PROJECT_NAME.Api/Controllers/WeatherForecastController.cs"
"src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.http"
)
for file in "${FILES_TO_REMOVE[@]}"; do
if [ -f "$file" ]; then
rm "$file"
echo " - Deleted $file"
fi
done
# --- 5. Add to Solution (With Visual Folders) ---
echo "📂 Organizing solution structure in $SLN_FILE..."
dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" -s "src"
dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" -s "src"
dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" -s "src"
dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" -s "src"
dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" -s "tests"
dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" -s "tests"
dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" -s "tests"
# --- 6. Add References ---
echo "🔗 Wiring up dependencies..."
# Clean Architecture Flow
dotnet add "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
dotnet add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj"
dotnet add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
dotnet add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj"
dotnet add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" reference "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj"
# Test References
dotnet add "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
dotnet add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj"
dotnet add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj"
dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj"
dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj"
dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj"
# --- 7. Install Nuget Packages (Optional) ---
if [ "$INSTALL_PACKAGES" = true ]; then
echo "📦 Installing standard Clean Architecture packages..."
add_package() {
local proj=$1
local pkg=$2
echo " + Adding $pkg..."
dotnet add "$proj" package "$pkg" > /dev/null 2>&1
if [ $? -ne 0 ]; then
echo " ⚠️ Failed to add $pkg. Check connection."
fi
}
# Application Layer
add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "MediatR"
add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "FluentValidation"
add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "FluentValidation.DependencyInjectionExtensions"
add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "Microsoft.Extensions.Logging.Abstractions"
# Infrastructure Layer
add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore"
add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "$DB_PACKAGE"
add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.Design"
# API Layer
add_package "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" "Microsoft.EntityFrameworkCore.Tools"
add_package "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" "Serilog.AspNetCore"
# Test Projects
TEST_PROJECTS=(
"tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj"
"tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj"
"tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj"
)
for proj in "${TEST_PROJECTS[@]}"; do
add_package "$proj" "FluentAssertions"
add_package "$proj" "Moq"
done
add_package "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" "Microsoft.AspNetCore.Mvc.Testing"
fi
# --- 8. Final Verification ---
echo "🏗️ Verifying build..."
dotnet build
if [ $? -eq 0 ]; then
echo "✅ $PROJECT_NAME scaffolded successfully!"
else
echo "⚠️ Scaffolding finished, but build failed. Run 'dotnet restore' manually."
fi
| 1 | #!/bin/bash |
| 2 | |
| 3 | # --- 0. Determine Project Name --- |
| 4 | # Grab the name of the current directory |
| 5 | PROJECT_NAME=$(basename "$PWD") |
| 6 | |
| 7 | echo "📂 Using current directory name as project name: $PROJECT_NAME" |
| 8 | |
| 9 | # --- 1. Configuration --- |
| 10 | FORMAT="slnx" # Options: "sln" or "slnx" |
| 11 | INSTALL_PACKAGES=true # Set to true to install NuGet packages |
| 12 | |
| 13 | echo "🚀 Initializing $PROJECT_NAME (Format: $FORMAT)..." |
| 14 | |
| 15 | # --- 1.5 Database Selection --- |
| 16 | echo "" |
| 17 | echo "🗄️ Select your Database Provider for $PROJECT_NAME:" |
| 18 | echo " 1) PostgreSQL (Npgsql) [Default]" |
| 19 | echo " 2) SQL Server" |
| 20 | echo " 3) SQLite" |
| 21 | # < /dev/tty allows interactive prompt when piping via curl |
| 22 | read -p "Enter choice [1-3] (Default: 1): " DB_CHOICE < /dev/tty |
| 23 | |
| 24 | case $DB_CHOICE in |
| 25 | 2) |
| 26 | DB_PACKAGE="Microsoft.EntityFrameworkCore.SqlServer" |
| 27 | echo " Selected: SQL Server" |
| 28 | ;; |
| 29 | 3) |
| 30 | DB_PACKAGE="Microsoft.EntityFrameworkCore.Sqlite" |
| 31 | echo " Selected: SQLite" |
| 32 | ;; |
| 33 | *) |
| 34 | DB_PACKAGE="Npgsql.EntityFrameworkCore.PostgreSQL" |
| 35 | echo " Selected: PostgreSQL" |
| 36 | ;; |
| 37 | esac |
| 38 | echo "" |
| 39 | |
| 40 | # --- 2. Smart SDK Detection --- |
| 41 | # Get the latest installed SDK version |
| 42 | LATEST_SDK=$(dotnet --list-sdks | tail -n 1 | awk '{print $1}') |
| 43 | |
| 44 | if [ -n "$LATEST_SDK" ]; then |
| 45 | echo "ℹ️ Detected SDK: $LATEST_SDK. Pinning global.json..." |
| 46 | dotnet new globaljson --sdk-version "$LATEST_SDK" --roll-forward latestFeature |
| 47 | else |
| 48 | echo "⚠️ No SDK detected. Skipping global.json." |
| 49 | fi |
| 50 | |
| 51 | dotnet new gitignore |
| 52 | |
| 53 | # --- 3. Create Solution & Fix NuGet --- |
| 54 | if [ "$FORMAT" = "slnx" ]; then |
| 55 | echo "📄 Creating .slnx solution..." |
| 56 | dotnet new sln -n "$PROJECT_NAME" --format slnx |
| 57 | SLN_FILE="$PROJECT_NAME.slnx" |
| 58 | else |
| 59 | echo "📄 Creating standard .sln solution..." |
| 60 | dotnet new sln -n "$PROJECT_NAME" |
| 61 | SLN_FILE="$PROJECT_NAME.sln" |
| 62 | fi |
| 63 | |
| 64 | # Create a local nuget.config to ensure we can find packages |
| 65 | echo "📦 Configuring NuGet sources..." |
| 66 | dotnet new nugetconfig --force |
| 67 | |
| 68 | # Check if nuget.org is already there, if not, add it |
| 69 | if ! dotnet nuget list source --configfile "nuget.config" | grep -q "nuget.org"; then |
| 70 | dotnet nuget add source "https://api.nuget.org/v3/index.json" -n "nuget.org" --configfile "nuget.config" |
| 71 | fi |
| 72 | |
| 73 | # --- 4. Create Projects --- |
| 74 | echo "🔨 Creating projects..." |
| 75 | dotnet new classlib -n "$PROJECT_NAME.Domain" -o "src/$PROJECT_NAME.Domain" |
| 76 | dotnet new classlib -n "$PROJECT_NAME.Application" -o "src/$PROJECT_NAME.Application" |
| 77 | dotnet new classlib -n "$PROJECT_NAME.Infrastructure" -o "src/$PROJECT_NAME.Infrastructure" |
| 78 | dotnet new webapi -n "$PROJECT_NAME.Api" -o "src/$PROJECT_NAME.Api" --use-controllers |
| 79 | |
| 80 | mkdir -p tests |
| 81 | dotnet new xunit -n "$PROJECT_NAME.Domain.Tests" -o "tests/$PROJECT_NAME.Domain.Tests" |
| 82 | dotnet new xunit -n "$PROJECT_NAME.Application.Tests" -o "tests/$PROJECT_NAME.Application.Tests" |
| 83 | dotnet new xunit -n "$PROJECT_NAME.IntegrationTests" -o "tests/$PROJECT_NAME.IntegrationTests" |
| 84 | |
| 85 | # --- 4.1 CLEANUP BOILERPLATE --- |
| 86 | echo "🧹 Removing default template files..." |
| 87 | |
| 88 | FILES_TO_REMOVE=( |
| 89 | "src/$PROJECT_NAME.Domain/Class1.cs" |
| 90 | "src/$PROJECT_NAME.Application/Class1.cs" |
| 91 | "src/$PROJECT_NAME.Infrastructure/Class1.cs" |
| 92 | "tests/$PROJECT_NAME.Domain.Tests/UnitTest1.cs" |
| 93 | "tests/$PROJECT_NAME.Application.Tests/UnitTest1.cs" |
| 94 | "tests/$PROJECT_NAME.IntegrationTests/UnitTest1.cs" |
| 95 | "src/$PROJECT_NAME.Api/WeatherForecast.cs" |
| 96 | "src/$PROJECT_NAME.Api/Controllers/WeatherForecastController.cs" |
| 97 | "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.http" |
| 98 | ) |
| 99 | |
| 100 | for file in "${FILES_TO_REMOVE[@]}"; do |
| 101 | if [ -f "$file" ]; then |
| 102 | rm "$file" |
| 103 | echo " - Deleted $file" |
| 104 | fi |
| 105 | done |
| 106 | |
| 107 | # --- 5. Add to Solution (With Visual Folders) --- |
| 108 | echo "📂 Organizing solution structure in $SLN_FILE..." |
| 109 | |
| 110 | dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" -s "src" |
| 111 | dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" -s "src" |
| 112 | dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" -s "src" |
| 113 | dotnet sln "$SLN_FILE" add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" -s "src" |
| 114 | |
| 115 | dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" -s "tests" |
| 116 | dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" -s "tests" |
| 117 | dotnet sln "$SLN_FILE" add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" -s "tests" |
| 118 | |
| 119 | # --- 6. Add References --- |
| 120 | echo "🔗 Wiring up dependencies..." |
| 121 | |
| 122 | # Clean Architecture Flow |
| 123 | dotnet add "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 124 | |
| 125 | dotnet add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" |
| 126 | dotnet add "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 127 | |
| 128 | dotnet add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" |
| 129 | dotnet add "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" reference "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" |
| 130 | |
| 131 | # Test References |
| 132 | dotnet add "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 133 | |
| 134 | dotnet add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" |
| 135 | dotnet add "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 136 | |
| 137 | dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" |
| 138 | dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" |
| 139 | dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" |
| 140 | dotnet add "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" reference "src/$PROJECT_NAME.Domain/$PROJECT_NAME.Domain.csproj" |
| 141 | |
| 142 | # --- 7. Install Nuget Packages (Optional) --- |
| 143 | if [ "$INSTALL_PACKAGES" = true ]; then |
| 144 | echo "📦 Installing standard Clean Architecture packages..." |
| 145 | |
| 146 | add_package() { |
| 147 | local proj=$1 |
| 148 | local pkg=$2 |
| 149 | echo " + Adding $pkg..." |
| 150 | dotnet add "$proj" package "$pkg" > /dev/null 2>&1 |
| 151 | if [ $? -ne 0 ]; then |
| 152 | echo " ⚠️ Failed to add $pkg. Check connection." |
| 153 | fi |
| 154 | } |
| 155 | |
| 156 | # Application Layer |
| 157 | add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "MediatR" |
| 158 | add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "FluentValidation" |
| 159 | add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "FluentValidation.DependencyInjectionExtensions" |
| 160 | add_package "src/$PROJECT_NAME.Application/$PROJECT_NAME.Application.csproj" "Microsoft.Extensions.Logging.Abstractions" |
| 161 | |
| 162 | # Infrastructure Layer |
| 163 | add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore" |
| 164 | add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "$DB_PACKAGE" |
| 165 | add_package "src/$PROJECT_NAME.Infrastructure/$PROJECT_NAME.Infrastructure.csproj" "Microsoft.EntityFrameworkCore.Design" |
| 166 | |
| 167 | # API Layer |
| 168 | add_package "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" "Microsoft.EntityFrameworkCore.Tools" |
| 169 | add_package "src/$PROJECT_NAME.Api/$PROJECT_NAME.Api.csproj" "Serilog.AspNetCore" |
| 170 | |
| 171 | # Test Projects |
| 172 | TEST_PROJECTS=( |
| 173 | "tests/$PROJECT_NAME.Domain.Tests/$PROJECT_NAME.Domain.Tests.csproj" |
| 174 | "tests/$PROJECT_NAME.Application.Tests/$PROJECT_NAME.Application.Tests.csproj" |
| 175 | "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" |
| 176 | ) |
| 177 | |
| 178 | for proj in "${TEST_PROJECTS[@]}"; do |
| 179 | add_package "$proj" "FluentAssertions" |
| 180 | add_package "$proj" "Moq" |
| 181 | done |
| 182 | |
| 183 | add_package "tests/$PROJECT_NAME.IntegrationTests/$PROJECT_NAME.IntegrationTests.csproj" "Microsoft.AspNetCore.Mvc.Testing" |
| 184 | fi |
| 185 | |
| 186 | # --- 8. Final Verification --- |
| 187 | echo "🏗️ Verifying build..." |
| 188 | dotnet build |
| 189 | if [ $? -eq 0 ]; then |
| 190 | echo "✅ $PROJECT_NAME scaffolded successfully!" |
| 191 | else |
| 192 | echo "⚠️ Scaffolding finished, but build failed. Run 'dotnet restore' manually." |
| 193 | fi |