.NET Backend Development Patterns

Master C#/.NET patterns for building production-grade APIs, MCP servers, and enterprise backends with modern best practices (2024/2025).

When to Use This Skill

• Developing new .NET Web APIs or MCP servers

• Reviewing C# code for quality and performance

• Designing service architectures with dependency injection

• Implementing caching strategies with Redis

• Writing unit and integration tests

• Optimizing database access with EF Core or Dapper

• Configuring applications with IOptions pattern

• Handling errors and implementing resilience patterns

Core Concepts

1. Project Structure (Clean Architecture)

src/

├── Domain/                     # Core business logic (no dependencies)

│   ├── Entities/

│   ├── Interfaces/

│   ├── Exceptions/

│   └── ValueObjects/

├── Application/                # Use cases, DTOs, validation

│   ├── Services/

│   ├── DTOs/

│   ├── Validators/

│   └── Interfaces/

├── Infrastructure/             # External implementations

│   ├── Data/                   # EF Core, Dapper repositories

│   ├── Caching/                # Redis, Memory cache

│   ├── External/               # HTTP clients, third-party APIs

│   └── DependencyInjection/    # Service registration

└── Api/                        # Entry point

    ├── Controllers/            # Or MinimalAPI endpoints

    ├── Middleware/

    ├── Filters/

    └── Program.cs

2. Dependency Injection Patterns

// Service registration by lifetime

public static class ServiceCollectionExtensions

{

    public static IServiceCollection AddApplicationServices(

        this IServiceCollection services,

        IConfiguration configuration)

    {

        // Scoped: One instance per HTTP request

        services.AddScoped<IProductService, ProductService>();

        services.AddScoped<IOrderService, OrderService>();

        // Singleton: One instance for app lifetime

        services.AddSingleton<ICacheService, RedisCacheService>();

        services.AddSingleton<IConnectionMultiplexer>(_ =>

            ConnectionMultiplexer.Connect(configuration["Redis:Connection"]!));

        // Transient: New instance every time

        services.AddTransient<IValidator<CreateOrderRequest>, CreateOrderValidator>();

        // Options pattern for configuration

        services.Configure<CatalogOptions>(configuration.GetSection("Catalog"));

        services.Configure<RedisOptions>(configuration.GetSection("Redis"));

        // Factory pattern for conditional creation

        services.AddScoped<IPriceCalculator>(sp =>

        {

            var options = sp.GetRequiredService<IOptions<PricingOptions>>().Value;

            return options.UseNewEngine

                ? sp.GetRequiredService<NewPriceCalculator>()

                : sp.GetRequiredService<LegacyPriceCalculator>();

        });

        // Keyed services (.NET 8+)

        services.AddKeyedScoped<IPaymentProcessor, StripeProcessor>("stripe");

        services.AddKeyedScoped<IPaymentProcessor, PayPalProcessor>("paypal");

        return services;

    }

}

// Usage with keyed services

public class CheckoutService

{

    public CheckoutService(

        [FromKeyedServices("stripe")] IPaymentProcessor stripeProcessor)

    {

        _processor = stripeProcessor;

    }

}

3. Async/Await Patterns

// ✅ CORRECT: Async all the way down

public async Task<Product> GetProductAsync(string id, CancellationToken ct = default)

{

    return await _repository.GetByIdAsync(id, ct);

}

// ✅ CORRECT: Parallel execution with WhenAll

public async Task<(Stock, Price)> GetStockAndPriceAsync(

    string productId,

    CancellationToken ct = default)

{

    var stockTask = _stockService.GetAsync(productId, ct);

    var priceTask = _priceService.GetAsync(productId, ct);

    await Task.WhenAll(stockTask, priceTask);

    return (await stockTask, await priceTask);

}

// ✅ CORRECT: ConfigureAwait in libraries

public async Task<T> LibraryMethodAsync<T>(CancellationToken ct = default)

{

    var result = await _httpClient.GetAsync(url, ct).ConfigureAwait(false);

    return await result.Content.ReadFromJsonAsync<T>(ct).ConfigureAwait(false);

}

// ✅ CORRECT: ValueTask for hot paths with caching

public ValueTask<Product?> GetCachedProductAsync(string id)

{

    if (_cache.TryGetValue(id, out Product? product))

        return ValueTask.FromResult(product);

    return new ValueTask<Product?>(GetFromDatabaseAsync(id));

}

// ❌ WRONG: Blocking on async (deadlock risk)

var result = GetProductAsync(id).Result;  // NEVER do this

var result2 = GetProductAsync(id).GetAwaiter().GetResult(); // Also bad

// ❌ WRONG: async void (except event handlers)

public async void ProcessOrder() { }  // Exceptions are lost

// ❌ WRONG: Unnecessary Task.Run for already async code

await Task.Run(async () => await GetDataAsync());  // Wastes thread

4. Configuration with IOptions

// Configuration classes

public class CatalogOptions

{

    public const string SectionName = "Catalog";

    public int DefaultPageSize { get; set; } = 50;

    public int MaxPageSize { get; set; } = 200;

    public TimeSpan CacheDuration { get; set; } = TimeSpan.FromMinutes(15);

    public bool EnableEnrichment { get; set; } = true;

}

public class RedisOptions

{

    public const string SectionName = "Redis";

    public string Connection { get; set; } = "localhost:6379";

    public string KeyPrefix { get; set; } = "mcp:";

    public int Database { get; set; } = 0;

}

// appsettings.json

{

    "Catalog": {

        "DefaultPageSize": 50,

        "MaxPageSize": 200,

        "CacheDuration": "00:15:00",

        "EnableEnrichment": true

    },

    "Redis": {

        "Connection": "localhost:6379",

        "KeyPrefix": "mcp:",

        "Database": 0

    }

}

// Registration

services.Configure<CatalogOptions>(configuration.GetSection(CatalogOptions.SectionName));

services.Configure<RedisOptions>(configuration.GetSection(RedisOptions.SectionName));

// Usage with IOptions (singleton, read once at startup)

public class CatalogService

{

    private readonly CatalogOptions _options;

    public CatalogService(IOptions<CatalogOptions> options)

    {

        _options = options.Value;

    }

}

// Usage with IOptionsSnapshot (scoped, re-reads on each request)

public class DynamicService

{

    private readonly CatalogOptions _options;

    public DynamicService(IOptionsSnapshot<CatalogOptions> options)

    {

        _options = options.Value;  // Fresh value per request

    }

}

// Usage with IOptionsMonitor (singleton, notified on changes)

public class MonitoredService

{

    private CatalogOptions _options;

    public MonitoredService(IOptionsMonitor<CatalogOptions> monitor)

    {

        _options = monitor.CurrentValue;

        monitor.OnChange(newOptions => _options = newOptions);

    }

}

5. Result Pattern (Avoiding Exceptions for Flow Control)

// Generic Result type

public class Result<T>

{

    public bool IsSuccess { get; }

    public T? Value { get; }

    public string? Error { get; }

    public string? ErrorCode { get; }

    private Result(bool isSuccess, T? value, string? error, string? errorCode)

    {

        IsSuccess = isSuccess;

        Value = value;

        Error = error;

        ErrorCode = errorCode;

    }

    public static Result<T> Success(T value) => new(true, value, null, null);

    public static Result<T> Failure(string error, string? code = null) => new(false, default, error, code);

    public Result<TNew> Map<TNew>(Func<T, TNew> mapper) =>

        IsSuccess ? Result<TNew>.Success(mapper(Value!)) : Result<TNew>.Failure(Error!, ErrorCode);

    public async Task<Result<TNew>> MapAsync<TNew>(Func<T, Task<TNew>> mapper) =>

        IsSuccess ? Result<TNew>.Success(await mapper(Value!)) : Result<TNew>.Failure(Error!, ErrorCode);

}

// Usage in service

public async Task<Result<Order>> CreateOrderAsync(CreateOrderRequest request, CancellationToken ct)

{

    // Validation

    var validation = await _validator.ValidateAsync(request, ct);

    if (!validation.IsValid)

        return Result<Order>.Failure(

            validation.Errors.First().ErrorMessage,

            "VALIDATION_ERROR");

    // Business rule check

    var stock = await _stockService.CheckAsync(request.ProductId, request.Quantity, ct);

    if (!stock.IsAvailable)

        return Result<Order>.Failure(

            $"Insufficient stock: {stock.Available} available, {request.Quantity} requested",

            "INSUFFICIENT_STOCK");

    // Create order

    var order = await _repository.CreateAsync(request.ToEntity(), ct);

    return Result<Order>.Success(order);

}

// Usage in controller/endpoint

app.MapPost("/orders", async (

    CreateOrderRequest request,

    IOrderService orderService,

    CancellationToken ct) =>

{

    var result = await orderService.CreateOrderAsync(request, ct);

    return result.IsSuccess

        ? Results.Created($"/orders/{result.Value!.Id}", result.Value)

        : Results.BadRequest(new { error = result.Error, code = result.ErrorCode });

});

Data Access Patterns

Entity Framework Core

// DbContext configuration

public class AppDbContext : DbContext

{

    public DbSet<Product> Products => Set<Product>();

    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)

    {

        // Apply all configurations from assembly

        modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);

        // Global query filters

        modelBuilder.Entity<Product>().HasQueryFilter(p => !p.IsDeleted);

    }

}

// Entity configuration

public class ProductConfiguration : IEntityTypeConfiguration<Product>

{

    public void Configure(EntityTypeBuilder<Product> builder)

    {

        builder.ToTable("Products");

        builder.HasKey(p => p.Id);

        builder.Property(p => p.Id).HasMaxLength(40);

        builder.Property(p => p.Name).HasMaxLength(200).IsRequired();

        builder.Property(p => p.Price).HasPrecision(18, 2);

        builder.HasIndex(p => p.Sku).IsUnique();

        builder.HasIndex(p => new { p.CategoryId, p.Name });

        builder.HasMany(p => p.OrderItems)

            .WithOne(oi => oi.Product)

            .HasForeignKey(oi => oi.ProductId);

    }

}

// Repository with EF Core

public class ProductRepository : IProductRepository

{

    private readonly AppDbContext _context;

    public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)

    {

        return await _context.Products

            .AsNoTracking()

            .FirstOrDefaultAsync(p => p.Id == id, ct);

    }

    public async Task<IReadOnlyList<Product>> SearchAsync(

        ProductSearchCriteria criteria,

        CancellationToken ct = default)

    {

        var query = _context.Products.AsNoTracking();

        if (!string.IsNullOrWhiteSpace(criteria.SearchTerm))

            query = query.Where(p => EF.Functions.Like(p.Name, $"%{criteria.SearchTerm}%"));

        if (criteria.CategoryId.HasValue)

            query = query.Where(p => p.CategoryId == criteria.CategoryId);

        if (criteria.MinPrice.HasValue)

            query = query.Where(p => p.Price >= criteria.MinPrice);

        if (criteria.MaxPrice.HasValue)

            query = query.Where(p => p.Price <= criteria.MaxPrice);

        return await query

            .OrderBy(p => p.Name)

            .Skip((criteria.Page - 1) * criteria.PageSize)

            .Take(criteria.PageSize)

            .ToListAsync(ct);

    }

}

Dapper for Performance

public class DapperProductRepository : IProductRepository

{

    private readonly IDbConnection _connection;

    public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)

    {

        const string sql = """

            SELECT Id, Name, Sku, Price, CategoryId, Stock, CreatedAt

            FROM Products

            WHERE Id = @Id AND IsDeleted = 0

            """;

        return await _connection.QueryFirstOrDefaultAsync<Product>(

            new CommandDefinition(sql, new { Id = id }, cancellationToken: ct));

    }

    public async Task<IReadOnlyList<Product>> SearchAsync(

        ProductSearchCriteria criteria,

        CancellationToken ct = default)

    {

        var sql = new StringBuilder("""

            SELECT Id, Name, Sku, Price, CategoryId, Stock, CreatedAt

            FROM Products

            WHERE IsDeleted = 0

            """);

        var parameters = new DynamicParameters();

        if (!string.IsNullOrWhiteSpace(criteria.SearchTerm))

        {

            sql.Append(" AND Name LIKE @SearchTerm");

            parameters.Add("SearchTerm", $"%{criteria.SearchTerm}%");

        }

        if (criteria.CategoryId.HasValue)

        {

            sql.Append(" AND CategoryId = @CategoryId");

            parameters.Add("CategoryId", criteria.CategoryId);

        }

        if (criteria.MinPrice.HasValue)

        {

            sql.Append(" AND Price >= @MinPrice");

            parameters.Add("MinPrice", criteria.MinPrice);

        }

        if (criteria.MaxPrice.HasValue)

        {

            sql.Append(" AND Price <= @MaxPrice");

            parameters.Add("MaxPrice", criteria.MaxPrice);

        }

        sql.Append(" ORDER BY Name OFFSET @Offset ROWS FETCH NEXT @PageSize ROWS ONLY");

        parameters.Add("Offset", (criteria.Page - 1) * criteria.PageSize);

        parameters.Add("PageSize", criteria.PageSize);

        var results = await _connection.QueryAsync<Product>(

            new CommandDefinition(sql.ToString(), parameters, cancellationToken: ct));

        return results.ToList();

    }

    // Multi-mapping for related data

    public async Task<Order?> GetOrderWithItemsAsync(int orderId, CancellationToken ct = default)

    {

        const string sql = """

            SELECT o.*, oi.*, p.*

            FROM Orders o

            LEFT JOIN OrderItems oi ON o.Id = oi.OrderId

            LEFT JOIN Products p ON oi.ProductId = p.Id

            WHERE o.Id = @OrderId

            """;

        var orderDictionary = new Dictionary<int, Order>();

        await _connection.QueryAsync<Order, OrderItem, Product, Order>(

            new CommandDefinition(sql, new { OrderId = orderId }, cancellationToken: ct),

            (order, item, product) =>

            {

                if (!orderDictionary.TryGetValue(order.Id, out var existingOrder))

                {

                    existingOrder = order;

                    existingOrder.Items = new List<OrderItem>();

                    orderDictionary.Add(order.Id, existingOrder);

                }

                if (item != null)

                {

                    item.Product = product;

                    existingOrder.Items.Add(item);

                }

                return existingOrder;

            },

            splitOn: "Id,Id");

        return orderDictionary.Values.FirstOrDefault();

    }

}

Caching Patterns

Multi-Level Cache with Redis

public class CachedProductService : IProductService

{

    private readonly IProductRepository _repository;

    private readonly IMemoryCache _memoryCache;

    private readonly IDistributedCache _distributedCache;

    private readonly ILogger<CachedProductService> _logger;

    private static readonly TimeSpan MemoryCacheDuration = TimeSpan.FromMinutes(1);

    private static readonly TimeSpan DistributedCacheDuration = TimeSpan.FromMinutes(15);

    public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)

    {

        var cacheKey = $"product:{id}";

        // L1: Memory cache (in-process, fastest)

        if (_memoryCache.TryGetValue(cacheKey, out Product? cached))

        {

            _logger.LogDebug("L1 cache hit for {CacheKey}", cacheKey);

            return cached;

        }

        // L2: Distributed cache (Redis)

        var distributed = await _distributedCache.GetStringAsync(cacheKey, ct);

        if (distributed != null)

        {

            _logger.LogDebug("L2 cache hit for {CacheKey}", cacheKey);

            var product = JsonSerializer.Deserialize<Product>(distributed);

            // Populate L1

            _memoryCache.Set(cacheKey, product, MemoryCacheDuration);

            return product;

        }

        // L3: Database

        _logger.LogDebug("Cache miss for {CacheKey}, fetching from database", cacheKey);

        var fromDb = await _repository.GetByIdAsync(id, ct);

        if (fromDb != null)

        {

            var serialized = JsonSerializer.Serialize(fromDb);

            // Populate both caches

            await _distributedCache.SetStringAsync(

                cacheKey,

                serialized,

                new DistributedCacheEntryOptions

                {

                    AbsoluteExpirationRelativeToNow = DistributedCacheDuration

                },

                ct);

            _memoryCache.Set(cacheKey, fromDb, MemoryCacheDuration);

        }

        return fromDb;

    }

    public async Task InvalidateAsync(string id, CancellationToken ct = default)

    {

        var cacheKey = $"product:{id}";

        _memoryCache.Remove(cacheKey);

        await _distributedCache.RemoveAsync(cacheKey, ct);

        _logger.LogInformation("Invalidated cache for {CacheKey}", cacheKey);

    }

}

// Stale-while-revalidate pattern

public class StaleWhileRevalidateCache<T>

{

    private readonly IDistributedCache _cache;

    private readonly TimeSpan _freshDuration;

    private readonly TimeSpan _staleDuration;

    public async Task<T?> GetOrCreateAsync(

        string key,

        Func<CancellationToken, Task<T>> factory,

        CancellationToken ct = default)

    {

        var cached = await _cache.GetStringAsync(key, ct);

        if (cached != null)

        {

            var entry = JsonSerializer.Deserialize<CacheEntry<T>>(cached)!;

            if (entry.IsStale &#x26;&#x26; !entry.IsExpired)

            {

                // Return stale data immediately, refresh in background

                _ = Task.Run(async () =>

                {

                    var fresh = await factory(CancellationToken.None);

                    await SetAsync(key, fresh, CancellationToken.None);

                });

            }

            if (!entry.IsExpired)

                return entry.Value;

        }

        // Cache miss or expired

        var value = await factory(ct);

        await SetAsync(key, value, ct);

        return value;

    }

    private record CacheEntry<TValue>(TValue Value, DateTime CreatedAt)

    {

        public bool IsStale => DateTime.UtcNow - CreatedAt > _freshDuration;

        public bool IsExpired => DateTime.UtcNow - CreatedAt > _staleDuration;

    }

}

Testing Patterns

Unit Tests with xUnit and Moq

public class OrderServiceTests

{

    private readonly Mock<IOrderRepository> _mockRepository;

    private readonly Mock<IStockService> _mockStockService;

    private readonly Mock<IValidator<CreateOrderRequest>> _mockValidator;

    private readonly OrderService _sut; // System Under Test

    public OrderServiceTests()

    {

        _mockRepository = new Mock<IOrderRepository>();

        _mockStockService = new Mock<IStockService>();

        _mockValidator = new Mock<IValidator<CreateOrderRequest>>();

        // Default: validation passes

        _mockValidator

            .Setup(v => v.ValidateAsync(It.IsAny<CreateOrderRequest>(), It.IsAny<CancellationToken>()))

            .ReturnsAsync(new ValidationResult());

        _sut = new OrderService(

            _mockRepository.Object,

            _mockStockService.Object,

            _mockValidator.Object);

    }

    [Fact]

    public async Task CreateOrderAsync_WithValidRequest_ReturnsSuccess()

    {

        // Arrange

        var request = new CreateOrderRequest

        {

            ProductId = "PROD-001",

            Quantity = 5,

            CustomerOrderCode = "ORD-2024-001"

        };

        _mockStockService

            .Setup(s => s.CheckAsync("PROD-001", 5, It.IsAny<CancellationToken>()))

            .ReturnsAsync(new StockResult { IsAvailable = true, Available = 10 });

        _mockRepository

            .Setup(r => r.CreateAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()))

            .ReturnsAsync(new Order { Id = 1, CustomerOrderCode = "ORD-2024-001" });

        // Act

        var result = await _sut.CreateOrderAsync(request);

        // Assert

        Assert.True(result.IsSuccess);

        Assert.NotNull(result.Value);

        Assert.Equal(1, result.Value.Id);

        _mockRepository.Verify(

            r => r.CreateAsync(It.Is<Order>(o => o.CustomerOrderCode == "ORD-2024-001"),

            It.IsAny<CancellationToken>()),

            Times.Once);

    }

    [Fact]

    public async Task CreateOrderAsync_WithInsufficientStock_ReturnsFailure()

    {

        // Arrange

        var request = new CreateOrderRequest { ProductId = "PROD-001", Quantity = 100 };

        _mockStockService

            .Setup(s => s.CheckAsync(It.IsAny<string>(), It.IsAny<int>(), It.IsAny<CancellationToken>()))

            .ReturnsAsync(new StockResult { IsAvailable = false, Available = 5 });

        // Act

        var result = await _sut.CreateOrderAsync(request);

        // Assert

        Assert.False(result.IsSuccess);

        Assert.Equal("INSUFFICIENT_STOCK", result.ErrorCode);

        Assert.Contains("5 available", result.Error);

        _mockRepository.Verify(

            r => r.CreateAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()),

            Times.Never);

    }

    [Theory]

    [InlineData(0)]

    [InlineData(-1)]

    [InlineData(-100)]

    public async Task CreateOrderAsync_WithInvalidQuantity_ReturnsValidationError(int quantity)

    {

        // Arrange

        var request = new CreateOrderRequest { ProductId = "PROD-001", Quantity = quantity };

        _mockValidator

            .Setup(v => v.ValidateAsync(request, It.IsAny<CancellationToken>()))

            .ReturnsAsync(new ValidationResult(new[]

            {

                new ValidationFailure("Quantity", "Quantity must be greater than 0")

            }));

        // Act

        var result = await _sut.CreateOrderAsync(request);

        // Assert

        Assert.False(result.IsSuccess);

        Assert.Equal("VALIDATION_ERROR", result.ErrorCode);

    }

}

Integration Tests with WebApplicationFactory

public class ProductsApiTests : IClassFixture<WebApplicationFactory<Program>>

{

    private readonly WebApplicationFactory<Program> _factory;

    private readonly HttpClient _client;

    public ProductsApiTests(WebApplicationFactory<Program> factory)

    {

        _factory = factory.WithWebHostBuilder(builder =>

        {

            builder.ConfigureServices(services =>

            {

                // Replace real database with in-memory

                services.RemoveAll<DbContextOptions<AppDbContext>>();

                services.AddDbContext<AppDbContext>(options =>

                    options.UseInMemoryDatabase("TestDb"));

                // Replace Redis with memory cache

                services.RemoveAll<IDistributedCache>();

                services.AddDistributedMemoryCache();

            });

        });

        _client = _factory.CreateClient();

    }

    [Fact]

    public async Task GetProduct_WithValidId_ReturnsProduct()

    {

        // Arrange

        using var scope = _factory.Services.CreateScope();

        var context = scope.ServiceProvider.GetRequiredService<AppDbContext>();

        context.Products.Add(new Product

        {

            Id = "TEST-001",

            Name = "Test Product",

            Price = 99.99m

        });

        await context.SaveChangesAsync();

        // Act

        var response = await _client.GetAsync("/api/products/TEST-001");

        // Assert

        response.EnsureSuccessStatusCode();

        var product = await response.Content.ReadFromJsonAsync<Product>();

        Assert.Equal("Test Product", product!.Name);

    }

    [Fact]

    public async Task GetProduct_WithInvalidId_Returns404()

    {

        // Act

        var response = await _client.GetAsync("/api/products/NONEXISTENT");

        // Assert

        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);

    }

}

Best Practices

DO

• Use async/await all the way through the call stack

• Inject dependencies through constructor injection

• Use IOptions for typed configuration

• Return Result types instead of throwing exceptions for business logic

• Use CancellationToken in all async methods

• Prefer Dapper for read-heavy, performance-critical queries

• Use EF Core for complex domain models with change tracking

• Cache aggressively with proper invalidation strategies

• Write unit tests for business logic, integration tests for APIs

• Use record types for DTOs and immutable data

DON'T

• Don't block on async with .Result or .Wait()

• Don't use async void except for event handlers

• Don't catch generic Exception without re-throwing or logging

• Don't hardcode configuration values

• Don't expose EF entities directly in APIs (use DTOs)

• Don't forget AsNoTracking() for read-only queries

• Don't ignore CancellationToken parameters

• Don't create new HttpClient() manually (use IHttpClientFactory)

• Don't mix sync and async code unnecessarily

• Don't skip validation at API boundaries

Common Pitfalls

• N+1 Queries: Use .Include() or explicit joins

• Memory Leaks: Dispose IDisposable resources, use using

• Deadlocks: Don't mix sync and async, use ConfigureAwait(false) in libraries

• Over-fetching: Select only needed columns, use projections

• Missing Indexes: Check query plans, add indexes for common filters

• Timeout Issues: Configure appropriate timeouts for HTTP clients

• Cache Stampede: Use distributed locks for cache population