quantity, CancellationToken ct);
}
### Step 2: Register with Explicit Lifetimes
Lifetimes must align with state ownership and thread safety. Register in the composition root (`Program.cs`), never in feature modules or controllers.
```csharp
var builder = WebApplication.CreateBuilder(args);
// Stateless, thread-safe, shared across application
builder.Services.AddSingleton<IOrderProcessor, OrderProcessor>();
// Request-scoped, holds per-request state (e.g., EF Core DbContext)
builder.Services.AddScoped<IInventoryService, InventoryService>();
// Ephemeral, created per resolution, must be disposed if implementing IDisposable
builder.Services.AddTransient<IEmailGateway, SmtpEmailGateway>();
Step 3: Inject via Constructors Only
Property or method injection breaks compile-time contract verification and enables partially constructed objects. Constructor injection enforces mandatory dependencies.
public class OrderProcessor : IOrderProcessor
{
private readonly IInventoryService _inventory;
private readonly IEmailGateway _email;
private readonly ILogger<OrderProcessor> _logger;
public OrderProcessor(
IInventoryService inventory,
IEmailGateway email,
ILogger<OrderProcessor> logger)
{
_inventory = inventory ?? throw new ArgumentNullException(nameof(inventory));
_email = email ?? throw new ArgumentNullException(nameof(email));
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
}
public async Task ProcessAsync(OrderCommand command, CancellationToken ct)
{
// Implementation
}
}
Step 4: Handle Background Scopes Correctly
Background tasks (IHostedService, BackgroundService) run outside HTTP request scopes. Inject IServiceScopeFactory to create explicit scopes.
public class OrderQueueWorker : BackgroundService
{
private readonly IServiceScopeFactory _scopeFactory;
private readonly ILogger<OrderQueueWorker> _logger;
public OrderQueueWorker(IServiceScopeFactory scopeFactory, ILogger<OrderQueueWorker> logger)
{
_scopeFactory = scopeFactory;
_logger = logger;
}
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
using var scope = _scopeFactory.CreateScope();
var processor = scope.ServiceProvider.GetRequiredService<IOrderProcessor>();
await processor.ProcessAsync(new OrderCommand(), stoppingToken);
}
}
}
Step 5: Validate at Startup
Enable graph validation to catch missing registrations, circular dependencies, and lifetime mismatches before deployment.
builder.Services.AddHostedService<OrderQueueWorker>();
var app = builder.Build();
app.Services.GetRequiredService<IOrderProcessor>(); // Forces validation
app.Run();
For stricter validation, use ValidateOnBuild() in .NET 8+:
builder.Services.Configure<HostOptions>(options =>
options.ServicesValidateOnBuild = true);
Architecture Decisions & Rationale
- Constructor injection only: Guarantees objects are fully initialized before use. Enables static analysis and unit testing without container setup.
- Scoped for EF Core:
DbContext tracks state per unit of work. Sharing it across requests causes concurrency bugs and memory leaks.
- Singleton for stateless services: Caching, logging, and configuration providers benefit from single instantiation. Must be thread-safe.
- Factory pattern for runtime dependencies: When creation depends on request data or configuration, use
Func<T> or explicit factory interfaces instead of resolving mid-method.
- Composition root isolation: Registration belongs in
Program.cs. Feature modules should only define contracts and implementations.
Pitfall Guide
1. Captive Dependencies
A singleton consuming a scoped service holds the scoped instance for the application lifetime. This bypasses per-request isolation and causes stale state or concurrency violations.
Fix: Validate lifetimes at registration. Use ValidateScopes in development to detect mismatches. Refactor to inject IServiceScopeFactory and resolve scoped dependencies within explicit scopes.
2. Service Locator Anti-Pattern
Injecting IServiceProvider and calling GetRequiredService<T>() inside business logic breaks dependency visibility, hides coupling, and prevents static analysis.
Fix: Replace with constructor injection or explicit factory interfaces. If dynamic resolution is required, use KeyedServices (.NET 8+) with explicit keys rather than open-ended IServiceProvider.
3. Ignoring IDisposable in Transient Registrations
The container does not automatically dispose transient instances unless explicitly resolved through a scope. Long-running applications leak unmanaged resources.
Fix: Register disposables as scoped when possible. If transient disposal is unavoidable, resolve through IServiceScope and call Dispose() explicitly, or implement IAsyncDisposable with proper cleanup patterns.
4. Circular Dependencies
Type A depends on Type B, which depends on Type A. The container throws InvalidOperationException at resolution time.
Fix: Introduce an intermediate interface, apply the mediator pattern, or refactor to break the cycle. Circular dependencies indicate violated single responsibility or improper abstraction boundaries.
5. Leaking Container References into Domain Layers
Passing IServiceProvider or container-specific types into application or domain services couples business logic to infrastructure.
Fix: Keep domain layers framework-agnostic. Use factories, handlers, or explicit interfaces to abstract infrastructure concerns.
6. Skipping Startup Validation
Unvalidated graphs fail unpredictably under production load. Missing registrations, lifetime conflicts, and circular references surface only when specific code paths execute.
Fix: Enable ServicesValidateOnBuild in all environments. Add integration tests that resolve critical service graphs. Fail fast during deployment.
7. Misconfiguring DbContext Pooling
AddDbContextPool improves performance but shares instance state improperly if not configured correctly. Pooled contexts retain tracking state across requests.
Fix: Use AddDbContextPool only for read-heavy or short-lived operations. Ensure UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking) where appropriate. Avoid modifying entity state in pooled contexts without explicit Attach/Detach handling.
Best Practices from Production
- Register interfaces, not concrete types, to enable mocking and swapping implementations
- Keep registration logic in
Program.cs; use extension methods for modular organization
- Prefer
AddScoped for request-bound services, AddSingleton for thread-safe stateless services
- Validate graphs at startup; never rely on runtime resolution for critical paths
- Use
IServiceScopeFactory for background workers, message handlers, and scheduled tasks
- Avoid property injection; it enables partially constructed objects and hides dependencies
- Document lifetime expectations in service XML comments to prevent future mismatches
Production Bundle
Action Checklist
Decision Matrix
| Scenario | Recommended Approach | Why | Cost Impact |
|---|
| HTTP request processing | AddScoped per request | Isolates state, aligns with request lifecycle, prevents cross-request contamination | Low (framework native) |
| Background worker / queue consumer | IServiceScopeFactory + using scope | Creates explicit lifetime boundary, ensures proper disposal, avoids captive dependencies | Low (minimal overhead) |
| High-throughput read operations | AddDbContextPool with NoTracking | Reuses context instances, reduces allocation pressure, improves throughput | Medium (requires tracking discipline) |
| Dynamic runtime resolution | KeyedServices (.NET 8+) | Provides explicit resolution keys, maintains compile-time safety, avoids service locator | Low (built-in support) |
| Legacy service locator migration | Factory interface + constructor injection | Restores dependency visibility, enables unit testing, eliminates container leakage | High (refactoring required) |
Configuration Template
// Program.cs
var builder = WebApplication.CreateBuilder(args);
// Lifetime mapping
builder.Services.AddSingleton<ICacheProvider, MemoryCacheProvider>();
builder.Services.AddScoped<IOrderRepository, EfOrderRepository>();
builder.Services.AddScoped<IOrderProcessor, OrderProcessor>();
builder.Services.AddTransient<IEmailGateway, SmtpEmailGateway>();
// Background service with explicit scope
builder.Services.AddHostedService<OrderQueueWorker>();
// Startup validation
builder.Services.Configure<HostOptions>(options =>
options.ServicesValidateOnBuild = true);
var app = builder.Build();
// Force graph validation on startup
app.Services.GetRequiredService<IOrderProcessor>();
app.MapControllers();
app.Run();
// Extension method for modular registration
public static class ServiceRegistrations
{
public static IServiceCollection AddOrdering(this IServiceCollection services)
{
services.AddScoped<IOrderProcessor, OrderProcessor>();
services.AddScoped<IOrderRepository, EfOrderRepository>();
return services;
}
}
Quick Start Guide
- Define contracts: Create interfaces for every service that will be injected. Place them in a dedicated
Contracts or Abstractions project.
- Register in composition root: Open
Program.cs. Map each interface to its implementation using AddSingleton, AddScoped, or AddTransient based on state ownership.
- Inject via constructors: Update consuming classes to accept dependencies through constructor parameters. Remove all property injection and
IServiceProvider usage.
- Enable validation: Add
builder.Services.Configure<HostOptions>(o => o.ServicesValidateOnBuild = true); to catch graph errors at startup.
- Test resolution: Run the application. If startup succeeds, the DI graph is valid. If it fails, resolve missing registrations or lifetime mismatches before proceeding.
