Clean Architecture for .NET applications. Covers the 4-project layout (Domain, Application, Infrastructure, Api), dependency inversion, use case handlers, domain entities with behavior, and infrastructure as a plugin. Load this skill when building a project with Clean Architecture, discussing layered architecture, dependency inversion, use cases, or when the architecture-advisor recommends Clean Architecture.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Clean Architecture for .NET applications. Covers the 4-project layout (Domain, Application, Infrastructure, Api), dependency inversion, use case handlers, domain entities with behavior, and infrastructure as a plugin. Load this skill when building a project with Clean Architecture, discussing layered architecture, dependency inversion, use cases, or when the architecture-advisor recommends Clean Architecture.
Clean Architecture
Core Principles
Dependency inversion is the foundation — All dependencies point inward. Domain has zero project references. Application references only Domain. Infrastructure references Application and Domain. Api references all but depends on abstractions. The compiler enforces this via project references.
Domain owns the rules — Business logic lives in the Domain layer as entity methods, domain services, or specifications. The Domain layer has no knowledge of databases, HTTP, or any framework — only pure C# and .NET primitives.
Use cases are the unit of work — Each use case (command or query) is a single class in the Application layer. It orchestrates domain objects, persists through abstractions, and returns a result. No "service" classes with 20 methods.
Infrastructure is a plugin — EF Core, external APIs, email senders, file storage — all live in Infrastructure and implement interfaces defined in Application or Domain. Swap implementations without touching business logic.
The API layer is thin — Endpoints map HTTP to use cases and use cases to HTTP responses. No business logic in endpoints.
Patterns
Project Layout
src/
MyApp.Domain/
Entities/
Order.cs # Entity with behavior
OrderItem.cs
Enums/
OrderStatus.cs
Exceptions/
DomainException.cs # Base domain exception
Interfaces/
IOrderRepository.cs # Only if query needs go beyond DbSet
Common/
Entity.cs # Base entity with Id
Result.cs # Result pattern type
MyApp.Application/
Common/
Behaviors/
ValidationBehavior.cs # Mediator pipeline behavior
Interfaces/
IAppDbContext.cs # DbContext abstraction (preferred over repository)
Orders/
Commands/
CreateOrder/
CreateOrderCommand.cs
CreateOrderHandler.cs
CreateOrderValidator.cs
Queries/
GetOrder/
GetOrderQuery.cs
GetOrderHandler.cs
OrderDto.cs
MyApp.Infrastructure/
Persistence/
AppDbContext.cs # Implements IAppDbContext
Configurations/
OrderConfiguration.cs
Migrations/
Services/
EmailSender.cs # Implements IEmailSender from Application
DependencyInjection.cs # AddInfrastructure extension
MyApp.Api/
Endpoints/
OrderEndpoints.cs # Thin, maps HTTP ↔ use cases
Program.cs
DbContext Abstraction (Preferred Over Repository)
Define a minimal interface in Application; implement in Infrastructure:
Why IAppDbContext over IRepository? EF Core's DbSet already IS a repository. Adding another abstraction on top adds indirection without value in most cases.
Every endpoint group implements IEndpointGroup and is auto-discovered via app.MapEndpoints(). Program.cs never changes when adding new endpoints. See the minimal-api skill for the full IEndpointGroup interface and EndpointExtensions setup.
// BAD — entity is just a data bag, all logic in handlerpublicclassOrder
{
public Guid Id { get; set; }
publicstring CustomerId { get; set; } = null!;
publicdecimal Total { get; set; }
public List<OrderItem> Items { get; set; } = [];
}
// Handler sets everything directly
order.Total = order.Items.Sum(i => i.Quantity * i.UnitPrice);
order.Status = OrderStatus.Pending;
// GOOD — entity encapsulates its own rules (see Domain Entity pattern above)var order = Order.Create(customerId, items, clock.GetUtcNow());
DbContext in Domain Layer
// BAD — Domain references EF Core// Domain/Services/OrderService.cspublicclassOrderService(AppDbContext db) { } // Domain depends on Infrastructure!// GOOD — Domain defines interfaces, Infrastructure implements// Domain/Interfaces/IOrderRepository.cs (only if you need query abstraction beyond DbSet)// Application/Common/Interfaces/IAppDbContext.cs (preferred)
Fat Endpoints
// BAD — business logic in the endpoint
app.MapPost("/orders", async (CreateOrderRequest req, AppDbContext db) =>
{
var order = new Order { CustomerId = req.CustomerId };
foreach (var item in req.Items)
{
order.Items.Add(new OrderItem { ProductId = item.ProductId, Quantity = item.Quantity });
}
order.Total = order.Items.Sum(i => i.Quantity * i.UnitPrice);
db.Orders.Add(order);
await db.SaveChangesAsync();
return TypedResults.Created($"/orders/{order.Id}", order);
});
// GOOD — endpoint delegates to a use case
app.MapPost("/orders", async (CreateOrderCommand command, ISender sender, CancellationToken ct) =>
{
var result = await sender.Send(command, ct);
return result.IsSuccess
? TypedResults.Created($"/orders/{result.Value}", result.Value)
: result.ToProblemDetails();
});
Repository for Every Entity
// BAD — repository per entity duplicates DbSet functionalitypublicinterfaceIOrderRepository { Task<Order?> GetByIdAsync(Guid id); }
publicinterfaceIProductRepository { Task<Product?> GetByIdAsync(Guid id); }
publicinterfaceICustomerRepository { Task<Customer?> GetByIdAsync(Guid id); }
// GOOD — use IAppDbContext with DbSet<T> directly// Only create a repository interface when you have complex query logic// that you want to test in isolation or reuse across multiple use cases
Decision Guide
Scenario
Recommendation
When to use CA over VSA
Medium+ domain complexity, long-lived system, team familiar with layers
When to add a Domain layer
Business rules involve invariants across entity groups
IAppDbContext vs repositories
Prefer IAppDbContext; add repository only for complex reusable queries
Mediator vs raw handlers in CA
Mediator for pipeline behaviors (validation, logging); raw handlers for simplicity
When to add Domain events
When side effects (notifications, audit) should be decoupled from the main flow
Evolving from VSA to CA
When handlers start needing shared domain logic that does not belong in Common/
