Best Practices for Structuring Large ASP.NET Projects: A Simple Guide

Mahesh Chand
3w
3.4k
0
18

100

Article

🔧 1. Use a Clean Architecture (Onion or Hexagonal)

Separate concerns clearly with layered architecture:

Layers:

Presentation/UI (ASP.NET MVC/Razor Pages/API Controllers)
Application (Use cases, commands, queries, interfaces)
Domain (Entities, value objects, business rules)
Infrastructure (Database, file system, email, external APIs)

Example Folder Structure:

/src

/Web (Presentation Layer)
/Application
/Domain
/Infrastructure
/tests
/UnitTests
/IntegrationTests

🧱 2. Modularize by Feature, Not Type

Avoid grouping files by technical type (e.g., Controllers, Models, Views). Instead, use feature folders:

/Features

/Orders OrderController.cs OrderService.cs Order.cs

/Products ProductController.cs ProductService.cs Product.cs

This improves encapsulation and makes features easier to test and modify.

📦 3. Use Dependency Injection Everywhere

Rely on ASP.NET Core’s built-in DI system. Avoid static classes or service locators.

🧪 4. Separate Test Projects

Maintain dedicated test projects for unit and integration tests, mirroring the structure of the main app.

/tests /App.UnitTests /App.IntegrationTests

📂 5. Use Projects for Separation

Split into multiple class libraries:

MyApp.Web
MyApp.Application
MyApp.Domain
MyApp.Infrastructure

This enforces compile-time separation and better boundaries.

🔄 6. Follow SOLID Principles

Single Responsibility: One class = one job.
Open/Closed: Code open for extension, closed for modification.
Liskov: Use base classes/interfaces safely.
Interface Segregation: Prefer small interfaces.
Dependency Inversion: Depend on abstractions.

Here are the essential folder, solution, and project structures for large ASP.NET applications:

Solution Structure

Multi-Project Solution Layout:

MySolution.sln
├── src/
│   ├── MyApp.Domain/
│   ├── MyApp.Application/
│   ├── MyApp.Infrastructure/
│   ├── MyApp.Web.API/
│   ├── MyApp.Web.MVC/
│   └── MyApp.Shared/
├── tests/
│   ├── MyApp.Domain.Tests/
│   ├── MyApp.Application.Tests/
│   ├── MyApp.Infrastructure.Tests/
│   └── MyApp.Integration.Tests/
├── docs/
├── scripts/
└── tools/

For Microservices/Multiple Bounded Contexts:

MySolution.sln
├── src/
│   ├── Services/
│   │   ├── MyApp.Orders/
│   │   │   ├── MyApp.Orders.API/
│   │   │   ├── MyApp.Orders.Domain/
│   │   │   └── MyApp.Orders.Infrastructure/
│   │   ├── MyApp.Users/
│   │   └── MyApp.Inventory/
│   ├── Shared/
│   │   ├── MyApp.Shared.Kernel/
│   │   ├── MyApp.Shared.Infrastructure/
│   │   └── MyApp.Shared.Contracts/
│   └── Gateways/
│       └── MyApp.API.Gateway/

Project Structure Patterns

Clean Architecture Project Layout:

MyApp.Domain/
├── Entities/
├── ValueObjects/
├── Enums/
├── Interfaces/
├── Events/
├── Exceptions/
└── Specifications/

MyApp.Application/
├── Commands/
├── Queries/
├── Handlers/
├── Services/
├── Interfaces/
├── DTOs/
├── Mappings/
└── Validators/

MyApp.Infrastructure/
├── Data/
│   ├── Configurations/
│   ├── Migrations/
│   └── Repositories/
├── Services/
├── External/
└── Caching/

MyApp.Web.API/
├── Controllers/
├── Middleware/
├── Filters/
├── Models/
│   ├── Requests/
│   └── Responses/
├── Configuration/
└── Extensions/

Feature-Based Structure (Alternative):

MyApp.Web.API/
├── Features/
│   ├── Orders/
│   │   ├── GetOrder/
│   │   │   ├── GetOrderQuery.cs
│   │   │   ├── GetOrderHandler.cs
│   │   │   └── GetOrderValidator.cs
│   │   ├── CreateOrder/
│   │   └── OrdersController.cs
│   ├── Users/
│   └── Products/
├── Common/
│   ├── Behaviors/
│   ├── Exceptions/
│   └── Extensions/
└── Infrastructure/

Folder Organization Within Projects

MyApp.Domain/
├── Aggregates/
│   ├── Order/
│   │   ├── Order.cs
│   │   ├── OrderItem.cs
│   │   └── IOrderRepository.cs
│   └── User/
├── Common/
│   ├── BaseEntity.cs
│   ├── IAggregateRoot.cs
│   └── DomainEvent.cs
├── ValueObjects/
│   ├── Money.cs
│   ├── Address.cs
│   └── Email.cs
└── Exceptions/
    └── DomainException.cs

Infrastructure Project Structure:

MyApp.Infrastructure/
├── Data/
│   ├── Context/
│   │   └── ApplicationDbContext.cs
│   ├── Configurations/
│   │   ├── OrderConfiguration.cs
│   │   └── UserConfiguration.cs
│   ├── Repositories/
│   │   ├── OrderRepository.cs
│   │   └── BaseRepository.cs
│   └── Migrations/
├── Services/
│   ├── EmailService.cs
│   └── FileStorageService.cs
├── External/
│   ├── PaymentGateway/
│   └── NotificationService/
└── Caching/
    └── RedisCacheService.cs

API Project Structure:

MyApp.Web.API/
├── Controllers/
│   ├── V1/
│   │   ├── OrdersController.cs
│   │   └── UsersController.cs
│   └── V2/
├── Models/
│   ├── Requests/
│   │   ├── CreateOrderRequest.cs
│   │   └── UpdateOrderRequest.cs
│   ├── Responses/
│   │   └── OrderResponse.cs
│   └── Common/
│       └── PagedResponse.cs
├── Middleware/
│   ├── ExceptionHandlingMiddleware.cs
│   └── RequestLoggingMiddleware.cs
├── Filters/
│   └── ValidateModelFilter.cs
├── Configuration/
│   ├── DependencyInjection.cs
│   └── SwaggerConfiguration.cs
└── Extensions/
    └── ServiceCollectionExtensions.cs

Specialized Structures

MyApp.BackgroundServices/
├── Jobs/
│   ├── OrderProcessingJob.cs
│   └── EmailSenderJob.cs
├── Services/
├── Configuration/
└── Extensions/

For Shared Libraries:

MyApp.Shared.Kernel/
├── Extensions/
├── Utilities/
├── Constants/
├── Attributes/
└── Interfaces/

MyApp.Shared.Contracts/
├── Events/
├── Commands/
├── Queries/
└── DTOs/

Project Dependencies

Dependency Flow:

Web.API → Application + Infrastructure
Application → Domain only
Infrastructure → Domain + Application (for interfaces)
Domain → No dependencies
Shared.Kernel → No dependencies
Shared.Contracts → Shared.Kernel only

File Naming Conventions

Controllers: OrdersController.cs, UsersController.cs Services: IOrderService.cs, OrderService.cs Repositories: IOrderRepository.cs, OrderRepository.cs DTOs: CreateOrderDto.cs, OrderResponseDto.cs Commands/Queries: CreateOrderCommand.cs, GetOrderQuery.cs Handlers: CreateOrderCommandHandler.cs, GetOrderQueryHandler.cs

Configuration Files Organization

MyApp.Web.API/
├── appsettings.json
├── appsettings.Development.json
├── appsettings.Production.json
├── appsettings.Staging.json
└── Configuration/
    ├── DatabaseSettings.cs
    ├── JwtSettings.cs
    └── ExternalServiceSettings.cs

This structure provides clear separation of concerns, makes navigation intuitive for large teams, and scales well as your application grows. The key is consistency across all projects and establishing clear naming conventions that everyone follows.

Mindcracker

Founded in 2003, Mindcracker is the authority in custom software development and innovation. We put best practices into action. We deliver solutions based on consumer and industry analysis.