grimoire-dotnet-clean-architecture

name: grimoire.dotnet-clean-architecture description: "Clean Architecture best practices for modern .NET (current: .NET 10) — the Dependency Rule, layer responsibilities (Domain, Application, Infrastructure, Presentation), and the 4-project solution layout, with rich domain models, value objects, domain events, the result pattern, and CQRS with or without MediatR (commercial since v13 — covers Wolverine and plain handler alternatives). Includes architecture tests with ArchUnitNET, when NOT to use Clean Architecture (vertical slice and hybrid approaches), and avoiding over-abstraction: generic repositories over EF Core, interface-for-everything, anemic domains, leaky IQueryable boundaries. Use when structuring a .NET solution, designing or reviewing layers, or deciding where business logic belongs. Triggers: clean architecture, onion architecture, hexagonal, ports and adapters, dependency rule, domain layer, application layer, use case, CQRS, MediatR, Wolverine, value object, domain event, anemic model, repository pattern, vertical slice, ArchUnitNET."

Clean Architecture for .NET

How to apply Clean Architecture properly on modern .NET. Examples target .NET 10 and reflect the current (2026) ecosystem — including the MediatR licensing change and the shift toward pragmatic, hybrid architectures. The focus is solution structure and where logic belongs — C# language idioms, web API design, and testing mechanics have their own skills.

This skill provides guidance, not enforcement. Check the project's existing structure first and match it. Don't restructure a working solution unless asked.

Should you use Clean Architecture?

Match architectural ceremony to domain complexity — this is the single most important decision.

The cost is real: in a fully-layered solution, a trivial feature can touch 8–10 files across 4 projects. Don't pay that tax for a simple domain. Conversely, complex invariants scattered through handlers and controllers cost far more over time.

→ Deep dive (incl. vertical slice and hybrid layouts): reference/solution-structure.md

The Dependency Rule & solution layout

One rule makes everything work: source-code dependencies point inward only. Domain references nothing. Nothing inner knows anything about anything outer.

            ┌──────────────────────────────┐
            │   Web (Presentation)         │──┐
            │   endpoints, composition root│  │
            └──────────────┬───────────────┘  │
                           │ references       │ references
            ┌──────────────▼───────────────┐  │
            │   Infrastructure             │  │
            │   EF Core, external services │  │
            └──────────────┬───────────────┘  │
                           │ references       │
            ┌──────────────▼───────────────┐  │
            │   Application                │◄─┘
            │   use cases, ports, validation
            └──────────────┬───────────────┘
                           │ references
            ┌──────────────▼───────────────┐
            │   Domain                     │
            │   entities, value objects,   │
            │   domain events, invariants  │
            └──────────────────────────────┘

→ Deep dive: reference/solution-structure.md

Domain modeling quick-reference

public sealed class Order
{
    private readonly List<OrderLine> _lines = [];
    public IReadOnlyCollection<OrderLine> Lines => _lines.AsReadOnly();

    public Result Ship()
    {
        if (_lines.Count == 0)
            return Result.Failure(OrderErrors.EmptyOrderCannotShip);

        Status = OrderStatus.Shipped;
        Raise(new OrderShippedDomainEvent(Id));
        return Result.Success();
    }
}

→ Deep dive: reference/domain-layer.md

Use cases & CQRS quick-reference

MediatR is commercial since v13 (April 2025). Options, in order of preference for new projects: plain handler interfaces + DI (no dependency, shown below), Wolverine (source-generated, adds retries/sagas/outbox), or pin MediatR 12.x (last free version). Don't pick a mediator library by habit — most solutions only use 10% of it.

For CQRS beyond the handler split — the maturity ladder, read models and projections, the outbox pattern, idempotency, and event sourcing with Marten — defer to the grimoire.dotnet-cqrs skill.

public interface ICommandHandler<in TCommand, TResult>
{
    Task<TResult> Handle(TCommand command, CancellationToken ct);
}

public sealed class ShipOrderHandler : ICommandHandler<ShipOrderCommand, Result>
{
    private readonly IApplicationDbContext _db;

    public ShipOrderHandler(IApplicationDbContext db) => _db = db;

    public async Task<Result> Handle(ShipOrderCommand command, CancellationToken ct)
    {
        var order = await _db.Orders.FindAsync([command.OrderId], ct);
        if (order is null) return Result.Failure(OrderErrors.NotFound);

        var result = order.Ship();          // business rule lives in the domain
        if (result.IsFailure) return result;

        await _db.SaveChangesAsync(ct);
        return Result.Success();
    }
}

→ Deep dive (incl. dispatch without MediatR, decorator pipelines): reference/application-layer.md

Avoiding over-abstraction

The most common Clean Architecture failure is too much of it.

→ Deep dive: reference/testing-and-antipatterns.md

Testing the architecture

[Fact]
public void Domain_Should_Not_Depend_On_Outer_Layers() =>
    Types().That().ResideInAssembly(DomainAssembly)
        .Should().NotDependOnAny(
            Types().That().ResideInAssembly(ApplicationAssembly, InfrastructureAssembly))
        .Check(Architecture);

→ Deep dive: reference/testing-and-antipatterns.md

Which reference file do I need?

Recommendations draw on Jason Taylor's CleanArchitecture template (.NET 10), the Ardalis template, Milan Jovanovic's Clean Architecture writings, and Microsoft's architecture guidance — cited in the reference files.