CleanArchitectureOnion.Template 1.0.2

Clean Architecture Onion Template

This repository ships a starter solution that implements a classic Onion Architecture on .NET 8. The project follows a controller → service → repository flow, uses Entity Framework Core for persistence, and is ready to connect to a SQL Server instance. SOLID principles guide the structure so the domain stays at the center.

Solution Layers

• Domain: Core business rules, entities, domain events, and reusable AggregateRoot / Specification base types.
• Application: Service contracts and business logic that orchestrate the domain through generic repository abstractions.
• Infrastructure: EF Core DbContext, the generic Repository<T> base class, custom repositories, and Unit of Work wiring.
• Api: ASP.NET Core MVC project exposing the HTTP endpoints.
• tests: Sample xUnit tests focused on domain behavior.

Database

The default connection string, stored under DefaultConnection in appsettings.json, targets LocalDB:

Server=(localdb)\MSSQLLocalDB;Database=CleanArchitectureOnionTemplateDb;Trusted_Connection=True;MultipleActiveResultSets=true

To point at another server, edit the files under src/Api/appsettings*.json. Create the initial schema with EF Core migrations:

dotnet tool install --global dotnet-ef # install if missing
dotnet ef migrations add InitialCreate --project src/Infrastructure --startup-project src/Api
dotnet ef database update --project src/Infrastructure --startup-project src/Api

Running Locally

dotnet restore
dotnet build
dotnet test
dotnet run --project src/Api

When the API starts you can try:

• GET /api/todos
• GET /api/todos/incomplete
• GET /api/todos/{id}
• POST /api/todos
• PUT /api/todos/{id}
• DELETE /api/todos/{id}

The file src/Api/CleanArchitectureOnionTemplate.Api.http contains ready-to-run HTTP requests for manual testing.

Request Validation & Error Handling

• FluentValidation enforces DTO rules (CreateTodoRequest, UpdateTodoRequest) before controller logic runs; extend the validators under src/Application/Services/Validators for new requests.
• Invalid model states yield RFC 7807 compliant application/problem+json payloads. The response body includes an errorType hint (request_validation, domain_validation, unhandled_exception) and a field-level errors dictionary.
• ExceptionHandlingMiddleware (registered in Program.cs) translates DomainValidationException, FluentValidation failures, and unexpected exceptions into consistent HTTP responses while logging the details.

Packaging the NuGet Template

Use .template.config/template.json for the template definition and templatepack/CleanArchitectureOnion.TemplatePack.csproj for packing:

dotnet pack templatepack/CleanArchitectureOnion.TemplatePack.csproj

Publish the generated .nupkg to NuGet Gallery or an internal feed, or install it locally:

dotnet new install <path-to-nupkg>
dotnet new clean-onion -n MyCompany.MyProject

Development Notes

• Keep the domain layer free from external dependencies; compose behavior with the provided AggregateRoot and Specification bases.
• The generic IRepository<T> and Repository<T> pair remove repetitive CRUD code; extend only when you add domain-specific behavior (OCP).
• TodoService showcases the service-to-repository flow; evolve it with your own bounded contexts and specifications.
• Domain unit tests ensure business rules stay intact as the solution grows.
• Surface-facing layers should rely on IValidator<T> implementations instead of duplicating guard clauses; domain entities still validate invariants as a safety net.
• Because the template relies on a real database, manage migrations and connection strings through your CI/CD workflow before deploying.