1// Service registration by lifetime
 2public static class ServiceCollectionExtensions
 3{
 4    public static IServiceCollection AddApplicationServices(
 5        this IServiceCollection services,
 6        IConfiguration configuration)
 7    {
 8        // Scoped: One instance per HTTP request
 9        services.AddScoped<IProductService, ProductService>();
10        services.AddScoped<IOrderService, OrderService>();
11
12        // Singleton: One instance for app lifetime
13        services.AddSingleton<ICacheService, RedisCacheService>();
14        services.AddSingleton<IConnectionMultiplexer>(_ =>
15            ConnectionMultiplexer.Connect(configuration["Redis:Connection"]!));
16
17        // Transient: New instance every time
18        services.AddTransient<IValidator<CreateOrderRequest>, CreateOrderValidator>();
19
20        // Options pattern for configuration
21        services.Configure<CatalogOptions>(configuration.GetSection("Catalog"));
22        services.Configure<RedisOptions>(configuration.GetSection("Redis"));
23
24        // Factory pattern for conditional creation
25        services.AddScoped<IPriceCalculator>(sp =>
26        {
27            var options = sp.GetRequiredService<IOptions<PricingOptions>>().Value;
28            return options.UseNewEngine
29                ? sp.GetRequiredService<NewPriceCalculator>()
30                : sp.GetRequiredService<LegacyPriceCalculator>();
31        });
32
33        // Keyed services (.NET 8+)
34        services.AddKeyedScoped<IPaymentProcessor, StripeProcessor>("stripe");
35        services.AddKeyedScoped<IPaymentProcessor, PayPalProcessor>("paypal");
36
37        return services;
38    }
39}
40
41// Usage with keyed services
42public class CheckoutService
43{
44    public CheckoutService(
45        [FromKeyedServices("stripe")] IPaymentProcessor stripeProcessor)
46    {
47        _processor = stripeProcessor;
48    }
49}

 1// ✅ CORRECT: Async all the way down
 2public async Task<Product> GetProductAsync(string id, CancellationToken ct = default)
 3{
 4    return await _repository.GetByIdAsync(id, ct);
 5}
 6
 7// ✅ CORRECT: Parallel execution with WhenAll
 8public async Task<(Stock, Price)> GetStockAndPriceAsync(
 9    string productId,
10    CancellationToken ct = default)
11{
12    var stockTask = _stockService.GetAsync(productId, ct);
13    var priceTask = _priceService.GetAsync(productId, ct);
14
15    await Task.WhenAll(stockTask, priceTask);
16
17    return (await stockTask, await priceTask);
18}
19
20// ✅ CORRECT: ConfigureAwait in libraries
21public async Task<T> LibraryMethodAsync<T>(CancellationToken ct = default)
22{
23    var result = await _httpClient.GetAsync(url, ct).ConfigureAwait(false);
24    return await result.Content.ReadFromJsonAsync<T>(ct).ConfigureAwait(false);
25}
26
27// ✅ CORRECT: ValueTask for hot paths with caching
28public ValueTask<Product?> GetCachedProductAsync(string id)
29{
30    if (_cache.TryGetValue(id, out Product? product))
31        return ValueTask.FromResult(product);
32
33    return new ValueTask<Product?>(GetFromDatabaseAsync(id));
34}
35
36// ❌ WRONG: Blocking on async (deadlock risk)
37var result = GetProductAsync(id).Result;  // NEVER do this
38var result2 = GetProductAsync(id).GetAwaiter().GetResult(); // Also bad
39
40// ❌ WRONG: async void (except event handlers)
41public async void ProcessOrder() { }  // Exceptions are lost
42
43// ❌ WRONG: Unnecessary Task.Run for already async code
44await Task.Run(async () => await GetDataAsync());  // Wastes thread

 1// Configuration classes
 2public class CatalogOptions
 3{
 4    public const string SectionName = "Catalog";
 5
 6    public int DefaultPageSize { get; set; } = 50;
 7    public int MaxPageSize { get; set; } = 200;
 8    public TimeSpan CacheDuration { get; set; } = TimeSpan.FromMinutes(15);
 9    public bool EnableEnrichment { get; set; } = true;
10}
11
12public class RedisOptions
13{
14    public const string SectionName = "Redis";
15
16    public string Connection { get; set; } = "localhost:6379";
17    public string KeyPrefix { get; set; } = "mcp:";
18    public int Database { get; set; } = 0;
19}
20
21// appsettings.json
22{
23    "Catalog": {
24        "DefaultPageSize": 50,
25        "MaxPageSize": 200,
26        "CacheDuration": "00:15:00",
27        "EnableEnrichment": true
28    },
29    "Redis": {
30        "Connection": "localhost:6379",
31        "KeyPrefix": "mcp:",
32        "Database": 0
33    }
34}
35
36// Registration
37services.Configure<CatalogOptions>(configuration.GetSection(CatalogOptions.SectionName));
38services.Configure<RedisOptions>(configuration.GetSection(RedisOptions.SectionName));
39
40// Usage with IOptions (singleton, read once at startup)
41public class CatalogService
42{
43    private readonly CatalogOptions _options;
44
45    public CatalogService(IOptions<CatalogOptions> options)
46    {
47        _options = options.Value;
48    }
49}
50
51// Usage with IOptionsSnapshot (scoped, re-reads on each request)
52public class DynamicService
53{
54    private readonly CatalogOptions _options;
55
56    public DynamicService(IOptionsSnapshot<CatalogOptions> options)
57    {
58        _options = options.Value;  // Fresh value per request
59    }
60}
61
62// Usage with IOptionsMonitor (singleton, notified on changes)
63public class MonitoredService
64{
65    private CatalogOptions _options;
66
67    public MonitoredService(IOptionsMonitor<CatalogOptions> monitor)
68    {
69        _options = monitor.CurrentValue;
70        monitor.OnChange(newOptions => _options = newOptions);
71    }
72}

 1// Generic Result type
 2public class Result<T>
 3{
 4    public bool IsSuccess { get; }
 5    public T? Value { get; }
 6    public string? Error { get; }
 7    public string? ErrorCode { get; }
 8
 9    private Result(bool isSuccess, T? value, string? error, string? errorCode)
10    {
11        IsSuccess = isSuccess;
12        Value = value;
13        Error = error;
14        ErrorCode = errorCode;
15    }
16
17    public static Result<T> Success(T value) => new(true, value, null, null);
18    public static Result<T> Failure(string error, string? code = null) => new(false, default, error, code);
19
20    public Result<TNew> Map<TNew>(Func<T, TNew> mapper) =>
21        IsSuccess ? Result<TNew>.Success(mapper(Value!)) : Result<TNew>.Failure(Error!, ErrorCode);
22
23    public async Task<Result<TNew>> MapAsync<TNew>(Func<T, Task<TNew>> mapper) =>
24        IsSuccess ? Result<TNew>.Success(await mapper(Value!)) : Result<TNew>.Failure(Error!, ErrorCode);
25}
26
27// Usage in service
28public async Task<Result<Order>> CreateOrderAsync(CreateOrderRequest request, CancellationToken ct)
29{
30    // Validation
31    var validation = await _validator.ValidateAsync(request, ct);
32    if (!validation.IsValid)
33        return Result<Order>.Failure(
34            validation.Errors.First().ErrorMessage,
35            "VALIDATION_ERROR");
36
37    // Business rule check
38    var stock = await _stockService.CheckAsync(request.ProductId, request.Quantity, ct);
39    if (!stock.IsAvailable)
40        return Result<Order>.Failure(
41            $"Insufficient stock: {stock.Available} available, {request.Quantity} requested",
42            "INSUFFICIENT_STOCK");
43
44    // Create order
45    var order = await _repository.CreateAsync(request.ToEntity(), ct);
46
47    return Result<Order>.Success(order);
48}
49
50// Usage in controller/endpoint
51app.MapPost("/orders", async (
52    CreateOrderRequest request,
53    IOrderService orderService,
54    CancellationToken ct) =>
55{
56    var result = await orderService.CreateOrderAsync(request, ct);
57
58    return result.IsSuccess
59        ? Results.Created($"/orders/{result.Value!.Id}", result.Value)
60        : Results.BadRequest(new { error = result.Error, code = result.ErrorCode });
61});

 1// DbContext configuration
 2public class AppDbContext : DbContext
 3{
 4    public DbSet<Product> Products => Set<Product>();
 5    public DbSet<Order> Orders => Set<Order>();
 6
 7    protected override void OnModelCreating(ModelBuilder modelBuilder)
 8    {
 9        // Apply all configurations from assembly
10        modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
11
12        // Global query filters
13        modelBuilder.Entity<Product>().HasQueryFilter(p => !p.IsDeleted);
14    }
15}
16
17// Entity configuration
18public class ProductConfiguration : IEntityTypeConfiguration<Product>
19{
20    public void Configure(EntityTypeBuilder<Product> builder)
21    {
22        builder.ToTable("Products");
23
24        builder.HasKey(p => p.Id);
25        builder.Property(p => p.Id).HasMaxLength(40);
26        builder.Property(p => p.Name).HasMaxLength(200).IsRequired();
27        builder.Property(p => p.Price).HasPrecision(18, 2);
28
29        builder.HasIndex(p => p.Sku).IsUnique();
30        builder.HasIndex(p => new { p.CategoryId, p.Name });
31
32        builder.HasMany(p => p.OrderItems)
33            .WithOne(oi => oi.Product)
34            .HasForeignKey(oi => oi.ProductId);
35    }
36}
37
38// Repository with EF Core
39public class ProductRepository : IProductRepository
40{
41    private readonly AppDbContext _context;
42
43    public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
44    {
45        return await _context.Products
46            .AsNoTracking()
47            .FirstOrDefaultAsync(p => p.Id == id, ct);
48    }
49
50    public async Task<IReadOnlyList<Product>> SearchAsync(
51        ProductSearchCriteria criteria,
52        CancellationToken ct = default)
53    {
54        var query = _context.Products.AsNoTracking();
55
56        if (!string.IsNullOrWhiteSpace(criteria.SearchTerm))
57            query = query.Where(p => EF.Functions.Like(p.Name, $"%{criteria.SearchTerm}%"));
58
59        if (criteria.CategoryId.HasValue)
60            query = query.Where(p => p.CategoryId == criteria.CategoryId);
61
62        if (criteria.MinPrice.HasValue)
63            query = query.Where(p => p.Price >= criteria.MinPrice);
64
65        if (criteria.MaxPrice.HasValue)
66            query = query.Where(p => p.Price <= criteria.MaxPrice);
67
68        return await query
69            .OrderBy(p => p.Name)
70            .Skip((criteria.Page - 1) * criteria.PageSize)
71            .Take(criteria.PageSize)
72            .ToListAsync(ct);
73    }
74}

 1public class DapperProductRepository : IProductRepository
 2{
 3    private readonly IDbConnection _connection;
 4
 5    public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
 6    {
 7        const string sql = """
 8            SELECT Id, Name, Sku, Price, CategoryId, Stock, CreatedAt
 9            FROM Products
10            WHERE Id = @Id AND IsDeleted = 0
11            """;
12
13        return await _connection.QueryFirstOrDefaultAsync<Product>(
14            new CommandDefinition(sql, new { Id = id }, cancellationToken: ct));
15    }
16
17    public async Task<IReadOnlyList<Product>> SearchAsync(
18        ProductSearchCriteria criteria,
19        CancellationToken ct = default)
20    {
21        var sql = new StringBuilder("""
22            SELECT Id, Name, Sku, Price, CategoryId, Stock, CreatedAt
23            FROM Products
24            WHERE IsDeleted = 0
25            """);
26
27        var parameters = new DynamicParameters();
28
29        if (!string.IsNullOrWhiteSpace(criteria.SearchTerm))
30        {
31            sql.Append(" AND Name LIKE @SearchTerm");
32            parameters.Add("SearchTerm", $"%{criteria.SearchTerm}%");
33        }
34
35        if (criteria.CategoryId.HasValue)
36        {
37            sql.Append(" AND CategoryId = @CategoryId");
38            parameters.Add("CategoryId", criteria.CategoryId);
39        }
40
41        if (criteria.MinPrice.HasValue)
42        {
43            sql.Append(" AND Price >= @MinPrice");
44            parameters.Add("MinPrice", criteria.MinPrice);
45        }
46
47        if (criteria.MaxPrice.HasValue)
48        {
49            sql.Append(" AND Price <= @MaxPrice");
50            parameters.Add("MaxPrice", criteria.MaxPrice);
51        }
52
53        sql.Append(" ORDER BY Name OFFSET @Offset ROWS FETCH NEXT @PageSize ROWS ONLY");
54        parameters.Add("Offset", (criteria.Page - 1) * criteria.PageSize);
55        parameters.Add("PageSize", criteria.PageSize);
56
57        var results = await _connection.QueryAsync<Product>(
58            new CommandDefinition(sql.ToString(), parameters, cancellationToken: ct));
59
60        return results.ToList();
61    }
62
63    // Multi-mapping for related data
64    public async Task<Order?> GetOrderWithItemsAsync(int orderId, CancellationToken ct = default)
65    {
66        const string sql = """
67            SELECT o.*, oi.*, p.*
68            FROM Orders o
69            LEFT JOIN OrderItems oi ON o.Id = oi.OrderId
70            LEFT JOIN Products p ON oi.ProductId = p.Id
71            WHERE o.Id = @OrderId
72            """;
73
74        var orderDictionary = new Dictionary<int, Order>();
75
76        await _connection.QueryAsync<Order, OrderItem, Product, Order>(
77            new CommandDefinition(sql, new { OrderId = orderId }, cancellationToken: ct),
78            (order, item, product) =>
79            {
80                if (!orderDictionary.TryGetValue(order.Id, out var existingOrder))
81                {
82                    existingOrder = order;
83                    existingOrder.Items = new List<OrderItem>();
84                    orderDictionary.Add(order.Id, existingOrder);
85                }
86
87                if (item != null)
88                {
89                    item.Product = product;
90                    existingOrder.Items.Add(item);
91                }
92
93                return existingOrder;
94            },
95            splitOn: "Id,Id");
96
97        return orderDictionary.Values.FirstOrDefault();
98    }
99}

  1public class CachedProductService : IProductService
  2{
  3    private readonly IProductRepository _repository;
  4    private readonly IMemoryCache _memoryCache;
  5    private readonly IDistributedCache _distributedCache;
  6    private readonly ILogger<CachedProductService> _logger;
  7
  8    private static readonly TimeSpan MemoryCacheDuration = TimeSpan.FromMinutes(1);
  9    private static readonly TimeSpan DistributedCacheDuration = TimeSpan.FromMinutes(15);
 10
 11    public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
 12    {
 13        var cacheKey = $"product:{id}";
 14
 15        // L1: Memory cache (in-process, fastest)
 16        if (_memoryCache.TryGetValue(cacheKey, out Product? cached))
 17        {
 18            _logger.LogDebug("L1 cache hit for {CacheKey}", cacheKey);
 19            return cached;
 20        }
 21
 22        // L2: Distributed cache (Redis)
 23        var distributed = await _distributedCache.GetStringAsync(cacheKey, ct);
 24        if (distributed != null)
 25        {
 26            _logger.LogDebug("L2 cache hit for {CacheKey}", cacheKey);
 27            var product = JsonSerializer.Deserialize<Product>(distributed);
 28
 29            // Populate L1
 30            _memoryCache.Set(cacheKey, product, MemoryCacheDuration);
 31            return product;
 32        }
 33
 34        // L3: Database
 35        _logger.LogDebug("Cache miss for {CacheKey}, fetching from database", cacheKey);
 36        var fromDb = await _repository.GetByIdAsync(id, ct);
 37
 38        if (fromDb != null)
 39        {
 40            var serialized = JsonSerializer.Serialize(fromDb);
 41
 42            // Populate both caches
 43            await _distributedCache.SetStringAsync(
 44                cacheKey,
 45                serialized,
 46                new DistributedCacheEntryOptions
 47                {
 48                    AbsoluteExpirationRelativeToNow = DistributedCacheDuration
 49                },
 50                ct);
 51
 52            _memoryCache.Set(cacheKey, fromDb, MemoryCacheDuration);
 53        }
 54
 55        return fromDb;
 56    }
 57
 58    public async Task InvalidateAsync(string id, CancellationToken ct = default)
 59    {
 60        var cacheKey = $"product:{id}";
 61
 62        _memoryCache.Remove(cacheKey);
 63        await _distributedCache.RemoveAsync(cacheKey, ct);
 64
 65        _logger.LogInformation("Invalidated cache for {CacheKey}", cacheKey);
 66    }
 67}
 68
 69// Stale-while-revalidate pattern
 70public class StaleWhileRevalidateCache<T>
 71{
 72    private readonly IDistributedCache _cache;
 73    private readonly TimeSpan _freshDuration;
 74    private readonly TimeSpan _staleDuration;
 75
 76    public async Task<T?> GetOrCreateAsync(
 77        string key,
 78        Func<CancellationToken, Task<T>> factory,
 79        CancellationToken ct = default)
 80    {
 81        var cached = await _cache.GetStringAsync(key, ct);
 82
 83        if (cached != null)
 84        {
 85            var entry = JsonSerializer.Deserialize<CacheEntry<T>>(cached)!;
 86
 87            if (entry.IsStale && !entry.IsExpired)
 88            {
 89                // Return stale data immediately, refresh in background
 90                _ = Task.Run(async () =>
 91                {
 92                    var fresh = await factory(CancellationToken.None);
 93                    await SetAsync(key, fresh, CancellationToken.None);
 94                });
 95            }
 96
 97            if (!entry.IsExpired)
 98                return entry.Value;
 99        }
100
101        // Cache miss or expired
102        var value = await factory(ct);
103        await SetAsync(key, value, ct);
104        return value;
105    }
106
107    private record CacheEntry<TValue>(TValue Value, DateTime CreatedAt)
108    {
109        public bool IsStale => DateTime.UtcNow - CreatedAt > _freshDuration;
110        public bool IsExpired => DateTime.UtcNow - CreatedAt > _staleDuration;
111    }
112}

  1public class OrderServiceTests
  2{
  3    private readonly Mock<IOrderRepository> _mockRepository;
  4    private readonly Mock<IStockService> _mockStockService;
  5    private readonly Mock<IValidator<CreateOrderRequest>> _mockValidator;
  6    private readonly OrderService _sut; // System Under Test
  7
  8    public OrderServiceTests()
  9    {
 10        _mockRepository = new Mock<IOrderRepository>();
 11        _mockStockService = new Mock<IStockService>();
 12        _mockValidator = new Mock<IValidator<CreateOrderRequest>>();
 13
 14        // Default: validation passes
 15        _mockValidator
 16            .Setup(v => v.ValidateAsync(It.IsAny<CreateOrderRequest>(), It.IsAny<CancellationToken>()))
 17            .ReturnsAsync(new ValidationResult());
 18
 19        _sut = new OrderService(
 20            _mockRepository.Object,
 21            _mockStockService.Object,
 22            _mockValidator.Object);
 23    }
 24
 25    [Fact]
 26    public async Task CreateOrderAsync_WithValidRequest_ReturnsSuccess()
 27    {
 28        // Arrange
 29        var request = new CreateOrderRequest
 30        {
 31            ProductId = "PROD-001",
 32            Quantity = 5,
 33            CustomerOrderCode = "ORD-2024-001"
 34        };
 35
 36        _mockStockService
 37            .Setup(s => s.CheckAsync("PROD-001", 5, It.IsAny<CancellationToken>()))
 38            .ReturnsAsync(new StockResult { IsAvailable = true, Available = 10 });
 39
 40        _mockRepository
 41            .Setup(r => r.CreateAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()))
 42            .ReturnsAsync(new Order { Id = 1, CustomerOrderCode = "ORD-2024-001" });
 43
 44        // Act
 45        var result = await _sut.CreateOrderAsync(request);
 46
 47        // Assert
 48        Assert.True(result.IsSuccess);
 49        Assert.NotNull(result.Value);
 50        Assert.Equal(1, result.Value.Id);
 51
 52        _mockRepository.Verify(
 53            r => r.CreateAsync(It.Is<Order>(o => o.CustomerOrderCode == "ORD-2024-001"),
 54            It.IsAny<CancellationToken>()),
 55            Times.Once);
 56    }
 57
 58    [Fact]
 59    public async Task CreateOrderAsync_WithInsufficientStock_ReturnsFailure()
 60    {
 61        // Arrange
 62        var request = new CreateOrderRequest { ProductId = "PROD-001", Quantity = 100 };
 63
 64        _mockStockService
 65            .Setup(s => s.CheckAsync(It.IsAny<string>(), It.IsAny<int>(), It.IsAny<CancellationToken>()))
 66            .ReturnsAsync(new StockResult { IsAvailable = false, Available = 5 });
 67
 68        // Act
 69        var result = await _sut.CreateOrderAsync(request);
 70
 71        // Assert
 72        Assert.False(result.IsSuccess);
 73        Assert.Equal("INSUFFICIENT_STOCK", result.ErrorCode);
 74        Assert.Contains("5 available", result.Error);
 75
 76        _mockRepository.Verify(
 77            r => r.CreateAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()),
 78            Times.Never);
 79    }
 80
 81    [Theory]
 82    [InlineData(0)]
 83    [InlineData(-1)]
 84    [InlineData(-100)]
 85    public async Task CreateOrderAsync_WithInvalidQuantity_ReturnsValidationError(int quantity)
 86    {
 87        // Arrange
 88        var request = new CreateOrderRequest { ProductId = "PROD-001", Quantity = quantity };
 89
 90        _mockValidator
 91            .Setup(v => v.ValidateAsync(request, It.IsAny<CancellationToken>()))
 92            .ReturnsAsync(new ValidationResult(new[]
 93            {
 94                new ValidationFailure("Quantity", "Quantity must be greater than 0")
 95            }));
 96
 97        // Act
 98        var result = await _sut.CreateOrderAsync(request);
 99
100        // Assert
101        Assert.False(result.IsSuccess);
102        Assert.Equal("VALIDATION_ERROR", result.ErrorCode);
103    }
104}

 1public class ProductsApiTests : IClassFixture<WebApplicationFactory<Program>>
 2{
 3    private readonly WebApplicationFactory<Program> _factory;
 4    private readonly HttpClient _client;
 5
 6    public ProductsApiTests(WebApplicationFactory<Program> factory)
 7    {
 8        _factory = factory.WithWebHostBuilder(builder =>
 9        {
10            builder.ConfigureServices(services =>
11            {
12                // Replace real database with in-memory
13                services.RemoveAll<DbContextOptions<AppDbContext>>();
14                services.AddDbContext<AppDbContext>(options =>
15                    options.UseInMemoryDatabase("TestDb"));
16
17                // Replace Redis with memory cache
18                services.RemoveAll<IDistributedCache>();
19                services.AddDistributedMemoryCache();
20            });
21        });
22
23        _client = _factory.CreateClient();
24    }
25
26    [Fact]
27    public async Task GetProduct_WithValidId_ReturnsProduct()
28    {
29        // Arrange
30        using var scope = _factory.Services.CreateScope();
31        var context = scope.ServiceProvider.GetRequiredService<AppDbContext>();
32
33        context.Products.Add(new Product
34        {
35            Id = "TEST-001",
36            Name = "Test Product",
37            Price = 99.99m
38        });
39        await context.SaveChangesAsync();
40
41        // Act
42        var response = await _client.GetAsync("/api/products/TEST-001");
43
44        // Assert
45        response.EnsureSuccessStatusCode();
46        var product = await response.Content.ReadFromJsonAsync<Product>();
47        Assert.Equal("Test Product", product!.Name);
48    }
49
50    [Fact]
51    public async Task GetProduct_WithInvalidId_Returns404()
52    {
53        // Act
54        var response = await _client.GetAsync("/api/products/NONEXISTENT");
55
56        // Assert
57        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
58    }
59}