Lesson 26. Dependency Injection

Mission link: A typed, tested service is assembled by a container you did not write, from registrations you did. Getting the implementation wrong fails on the first request. Getting the lifetime wrong compiles, passes a smoke test, and then serves one user's data to another under load, which is why this lesson spends most of its time on the second kind of mistake.
Primary source: Docs: "Dependency injection guidelines", Microsoft Learn
Prerequisites: Lesson 25, Lesson 22, Lesson 6

Warm-up

1. ▢ Lesson 23 stopped one step short: a class takes IPaymentGateway in its constructor, and a test passes a substitute. Who passes the real one?

2. ▢ Under xUnit, what decides how long a test class instance lives, and what question did that force you to ask?

3. ▢ What does a using statement decide, and who decides it?

Know this

A registration says two things, and only one of them fails loudly. Which implementation to use, and how long an instance may live (Dependency injection in ASP.NET Core):

builder.Services.AddTransient<IOperationTransient, Operation>();
builder.Services.AddScoped<IOperationScoped, Operation>();
builder.Services.AddSingleton<IOperationSingleton, Operation>();

Name the wrong implementation and the first request tells you. Name the wrong lifetime and nothing tells you, because a lifetime is not a promise the type system can check.

Scoped is the lifetime a service revolves around, and it is defined by the scope, not by the request. In an app that processes requests the scope is usually the request, but the mechanism is an IServiceScope, and two documented consequences follow from that being the real rule. First, if a scoped service is created in the root container, the service's lifetime is effectively promoted to singleton, because only the root container disposes it, at shutdown (.NET dependency injection). Second, stated as an anti-pattern in its own right: when you are not creating a scope or within an existing scope, the service becomes a singleton.

Both sentences describe the same failure. A scoped registration does not make anything scoped; being resolved inside a scope does.

Captive dependency: the case that reads as correct. The term, coined by Mark Seemann, is for a longer-lived service holding a shorter-lived service captive. The documentation's example is a singleton Foo whose constructor takes a scoped Bar, and its verdict is that this seems valid on the surface and is a misconfiguration: Foo is instantiated once and holds that one Bar for its whole lifetime.

There is a check, and it is worth knowing exactly how far it reaches. When an app runs in the development environment and builds its host with CreateApplicationBuilder, the default service provider verifies that scoped services are not resolved from the root service provider and are not injected into singletons. You can also ask for it directly by passing validateScopes: true to BuildServiceProvider, which produces an InvalidOperationException.

Read the qualifier rather than the promise. This is a development-environment check on the container's own graph. It is a good reason to run the app in Development before shipping, and not a reason to believe the shape of your lifetimes has been proved.

Middleware is where this bites first, and lesson 25 already set it up. A middleware's position in the pipeline is fixed at startup, and so is its construction: it is built once for the application, not once per request. So the documentation gives a rule with a reason attached. To use scoped services in middleware, inject the service into the middleware's Invoke or InvokeAsync method, because using constructor injection throws a runtime exception: it forces the scoped service to behave like a singleton. The alternative is factory-based middleware, which is activated per client request, and can therefore take scoped services in its constructor after all.

Disposal is not your job, and doing it anyway is the bug. The container is responsible for cleanup of the types it creates, calling Dispose on IDisposable and DisposeAsync on IAsyncDisposable, and services resolved from the container should never be disposed by the developer. The schedule follows the lifetime: transient and scoped instances are disposed at the end of the scope in which they were resolved, typically the end of the request, and singletons when the container itself is disposed, usually at application shutdown.

Three guidelines fall out of that, and the third is the one that catches careful people:

• Do not register IDisposable instances with a transient lifetime; use a factory so the instance can be disposed deliberately.
• Do not resolve transient or scoped IDisposable instances in the root scope.
• Receiving an IDisposable dependency through DI does not require the receiver to implement IDisposable, and the receiver should not call Dispose on that dependency.

Also worth filing away, because it contradicts an intuition most people have: scopes are not hierarchical, and there is no special connection among scopes.

Thread safety, stated as narrowly as the documentation states it. Resolving services from the built-in container is thread-safe: once an IServiceProvider or IServiceScope is built, it is safe to resolve from several threads. The note attached to that is the part to keep, because thread safety of the container only guarantees that constructing and resolving services is safe, and any service, especially a singleton, that holds shared mutable state must implement its own synchronization logic if accessed concurrently. Choosing AddSingleton is choosing to write that synchronization.

Two recommendations to adopt now rather than learn later. Avoid the service locator pattern: do not call GetService to fetch an instance where DI would have supplied it, and treat injecting a factory that resolves dependencies at run time as the same mistake in a better coat. And avoid storing data or configuration in the container, which has its own mechanism.

One forward pointer. That mechanism is the options pattern, which is lesson 27. Lesson 28 is Entity Framework Core, whose DbContext is the scoped service this lesson has been describing in the abstract, and 29 assembles the whole thing into something testable, which is where stage 6's capstone lands.

Practice

1. ▢ A caching service is registered with AddSingleton and takes a repository registered with AddScoped in its constructor. It compiles and the first request works. What is this called, what is actually happening, and when do you find out?

2. ▢ A middleware takes a scoped service in its constructor. It throws at run time. Why, and what are the two documented ways to fix it?

3. ▢ A service receives an HttpClient through DI and implements IDisposable to dispose it in Dispose, on the reasoning that whatever holds a disposable should release it. What is wrong?

4. ▢ A background job resolves a scoped service directly from the application's root provider rather than creating a scope. The registration still says AddScoped. What lifetime does it actually have?

5. ▢ Which statement is correct?

   • a) The container disposes singletons only, so transient and scoped instances must be disposed by whoever resolved them
   • b) A singleton taking a scoped dependency holds one instance of it for the application's lifetime, and the development-time scope check reports that as an error
   • c) Resolving services from the container is thread-safe, so the singleton instances it returns are thread-safe as well
   • d) Injecting a scoped service into a middleware constructor is the documented way to use scoped services in middleware

Real-world reps

• [ ] Open a Program.cs you have access to and list its registrations by lifetime. For each singleton, name what it holds.
• [ ] Find one singleton with mutable state and decide whether anything synchronises access to it.
• [ ] Tomorrow: find a class that both receives a dependency through DI and implements IDisposable. Work out which of the two disposables it actually owns.

Going further

• Docs: "Dependency injection guidelines", Microsoft Learn
• Docs: "Dependency injection in ASP.NET Core", Microsoft Learn
• Docs: ".NET dependency injection", Microsoft Learn
• Resources

Not landing? Reread the primary source at the top, since this lesson compresses it and compression is where understanding leaks. Check the glossary for any term that felt slippery.

If the lesson itself is unclear rather than the material, that is a defect: open an issue.