Clean Architecture for .NET

Reference for architectural decisions. This skill is the source of truth for layer rules; ddd documents its one variant (repository interfaces in Domain).

Layer Definitions

Domain (innermost)

• Contains: Entities, value objects, domain events, domain errors, enums, the Result<TValue, TError> type (skills/error-handling/SKILL.md)
• References: Nothing (zero project references)
• Packages allowed: none — the BCL covers it (TimeProvider included)
• Packages forbidden: EF Core, ASP.NET Core, MediatR, FluentValidation, any infrastructure

Application

• Contains: Use-case handlers/services, repository and gateway interfaces, DTOs, validators
• References: Domain only
• Packages allowed: FluentValidation; MediatR / AutoMapper only with the licence check below
• Packages forbidden: EF Core, database drivers, HTTP clients

Licensing: MediatR 13+ and AutoMapper 15+ are commercial (Lucky Penny Software, since July 2025; a free Community edition covers qualifying organisations). Earlier versions stay open source but get no fixes. Before adding either, confirm the licence or use a plain handler interface and hand-written mapping — neither library is needed for this layering.

Infrastructure

• Contains: DbContext, repositories, external service clients, email senders
• References: Domain, Application
• Packages allowed: EF Core, database drivers, HTTP clients, file system
• Implements: Interfaces defined in Application

API/Web (outermost)

• Contains: Controllers/endpoints, middleware, Program.cs, DI composition root
• References: Application, Infrastructure
• Packages allowed: Microsoft.AspNetCore.OpenApi (built-in AddOpenApi()/MapOpenApi()), authentication, rate limiting
• Responsibility: Wire everything together, no business logic. Referencing Infrastructure here is the composition root's job, not a violation

Tests

• References: Any (unrestricted)
• Packages: Test framework, mocking library, assertions, WebApplicationFactory

DI Registration Pattern

// In Infrastructure project:
public static class InfrastructureServiceExtensions
{
    public static IServiceCollection AddInfrastructureServices(
        this IServiceCollection services, IConfiguration config)
    {
        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseNpgsql(config.GetConnectionString("DefaultConnection")));

        services.AddScoped<IUserRepository, UserRepository>();
        return services;
    }
}

// In Application project:
public static class ApplicationServiceExtensions
{
    public static IServiceCollection AddApplicationServices(this IServiceCollection services)
    {
        services.AddScoped<IUserService, UserService>();
        services.AddValidatorsFromAssembly(typeof(ApplicationServiceExtensions).Assembly);
        return services;
    }
}

// In Program.cs (API project):
builder.Services.AddApplicationServices();
builder.Services.AddInfrastructureServices(builder.Configuration);

Validation Rules