.NET Best Practices

Production-grade .NET development guidance from top thought leaders

When to Apply

Reference these guidelines when:

• Architecting new .NET projects (choosing between Simple/Clean/Modular patterns)
• Writing or reviewing C# code for performance
• Implementing CQRS or mediator patterns
• Optimizing Entity Framework Core queries
• Designing RESTful APIs
• Debugging production performance issues
• Upgrading to .NET 8/9 features

Architecture Decision Matrix

Choose architecture based on project complexity and team size:

[!IMPORTANT] Start simple, evolve when pain points emerge. Over-engineering kills velocity. A well-structured simple API can handle most business needs.

Rule Categories by Priority

Quick Reference

1. Architecture Selection (CRITICAL)

Simple API Pattern – For MVPs, internal tools, small teams:

// ✅ Simple: Controllers → Services → DbContext
public class ProductsController : ControllerBase
{
    private readonly ProductService _service;
    public ProductsController(ProductService service) => _service = service;
    
    [HttpGet("{id}")]
    public async Task<ActionResult<ProductDto>> Get(int id) 
        => Ok(await _service.GetByIdAsync(id));
}

Clean Architecture – For complex domain logic, medium teams:

Domain → Application → Infrastructure → Presentation
         (no dependencies on outer layers)

Modular Monolith – For enterprise, large teams preparing for microservices:

Each module = independent bounded context with own:
- Domain layer
- Application layer  
- Infrastructure (can share DB initially)
- Public API (contracts for inter-module communication)

2. Performance & Memory (CRITICAL)

// ❌ BAD: Allocates new array for each slice
var subset = array.Skip(10).Take(20).ToArray();

// ✅ GOOD: Zero-allocation slice
ReadOnlySpan<int> subset = array.AsSpan(10, 20);

// ❌ BAD: New array allocation each call
public byte[] GetBuffer() => new byte[4096];

// ✅ GOOD: Rent from pool, return when done
public byte[] GetBuffer() => ArrayPool<byte>.Shared.Rent(4096);
// Remember: ArrayPool<byte>.Shared.Return(buffer);

3. Entity Framework Core (HIGH)

// ❌ BAD: Tracks entities + fetches all columns + N+1
var orders = await _context.Orders.ToListAsync();
foreach (var order in orders)
    Console.WriteLine(order.Customer.Name); // N+1!

// ✅ GOOD: No tracking, projection, eager load
var orders = await _context.Orders
    .AsNoTracking()
    .Include(o => o.Customer)
    .Select(o => new OrderDto(o.Id, o.Customer.Name, o.Total))
    .ToListAsync();

4. CQRS & Mediator (HIGH)

// Command: Uses EF Core for rich domain model
public class CreateOrderHandler : ICommandHandler<CreateOrderCommand, Guid>
{
    private readonly AppDbContext _context;
    
    public async Task<Guid> Handle(CreateOrderCommand cmd, CancellationToken ct)
    {
        var order = Order.Create(cmd.CustomerId, cmd.Items); // Domain logic
        _context.Orders.Add(order);
        await _context.SaveChangesAsync(ct);
        return order.Id;
    }
}

// Query: Uses Dapper for performance
public class GetOrdersHandler : IQueryHandler<GetOrdersQuery, IEnumerable<OrderDto>>
{
    private readonly ISqlConnectionFactory _sql;
    
    public async Task<IEnumerable<OrderDto>> Handle(GetOrdersQuery query, CancellationToken ct)
    {
        using var conn = _sql.Create();
        return await conn.QueryAsync<OrderDto>(
            "SELECT Id, CustomerName, Total FROM Orders WHERE CustomerId = @Id",
            new { query.CustomerId });
    }
}

5. API Design (MEDIUM-HIGH)

// ✅ GOOD: Versioned, paginated, proper response types
[ApiController]
[Route("api/v1/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [ProducesResponseType<PagedResult<ProductDto>>(200)]
    public async Task<ActionResult<PagedResult<ProductDto>>> GetAll(
        [FromQuery] int page = 1, 
        [FromQuery] int pageSize = 20)
    {
        var result = await _service.GetPagedAsync(page, pageSize);
        return Ok(result);
    }
    
    [HttpGet("{id:guid}")]
    [ProducesResponseType<ProductDto>(200)]
    [ProducesResponseType<ProblemDetails>(404)]
    public async Task<ActionResult<ProductDto>> GetById(Guid id)
    {
        var product = await _service.GetByIdAsync(id);
        return product is null ? NotFound() : Ok(product);
    }
}

6. Async/Await Patterns (MEDIUM)

// ❌ BAD: Deadlock risk in ASP.NET
public string GetData()
{
    return GetDataAsync().Result; // DEADLOCK!
}

// ✅ GOOD: Async all the way
public async Task<string> GetDataAsync(CancellationToken ct = default)
{
    var data = await _httpClient.GetStringAsync(url, ct);
    return data;
}

7. Common Production Pitfalls

// ❌ BAD: Port exhaustion
public class MyService
{
    public async Task CallApi()
    {
        using var client = new HttpClient(); // DON'T!
        await client.GetAsync("...");
    }
}

// ✅ GOOD: Factory-managed lifecycle
public class MyService
{
    private readonly IHttpClientFactory _factory;
    
    public async Task CallApi()
    {
        var client = _factory.CreateClient();
        await client.GetAsync("...");
    }
}

Searching References

# Find patterns by keyword
grep -l "ef core" references/
grep -l "async" references/
grep -l "memory" references/
grep -l "cqrs" references/

Problem → Reference Mapping

Attribution

Based on teachings from Original Thinkers:

• David Fowler – Async/Await, Concurrency, ASP.NET Core (Microsoft)
• Jeremy D. Miller – Wolverine, Marten, Vertical Slice, Event Sourcing
• Julie Lerman – Entity Framework Core, DDD
• Nick Chapsas – C# Performance, Span, Benchmarking
• Andrew Lock – ASP.NET Core Internals, Middleware, DI
• Milan Jovanovic – Clean Architecture, CQRS, Functional Core
• Julio Casal – Modular Monoliths, Microservices Transition
• Gui Ferreira – Memory Management, Struct Layout
• Mukesh Murugan – API Design, Idempotency, Global Errors
• Dr. Milan Milanovic – Distributed Systems, Resilience Patterns