C# Dependency Injection and IoC Containers Complete Guide

Introduction to Dependency Injection#

Dependency Injection (DI) is a design pattern that implements Inversion of Control (IoC) for resolving dependencies. It’s a fundamental technique for writing maintainable, testable, and loosely coupled code. In modern C# development, especially with ASP.NET Core, DI has become a core part of application architecture.

This guide covers DI concepts, IoC containers, implementation patterns, best practices, and advanced scenarios.

Understanding Dependency Injection#

What is Dependency Injection?#

Dependency Injection is a technique where an object receives its dependencies from external sources rather than creating them itself.

// WITHOUT Dependency Injection
public class OrderService
{
    private readonly OrderRepository _repository;
    
    public OrderService()
    {
        // Tight coupling - creates its own dependency
        _repository = new OrderRepository();
    }
    
    public void CreateOrder(Order order)
    {
        _repository.Save(order);
    }
}

// WITH Dependency Injection
public class OrderService
{
    private readonly IOrderRepository _repository;
    
    // Dependency injected via constructor
    public OrderService(IOrderRepository repository)
    {
        _repository = repository;
    }
    
    public void CreateOrder(Order order)
    {
        _repository.Save(order);
    }
}

Benefits of Dependency Injection#

1. Loose Coupling: Components depend on abstractions, not concrete implementations.

2. Testability: Easy to mock dependencies in unit tests.

[TestMethod]
public void CreateOrder_SavesOrderSuccessfully()
{
    // Arrange
    var mockRepository = new Mock<IOrderRepository>();
    var service = new OrderService(mockRepository.Object);
    var order = new Order { Id = 1 };
    
    // Act
    service.CreateOrder(order);
    
    // Assert
    mockRepository.Verify(r => r.Save(order), Times.Once);
}

3. Maintainability: Changes to dependencies don’t require changes to dependent classes.

4. Flexibility: Easy to swap implementations without modifying code.

Types of Dependency Injection#

1. Constructor Injection#

The most common and recommended approach.

public class ProductService
{
    private readonly IProductRepository _repository;
    private readonly ILogger<ProductService> _logger;
    
    // Dependencies injected via constructor
    public ProductService(
        IProductRepository repository,
        ILogger<ProductService> logger)
    {
        _repository = repository ?? throw new ArgumentNullException(nameof(repository));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }
    
    public async Task<Product> GetProductAsync(int id)
    {
        _logger.LogInformation("Fetching product {ProductId}", id);
        return await _repository.GetByIdAsync(id);
    }
}

Advantages:

Dependencies are explicit and required
Immutability (readonly fields)
Easy to test
Prevents partially constructed objects

2. Property Injection#

Used for optional dependencies.

public class EmailService
{
    private readonly IEmailSender _sender;
    
    public EmailService(IEmailSender sender)
    {
        _sender = sender;
    }
    
    // Optional dependency via property
    public ILogger Logger { get; set; }
    
    public async Task SendEmailAsync(string to, string subject, string body)
    {
        Logger?.LogInformation("Sending email to {Recipient}", to);
        await _sender.SendAsync(to, subject, body);
    }
}

Disadvantages:

Dependencies not immediately obvious
Can be set to null
Less preferred than constructor injection

3. Method Injection#

Dependencies passed as method parameters.

public class ReportGenerator
{
    public Report Generate(IDataSource dataSource, IReportTemplate template)
    {
        var data = dataSource.GetData();
        return template.Format(data);
    }
}

// Usage
var generator = new ReportGenerator();
var report = generator.Generate(
    new DatabaseDataSource(),
    new PdfTemplate()
);

Use cases:

Different dependency needed per method call
Dependency not needed for entire object lifetime

IoC Containers in .NET#

Built-in Microsoft.Extensions.DependencyInjection#

ASP.NET Core includes a built-in DI container.

// Startup.cs or Program.cs
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Transient - new instance every time
        services.AddTransient<IEmailService, EmailService>();
        
        // Scoped - one instance per request
        services.AddScoped<IOrderService, OrderService>();
        
        // Singleton - one instance for application lifetime
        services.AddSingleton<IConfiguration, Configuration>();
        
        // Register with factory
        services.AddTransient<IProductService>(provider =>
        {
            var repository = provider.GetRequiredService<IProductRepository>();
            var cache = provider.GetService<ICache>();
            return new ProductService(repository, cache);
        });
    }
}

Service Lifetimes#

Transient:

Created each time they’re requested
Best for lightweight, stateless services
Each request gets a new instance

services.AddTransient<IEmailSender, SmtpEmailSender>();

// Usage
public class Controller
{
    private readonly IEmailSender _sender1;
    private readonly IEmailSender _sender2;
    
    public Controller(IEmailSender sender1, IEmailSender sender2)
    {
        _sender1 = sender1;  // New instance
        _sender2 = sender2;  // Another new instance
        // sender1 != sender2
    }
}

Scoped:

Created once per client request (scope)
Best for per-request operations
Same instance within a request

services.AddScoped<IOrderRepository, OrderRepository>();

// In web request:
// All services within the same HTTP request share the same instance
public class OrderController
{
    private readonly IOrderRepository _repo;
    
    public OrderController(IOrderRepository repo)
    {
        _repo = repo;  // Same instance as injected in OrderService
    }
}

public class OrderService
{
    private readonly IOrderRepository _repo;
    
    public OrderService(IOrderRepository repo)
    {
        _repo = repo;  // Same instance as in OrderController
    }
}

Singleton:

Created once and shared throughout application lifetime
Best for stateless services, configurations, caches
Must be thread-safe

services.AddSingleton<ICache, MemoryCache>();

// All requests share the same instance
public class Service1
{
    public Service1(ICache cache) { }  // Same instance
}

public class Service2
{
    public Service2(ICache cache) { }  // Same instance
}

Lifetime Best Practices#

public class LifetimeExamples
{
    public void ConfigureServices(IServiceCollection services)
    {
        // GOOD - Stateless service as Transient
        services.AddTransient<IEmailValidator, EmailValidator>();
        
        // GOOD - Per-request state as Scoped
        services.AddScoped<IShoppingCart, ShoppingCart>();
        
        // GOOD - Shared state as Singleton
        services.AddSingleton<IConfigurationProvider, ConfigurationProvider>();
        
        // BAD - Don't inject Scoped into Singleton
        // services.AddSingleton<ServiceWithScopedDependency>();
        
        // GOOD - Use IServiceScopeFactory in Singleton
        services.AddSingleton<BackgroundService>();
        services.AddScoped<IScopedService, ScopedService>();
    }
}

public class BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    
    public BackgroundService(IServiceScopeFactory scopeFactory)
    {
        _scopeFactory = scopeFactory;
    }
    
    public async Task DoWorkAsync()
    {
        using var scope = _scopeFactory.CreateScope();
        var scopedService = scope.ServiceProvider
            .GetRequiredService<IScopedService>();
        
        await scopedService.ProcessAsync();
    }
}

Advanced DI Patterns#

1. Factory Pattern with DI#

public interface INotificationFactory
{
    INotification CreateNotification(NotificationType type);
}

public class NotificationFactory : INotificationFactory
{
    private readonly IServiceProvider _serviceProvider;
    
    public NotificationFactory(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }
    
    public INotification CreateNotification(NotificationType type)
    {
        return type switch
        {
            NotificationType.Email => 
                _serviceProvider.GetRequiredService<EmailNotification>(),
            NotificationType.Sms => 
                _serviceProvider.GetRequiredService<SmsNotification>(),
            NotificationType.Push => 
                _serviceProvider.GetRequiredService<PushNotification>(),
            _ => throw new ArgumentException("Invalid notification type")
        };
    }
}

// Registration
services.AddTransient<EmailNotification>();
services.AddTransient<SmsNotification>();
services.AddTransient<PushNotification>();
services.AddSingleton<INotificationFactory, NotificationFactory>();

2. Decorator Pattern#

public interface IOrderService
{
    Task<Order> CreateOrderAsync(Order order);
}

public class OrderService : IOrderService
{
    private readonly IOrderRepository _repository;
    
    public OrderService(IOrderRepository repository)
    {
        _repository = repository;
    }
    
    public async Task<Order> CreateOrderAsync(Order order)
    {
        return await _repository.SaveAsync(order);
    }
}

// Decorator for logging
public class LoggingOrderService : IOrderService
{
    private readonly IOrderService _inner;
    private readonly ILogger<LoggingOrderService> _logger;
    
    public LoggingOrderService(
        IOrderService inner,
        ILogger<LoggingOrderService> logger)
    {
        _inner = inner;
        _logger = logger;
    }
    
    public async Task<Order> CreateOrderAsync(Order order)
    {
        _logger.LogInformation("Creating order {OrderId}", order.Id);
        
        try
        {
            var result = await _inner.CreateOrderAsync(order);
            _logger.LogInformation("Order {OrderId} created successfully", order.Id);
            return result;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to create order {OrderId}", order.Id);
            throw;
        }
    }
}

// Registration with Scrutor
services.AddScoped<IOrderService, OrderService>();
services.Decorate<IOrderService, LoggingOrderService>();

3. Named Services#

public interface IPaymentProcessor
{
    Task<PaymentResult> ProcessAsync(Payment payment);
}

public class PayPalProcessor : IPaymentProcessor
{
    public async Task<PaymentResult> ProcessAsync(Payment payment)
    {
        // PayPal implementation
        return await Task.FromResult(new PaymentResult());
    }
}

public class StripeProcessor : IPaymentProcessor
{
    public async Task<PaymentResult> ProcessAsync(Payment payment)
    {
        // Stripe implementation
        return await Task.FromResult(new PaymentResult());
    }
}

// Named service resolver
public interface IPaymentProcessorResolver
{
    IPaymentProcessor Resolve(string provider);
}

public class PaymentProcessorResolver : IPaymentProcessorResolver
{
    private readonly IServiceProvider _serviceProvider;
    
    public PaymentProcessorResolver(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }
    
    public IPaymentProcessor Resolve(string provider)
    {
        return provider.ToLower() switch
        {
            "paypal" => _serviceProvider.GetRequiredService<PayPalProcessor>(),
            "stripe" => _serviceProvider.GetRequiredService<StripeProcessor>(),
            _ => throw new ArgumentException($"Unknown provider: {provider}")
        };
    }
}

// Registration
services.AddScoped<PayPalProcessor>();
services.AddScoped<StripeProcessor>();
services.AddScoped<IPaymentProcessorResolver, PaymentProcessorResolver>();

4. Options Pattern#

public class EmailSettings
{
    public string SmtpServer { get; set; }
    public int Port { get; set; }
    public string Username { get; set; }
    public string Password { get; set; }
}

// appsettings.json
{
  "EmailSettings": {
    "SmtpServer": "smtp.example.com",
    "Port": 587,
    "Username": "user@example.com",
    "Password": "secret"
  }
}

// Startup
services.Configure<EmailSettings>(
    Configuration.GetSection("EmailSettings"));

// Service using options
public class EmailService
{
    private readonly EmailSettings _settings;
    
    public EmailService(IOptions<EmailSettings> options)
    {
        _settings = options.Value;
    }
    
    public async Task SendAsync(string to, string subject, string body)
    {
        // Use _settings.SmtpServer, _settings.Port, etc.
    }
}

Popular IoC Containers#

1. Autofac#

using Autofac;
using Autofac.Extensions.DependencyInjection;

public class Startup
{
    public IServiceProvider ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
        
        var builder = new ContainerBuilder();
        builder.Populate(services);
        
        // Register types
        builder.RegisterType<OrderService>()
            .As<IOrderService>()
            .InstancePerLifetimeScope();
        
        // Register with parameters
        builder.RegisterType<ProductService>()
            .As<IProductService>()
            .WithParameter("timeout", TimeSpan.FromSeconds(30));
        
        // Register modules
        builder.RegisterModule<RepositoryModule>();
        
        var container = builder.Build();
        return new AutofacServiceProvider(container);
    }
}

// Module for organizing registrations
public class RepositoryModule : Module
{
    protected override void Load(ContainerBuilder builder)
    {
        builder.RegisterType<OrderRepository>()
            .As<IOrderRepository>()
            .InstancePerLifetimeScope();
        
        builder.RegisterType<ProductRepository>()
            .As<IProductRepository>()
            .InstancePerLifetimeScope();
    }
}

2. Ninject#

using Ninject;

public class Program
{
    private static IKernel ConfigureServices()
    {
        var kernel = new StandardKernel();
        
        // Bind interface to implementation
        kernel.Bind<IOrderService>().To<OrderService>();
        
        // Bind with scope
        kernel.Bind<IOrderRepository>().To<OrderRepository>()
            .InRequestScope();
        
        // Bind singleton
        kernel.Bind<IConfiguration>().To<Configuration>()
            .InSingletonScope();
        
        // Bind with factory
        kernel.Bind<IProductService>().ToMethod(ctx =>
        {
            var repo = ctx.Kernel.Get<IProductRepository>();
            return new ProductService(repo);
        });
        
        return kernel;
    }
    
    public static void Main()
    {
        var kernel = ConfigureServices();
        var service = kernel.Get<IOrderService>();
    }
}

3. Castle Windsor#

using Castle.MicroKernel.Registration;
using Castle.Windsor;

public class Program
{
    private static IWindsorContainer ConfigureServices()
    {
        var container = new WindsorContainer();
        
        // Register components
        container.Register(
            Component.For<IOrderService>()
                .ImplementedBy<OrderService>()
                .LifestyleScoped()
        );
        
        container.Register(
            Component.For<IProductService>()
                .ImplementedBy<ProductService>()
                .LifestyleTransient()
        );
        
        // Register with interceptors
        container.Register(
            Component.For<IOrderRepository>()
                .ImplementedBy<OrderRepository>()
                .Interceptors<LoggingInterceptor>()
        );
        
        return container;
    }
    
    public static void Main()
    {
        var container = ConfigureServices();
        var service = container.Resolve<IOrderService>();
    }
}

Testing with DI#

Unit Testing#

public class OrderServiceTests
{
    [Fact]
    public async Task CreateOrder_ValidOrder_ReturnsSuccess()
    {
        // Arrange
        var mockRepository = new Mock<IOrderRepository>();
        var mockLogger = new Mock<ILogger<OrderService>>();
        
        mockRepository
            .Setup(r => r.SaveAsync(It.IsAny<Order>()))
            .ReturnsAsync(new Order { Id = 1 });
        
        var service = new OrderService(
            mockRepository.Object,
            mockLogger.Object
        );
        
        var order = new Order { CustomerId = 1, Total = 100 };
        
        // Act
        var result = await service.CreateOrderAsync(order);
        
        // Assert
        Assert.NotNull(result);
        Assert.Equal(1, result.Id);
        mockRepository.Verify(r => r.SaveAsync(order), Times.Once);
    }
}

Integration Testing#

public class OrderServiceIntegrationTests : IClassFixture<WebApplicationFactory<Startup>>
{
    private readonly WebApplicationFactory<Startup> _factory;
    
    public OrderServiceIntegrationTests(WebApplicationFactory<Startup> factory)
    {
        _factory = factory;
    }
    
    [Fact]
    public async Task CreateOrder_IntegrationTest()
    {
        // Arrange
        var client = _factory.CreateClient();
        var order = new Order { CustomerId = 1, Total = 100 };
        
        // Act
        var response = await client.PostAsJsonAsync("/api/orders", order);
        
        // Assert
        response.EnsureSuccessStatusCode();
        var result = await response.Content.ReadFromJsonAsync<Order>();
        Assert.NotNull(result);
        Assert.True(result.Id > 0);
    }
}

Common Pitfalls and Best Practices#

1. Service Locator Anti-Pattern#

// BAD - Service Locator (anti-pattern)
public class OrderService
{
    public void CreateOrder(Order order)
    {
        var repository = ServiceLocator.GetService<IOrderRepository>();
        repository.Save(order);
    }
}

// GOOD - Constructor Injection
public class OrderService
{
    private readonly IOrderRepository _repository;
    
    public OrderService(IOrderRepository repository)
    {
        _repository = repository;
    }
    
    public void CreateOrder(Order order)
    {
        _repository.Save(order);
    }
}

2. Captive Dependencies#

// BAD - Singleton capturing Scoped dependency
public class SingletonService
{
    private readonly IScopedService _scopedService;
    
    // This keeps the scoped service alive forever!
    public SingletonService(IScopedService scopedService)
    {
        _scopedService = scopedService;
    }
}

// GOOD - Use IServiceScopeFactory
public class SingletonService
{
    private readonly IServiceScopeFactory _scopeFactory;
    
    public SingletonService(IServiceScopeFactory scopeFactory)
    {
        _scopeFactory = scopeFactory;
    }
    
    public void DoWork()
    {
        using var scope = _scopeFactory.CreateScope();
        var scopedService = scope.ServiceProvider
            .GetRequiredService<IScopedService>();
        scopedService.Process();
    }
}

3. Over-Injection#

// BAD - Too many dependencies
public class OrderService
{
    public OrderService(
        IOrderRepository repo,
        ICustomerService customerService,
        IInventoryService inventoryService,
        IPaymentService paymentService,
        IShippingService shippingService,
        INotificationService notificationService,
        ILogger logger,
        IConfiguration config)
    {
        // Too many dependencies suggests class does too much
    }
}

// GOOD - Extract to smaller services
public class OrderService
{
    private readonly IOrderRepository _repository;
    private readonly IOrderProcessor _processor;
    private readonly ILogger<OrderService> _logger;
    
    public OrderService(
        IOrderRepository repository,
        IOrderProcessor processor,
        ILogger<OrderService> logger)
    {
        _repository = repository;
        _processor = processor;
        _logger = logger;
    }
}

public class OrderProcessor
{
    // Handles complex order processing logic
    public OrderProcessor(
        IPaymentService paymentService,
        IInventoryService inventoryService,
        INotificationService notificationService)
    {
        // Focused responsibility
    }
}

4. Null Checking#

// GOOD - Always validate constructor parameters
public class OrderService
{
    private readonly IOrderRepository _repository;
    private readonly ILogger<OrderService> _logger;
    
    public OrderService(
        IOrderRepository repository,
        ILogger<OrderService> logger)
    {
        _repository = repository 
            ?? throw new ArgumentNullException(nameof(repository));
        _logger = logger 
            ?? throw new ArgumentNullException(nameof(logger));
    }
}

Performance Considerations#

1. Avoid Unnecessary Transient Services#

// BAD - Expensive transient service
services.AddTransient<ExpensiveService>();

// GOOD - Use appropriate lifetime
services.AddSingleton<ExpensiveService>();
// or
services.AddScoped<ExpensiveService>();

2. Lazy Initialization#

public class ServiceWithLazyDependency
{
    private readonly Lazy<IExpensiveService> _expensiveService;
    
    public ServiceWithLazyDependency(Lazy<IExpensiveService> expensiveService)
    {
        _expensiveService = expensiveService;
    }
    
    public void DoWork()
    {
        if (SomeCondition())
        {
            // Service only created if needed
            _expensiveService.Value.Process();
        }
    }
}

// Registration
services.AddTransient<IExpensiveService, ExpensiveService>();
services.AddTransient(provider => 
    new Lazy<IExpensiveService>(
        () => provider.GetRequiredService<IExpensiveService>()
    )
);

Conclusion#

Dependency Injection and IoC containers are fundamental to modern C# development. Key takeaways include:

Use constructor injection for required dependencies
Understand service lifetimes (Transient, Scoped, Singleton)
Avoid service locator anti-pattern
Be careful with captive dependencies
Keep constructors simple and avoid over-injection
Choose the right IoC container for your needs
Always validate constructor parameters
Use factory patterns for complex object creation
Leverage the Options pattern for configuration
Write testable code with proper abstractions

By mastering DI and IoC, you can build maintainable, testable, and flexible applications that follow SOLID principles.