Building a lightweight dependency injection container in .NET Core

Many developers in Sydney and Melbourne rely on the built-in Microsoft.Extensions.DependencyInjection library without ever considering what happens behind its surface. Others, especially those working at fintechs in Brisbane or defence contractors in Canberra, eventually need finer control over object lifetimes, registration sources, or how the container reacts to specific compliance rules such as the Notifiable Data Breaches scheme under the Privacy Act 1988. Rolling a minimal IoC container yourself is a rewarding exercise that exposes the seams of the framework and gives you complete authority over registration, activation, and disposal logic.

This walkthrough goes beyond a toy example. You will build a working service container capable of handling transient, singleton, and scoped lifetimes, support constructor injection, validate the dependency graph, and integrate with the IServiceProvider abstraction that ASP.NET Core uses internally. Along the way we touch on design choices that matter when the same code eventually ships to customers in Australia East and Australia Southeast Azure regions and must pass a code review from a local engineering lead.

Why build your own container

The stock DI container shipped with .NET Core is fast, predictable, and good enough for roughly 95 percent of business applications. Yet there are situations where its conventions get in the way. A team might need to resolve services from a custom configuration source that reads from Azure App Configuration in the Australia East region, or apply conditional registrations based on environment name. Some organisations, particularly those bound by Australian Prudential Regulation Authority guidelines, prefer to log every resolution attempt to an internal audit pipeline before the object is returned.

When you write the container you are no longer surprised by behaviour you cannot trace. You decide whether open generics are supported, how circular dependencies are detected, and whether reflection caching happens lazily or eagerly. The custom container becomes a teaching tool that demystifies how IServiceScopeFactory creates child scopes per HTTP request, a detail that becomes tangible the moment you host the application inside an Azure App Service plan located in Sydney.

Another reason is interview preparation and conference talks. Speakers at the C# Corner Annual Conference regularly demo custom containers in twenty minutes to show the audience that the pattern is small enough to fit on a single slide. Once you understand the moving parts, you can explain Microsoft.Extensions.DependencyInjection with confidence because you have written the equivalent mechanism yourself.

Service registrations and the container API

Every container starts with a registry. In .NET Core the canonical contract is IServiceCollection, a list of ServiceDescriptor entries that the framework later consumes through a BuildServiceProvider call. A descriptor holds three pieces of information: the service type, the implementation type or factory delegate, and the ServiceLifetime.

The minimum API surface we need to copy is straightforward. A RegisterTransient method adds a descriptor flagged as transient. RegisterSingleton accepts either a type or an already-constructed instance. RegisterScoped is reserved for cases where the resolved object should live for the duration of an IServiceScope, which is exactly what ASP.NET Core creates on every HTTP request that hits a web app hosted in an Australian data centre.

A practical design supports three extension points: instance registration for objects that were built elsewhere (such as an ILoggerFactory wired up during Program.cs), factory registration for lazy or conditional construction, and open-generic registration. We store everything as a simple in-memory list because the registration count rarely exceeds a few hundred entries in real-world apps, even at large Australian banks that run hundreds of microservices. The descriptor pattern lets the container treat every service the same way regardless of origin.

• A transient service is created on every call to GetService.
• A singleton service is constructed once and reused for the lifetime of the root provider.
• A scoped service is created once per scope and disposed when the scope ends.
• Open generic registrations resolve any closed generic that matches the type definition.

Resolution engine and constructor injection

The interesting code lives in the Resolve method. When a request comes in for IService, the engine first checks a singleton cache, then a scoped cache if the current scope has one, and finally falls through to the factory path. Each cache is a simple ConcurrentDictionary keyed by the requested Type.

For constructor injection we use reflection. We fetch the constructor with the most parameters that the container can satisfy, an approach that mirrors what the built-in container does. We then resolve every parameter recursively, throwing a clear exception if a parameter type is not registered. The exception message should mention the type that could not be resolved and the chain that led to it, because that single line often saves hours of debugging when a release fails in production.

Circular dependencies are detected with a small thread-local hash set pushed onto a stack before each resolution. If a request appears twice in the same chain we throw immediately. This is exactly the behaviour Microsoft chose for its own container, and reproducing it proves you have understood the contract. The recursive nature of resolution also explains why deep object graphs are slower than flat ones, a fact worth memorising when you tune a hot path that handles thousands of requests per second on an Azure App Service in Melbourne.

A small performance trick worth adopting is to cache the reflected ConstructorInfo objects. Reflection in .NET 8 is cheaper than it used to be, but on a cold start inside a serverless function in Australia East, every millisecond still matters because you pay for the entire execution time.

Scoped lifetime and disposal hygiene

The notion of a scope is the trickiest piece of the puzzle. A scope exists to give scoped services a predictable lifetime. The container exposes a CreateScope method that returns an IServiceScope containing a child IServiceProvider. All scoped instances resolved through the child provider live only as long as that scope.

For the container to clean up correctly, every resolved object that implements IDisposable or IAsyncDisposable must be tracked. The built-in engine keeps two lists per scope: one for synchronous disposables and one for asynchronous ones. When the scope is disposed the lists are iterated in reverse so that objects created later are released first.

Our container does the same. We add the IDisposable instance to a scope-local list as soon as the factory returns it, then expose a Dispose method on the scope that walks the list. Following this pattern keeps resource usage bounded, which matters when the same Application Pool recycles many requests per second at a busy ecommerce site hosted in Sydney. It also keeps us aligned with the Australian Privacy Principles, because services that hold references to personally identifiable information should release those references as soon as the request finishes.

If a service holds expensive unmanaged resources, such as a database connection to an Azure SQL database in Australia East, the disposal logic should call the asynchronous variant. Mixing sync and async disposal is a frequent source of deadlocks in older .NET codebases still maintained by Australian government agencies.

Validation and graph integrity

Before the container hands a provider to the caller, it is good practice to validate the entire graph. Microsoft offers ValidateOnBuild, ValidateScopes, and a few related options for exactly this purpose. Building the validator from scratch is not difficult: walk every registration, recursively resolve each service without caching the result, and confirm that the chain terminates.

Validation catches forgotten registrations early, which is especially useful in continuous integration pipelines running inside GitHub Actions hosted in Australia. A pipeline that validates the container graph on every pull request prevents the classic "works on my machine" surprise when a release is deployed to a customer's Azure subscription.

Common bugs the validator surfaces include: missing implementations for a service only used by a feature flag, circular references that slipped past the runtime check, and open generics registered for the wrong type definition. Each of these tends to appear once and then never again once the team adopts a habit of running the validator as part of the build script. In a Melbourne-based team I worked with, adding validation shaved a full day off the average onboarding time for new engineers because the error messages were immediately actionable.

Performance and testing considerations

A custom container is rarely faster than the optimised version Microsoft ships. The team behind the official library has spent years tuning it for allocation pressure, and any home-grown replacement should expect to be 10 to 40 percent slower in micro-benchmarks. The trade-off is flexibility: you control the registration sources, the caching strategy, and the diagnostics.

For testing, write unit tests that prove each lifetime behaves as documented. A transient service called twice must return two different instances. A singleton resolved from two different scopes must be the same object. A scoped service obtained from two scopes must differ. BenchmarkDotNet is the tool of choice in the Australian .NET community, and meetups in Sydney and Brisbane often run hands-on sessions that pair the custom container with micro-benchmarks to demonstrate the cost of reflection-based resolution.

Helpful habits when shipping the container include the following.

• Keep the source inside the application repository rather than packaging it as a public NuGet feed unless the team commits to long-term maintenance.
• Document the supported lifetimes and the validation options in a README that links back to the relevant ASP.NET Core docs.
• Re-evaluate the design whenever the official Microsoft.Extensions.DependencyInjection library adds a feature the application cannot live without.

Once the container is stable, treat it as an internal package and resist the urge to publish it externally without a long-term plan. The surface area looks small but grows quickly as feature requests arrive from teams with very different needs. A pragmatic balance between curiosity and shipping is what turns a learning exercise into a production-grade asset.