Dependency Injection in .NET: A Beginner-Friendly Guide

Stop building your own dependencies. Let someone hand them to you.

Imagine every time you wanted a coffee, you had to grow the beans yourself, build a roaster, and manufacture a coffee machine before you could brew a cup. That's insane — you just want the coffee. You walk into a café, and the barista hands you a finished cup. You didn't build the machine; someone else provided it, and you simply used it.

A lot of C# code is written the "grow your own beans" way. A class needs a logger, so it does new ConsoleLogger() right inside itself. It needs to send email, so it does new SmtpEmailSender(). Every class becomes responsible for manufacturing everything it touches — which means every class is welded to specific, concrete implementations, and none of it can be swapped, mocked, or reconfigured without editing that class's source code.

In this lesson, you'll learn what Dependency Injection actually is, why the .NET runtime ships a built-in container for it, and how to register and resolve services using the modern generic host — the foundation every real .NET application (web app, worker service, or console tool) is built on.

What Is It?

The Simple Explanation

Dependency Injection (DI) is a technique where a class doesn't create the objects it depends on — it receives them from the outside, usually through its constructor. The class declares "I need an ILogger," and something else — a framework, a container — figures out which concrete logger to hand it and builds it for it.

Break the phrase into its two words:

• Dependency — something a class needs in order to do its job (a logger, a database repository, an email sender).
• Injection — the act of supplying that dependency from outside, rather than the class constructing it itself.

The Technical Definition

Dependency Injection is a specific application of the Dependency Inversion Principle — the "D" in SOLID, covered in lesson 081. Dependency Inversion says: high-level code should depend on abstractions (interfaces), not on concrete, low-level implementations. Dependency Injection is how you make that happen at runtime: an external mechanism constructs the concrete implementation and passes it into the class that depends on the abstraction, typically through the constructor.

In .NET, this external mechanism is usually the built-in Microsoft.Extensions.DependencyInjection package — a lightweight Inversion of Control (IoC) container. You register your services with it once, at startup, and it takes responsibility for constructing them (and everything they depend on) whenever they're needed.

Why Does It Exist?

The Problem — Classes That Build Their Own Dependencies

Picture an OrderService that needs to log activity and send confirmation emails:

public class OrderService
{
    private readonly ConsoleLogger _logger = new ConsoleLogger();
    private readonly SmtpEmailSender _emailSender = new SmtpEmailSender("smtp.mycorp.com");

    public void PlaceOrder(Order order)
    {
        _logger.Log($"Placing order {order.Id}");
        _emailSender.Send(order.CustomerEmail, "Order placed!");
    }
}

This looks harmless, but it quietly creates several real problems:

• You can't test it in isolation. Every unit test for OrderService will send a real SMTP email, because there's no way to substitute a fake sender.
• You can't swap implementations. Want to log to a file instead of the console in production? You have to edit OrderService's source code.
• Configuration is buried. The SMTP server address is hardcoded inside a class that has nothing conceptually to do with SMTP servers.
• Object graphs don't scale. As your app grows, every class ends up wiring up its own tree of dependencies by hand, and that logic gets duplicated everywhere.

The Solution — Let Something Else Supply the Dependencies

Dependency Injection flips the responsibility. OrderService stops knowing how to build a logger or an email sender — it only knows it needs something that satisfies ILogger and IEmailSender. A container, configured once at startup, is responsible for building the right concrete objects and wiring them together.

Big Picture

Zoomed out, this is the flow of a DI-powered app:

How It Works

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IEmailSender, SmtpEmailSender>();
builder.Services.AddTransient<OrderService>();

using var host = builder.Build();

var orderService = host.Services.GetRequiredService<OrderService>();
orderService.PlaceOrder(new Order(1, "customer@example.com"));

Simple Example

Here's the full, runnable picture — an abstraction, an implementation, a class that depends on the abstraction via constructor injection (using a primary constructor), and the wiring at startup.

// ─── The abstraction ───
public interface IEmailSender
{
    void Send(string to, string message);
}

// ─── The concrete implementation ───
public class SmtpEmailSender : IEmailSender
{
    public void Send(string to, string message) =>
        Console.WriteLine($"[SMTP] To: {to} — {message}");
}

// ─── A class that DEPENDS on the abstraction ───
// Primary constructor: the parameter list *is* the constructor.
public class OrderService(IEmailSender emailSender, ILogger<OrderService> logger)
{
    public void PlaceOrder(int orderId, string customerEmail)
    {
        logger.LogInformation("Placing order {OrderId}", orderId);
        emailSender.Send(customerEmail, $"Your order {orderId} has been placed!");
    }
}

// ─── Program.cs — composing the app ───
var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IEmailSender, SmtpEmailSender>();
builder.Services.AddTransient<OrderService>();

using var host = builder.Build();

var orderService = host.Services.GetRequiredService<OrderService>();
orderService.PlaceOrder(1001, "sam@example.com");

What just happened: OrderService never wrote new SmtpEmailSender() anywhere. It simply declared, through its constructor, "I need an IEmailSender and a logger." The container matched that request against the registration and supplied the concrete object. OrderService doesn't even know SmtpEmailSender exists.

Note also that logger was never explicitly registered — ILogger<T> is provided automatically by the generic host's built-in logging infrastructure (lesson 128 covers this in depth).

Real-World Example

Consider a background worker service that polls a payment provider every minute, checks for failed payments, and notifies a support channel. It needs several collaborators: a payment API client, a notification service, and a repository to track which payments it has already handled.

public interface IPaymentClient
{
    Task<IReadOnlyList<FailedPayment>> GetFailedPaymentsAsync();
}

public interface INotificationService
{
    Task NotifyAsync(string message);
}

public class PaymentMonitorWorker(
    IPaymentClient paymentClient,
    INotificationService notifications,
    ILogger<PaymentMonitorWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            var failures = await paymentClient.GetFailedPaymentsAsync();
            foreach (var failure in failures)
            {
                logger.LogWarning("Payment {PaymentId} failed", failure.Id);
                await notifications.NotifyAsync($"Payment {failure.Id} failed for {failure.Amount:C}");
            }
            await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
        }
    }
}

// ─── Composition root ───
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHttpClient<IPaymentClient, StripePaymentClient>();
builder.Services.AddSingleton<INotificationService, SlackNotificationService>();
builder.Services.AddHostedService<PaymentMonitorWorker>();

using var host = builder.Build();
await host.RunAsync();

PaymentMonitorWorker is completely decoupled from Stripe and Slack. In a test project, you register fake implementations of IPaymentClient and INotificationService instead, and the worker's logic runs against them without a single change to PaymentMonitorWorker itself. That's the entire point.

Analogy

Under the Hood

This constructor-reflection approach means the container is largely unopinionated about your code — it just needs a public constructor whose parameter types it can resolve. If it can't find or build a registration for some required type, it throws an InvalidOperationException at resolution time (usually app startup), not silently returning null.

Common Confusion

"Dependency Injection" ≠ "Dependency Inversion"

These are two different, related ideas, and beginners routinely conflate them:

• Dependency Inversion Principle (lesson 081) is a design rule: depend on abstractions, not concrete types. You can follow this rule with zero frameworks — just by typing an interface parameter.
• Dependency Injection is a runtime technique for actually supplying those abstractions — usually via a container. You can technically do DI by hand (passing a concrete new SmtpEmailSender() into a constructor that takes IEmailSender) without ever touching a container. The container is a convenience that automates it at scale.

In short: Dependency Inversion is the "what and why," Dependency Injection is one common "how."

"The container" isn't magic — it's a dictionary and reflection

It's tempting to think of IServiceProvider as some mysterious black box. It isn't — it's a lookup table mapping types to instructions for building them, plus a bit of reflection to read constructors. Understanding this demystifies most DI errors: if resolution fails, it's because a type wasn't registered, or one of its dependencies wasn't.

Common Mistakes

Mistake 1 — The "Service Locator" anti-pattern

Injecting the whole IServiceProvider and pulling services out of it manually inside a class, instead of declaring real constructor dependencies.

public class OrderService(IServiceProvider provider)
{
    public void PlaceOrder()
    {
        var emailSender = provider.GetRequiredService<IEmailSender>(); // hides the real dependency
    }
}

Declare IEmailSender directly as a constructor parameter. This keeps the class's true dependencies visible and honest, and lets the compiler (and the reader) verify them at a glance.

Mistake 2 — Forgetting to register a type and only finding out at runtime

DI resolution failures happen at runtime, not compile time. Forgetting builder.Services.AddTransient<OrderService>() compiles fine and blows up the moment you try to resolve it.

Resolve your top-level services (like hosted services or entry points) as early as possible in Program.cs/startup so registration mistakes surface immediately in development, not in production.

Mistake 3 — Injecting concrete classes instead of interfaces

public OrderService(SmtpEmailSender sender) — this defeats the whole purpose. You can still register and resolve it, but now OrderService is coupled to SMTP specifically, and you've lost the ability to swap implementations or mock it cleanly in tests.

Depend on the interface (IEmailSender), and let the registration decide which concrete type fulfills it.

When Should I Use It?

Use DI when:

• You're building any real ASP.NET Core app, worker service, or console tool with more than a handful of classes.
• You want your business logic to be unit-testable in isolation, with fakes/mocks standing in for real dependencies.
• You have cross-cutting concerns (logging, configuration, HTTP clients) that many classes need but shouldn't each construct themselves.
• You expect implementations to change per environment (a mock email sender in tests, a real SMTP sender in production).

You may not need a full container when:

• You're writing a tiny script or one-off tool with no meaningful object graph.
• Manual constructor passing (plain "poor man's DI" — just calling new at one composition point) is simple enough and the app will never grow.

Mental Model

Key Takeaway

Check Your Understanding

You've seen how Dependency Injection lets a class receive what it needs instead of building it. Let's check whether the mental model has stuck.

You now understand what Dependency Injection is, why it exists, and how to wire it up with the modern generic host — the foundation for everything else in this module.