Dependency injection and service lifetimes

Transient, scoped and singleton, what a scope is in ASP.NET Core, and who disposes what the container creates.

After this lesson you can

Define transient, scoped and singleton precisely
Predict how many instances a sequence of resolutions creates
Explain when the container disposes a service and when it does not
Say which registration a constructor gets when there are several

ASP.NET Core ships a dependency injection container. You describe services at startup; the container builds them, and their dependencies, when something asks.

builder.Services.AddSingleton<IClock, SystemClock>();
builder.Services.AddScoped<IOrderRepository, SqlOrderRepository>();
builder.Services.AddTransient<IPriceCalculator, PriceCalculator>();

The lifetime decides how often a new instance is made:

Transient: a new instance every time the service is resolved, so two constructors asking for it in the same request get two objects.
Scoped: one instance per scope. ASP.NET Core opens a scope for each request and disposes it when the request ends, so "scoped" means "one per request" in a web app. AddDbContext registers the context as scoped.
Singleton: one instance for the root provider, created the first time it is needed (or the instance you passed in) and kept for the life of the app.

The example is a model, not the real container: twenty lines that apply the same three rules, and two requests that each resolve every service twice.

A tiny container with the three lifetimescsharp-9

1public class Container2{3    readonly Dictionary<string, string> lifetimes = new();4    readonly Dictionary<string, string> singletons = new();5    int counter;6 7    public void Register(string service, string lifetime) => lifetimes[service] = lifetime;8 9    public string Resolve(string service, Dictionary<string, string> scope)10    {11        switch (lifetimes[service])12        {13            case "Singleton":14                if (!singletons.TryGetValue(service, out var s)) singletons[service] = s = New(service);15                return s;16            case "Scoped":17                if (!scope.TryGetValue(service, out var sc)) scope[service] = sc = New(service);18                return sc;19            default:20                return New(service);21        }22    }23 24    string New(string service) => service + "#" + ++counter;25}26 27public static class Solution28{29    public static List<string> Run()30    {31        var c = new Container();32        c.Register("Clock", "Singleton");33        c.Register("Db", "Scoped");34        c.Register("Validator", "Transient");35 36        var lines = new List<string>();37        for (int request = 1; request <= 2; request++)38        {39            var scope = new Dictionary<string, string>(); // one scope per request40            var got = new List<string>();41            foreach (var service in new[] { "Clock", "Clock", "Db", "Db", "Validator", "Validator" })42                got.Add(c.Resolve(service, scope));43            lines.Add($"request {request}: " + string.Join(" ", got));44        }45        return lines;46    }47}

What to look for

Disposal

The container disposes every IDisposable it created, when the scope that owns it is disposed: scoped and transient services at the end of the request, singletons when the app shuts down. An object you constructed yourself and registered with AddSingleton(instance) is yours to dispose. A disposable transient resolved from the root provider is held by the root until shutdown, so resolving one repeatedly there grows memory for the life of the process.

Several registrations for one service

Registering a service twice keeps both registrations. A constructor that takes IPriceCalculator gets the last one registered; a constructor that takes IEnumerable<IPriceCalculator> gets all of them in registration order. TryAddSingleton and friends only register when the service has no registration yet, which is how libraries supply defaults that the application can replace.

Common mistakes

Registering something with per-user or per-request state as a singleton. Every concurrent request then shares one object; a DbContext in particular is not safe to use from two threads at once.
Assuming transient means "per request". Two services in the same request that both depend on a transient get two separate instances, like Validator#3 and Validator#4 in the model.
Resolving a scoped service from app.Services at startup. With scope validation on, which is the default in the Development environment, this throws; with it off, the instance silently lives as long as the app.
Calling builder.Services.BuildServiceProvider() yourself to fetch a service during startup. That builds a second container with its own singletons, separate from the one the app uses.

Try it yourself

2 visible tests · 3 hidden tests

Model the container. registrations holds entries "Name:Lifetime" with lifetime Transient, Scoped or Singleton; if a name is registered more than once, the last entry's lifetime is the one used. resolutions holds entries "scope:Name", resolved in order. Scopes are identified by any string; the scope root stands for the root provider, and a scoped service resolved from the root is cached in the root exactly like any other scope.

Implement Labels(List<string> registrations, List<string> resolutions) returning one label per resolution, in order, shaped "Name#k", where k counts instances of that service in creation order starting at 1. Every name resolved is registered.

Labels(["Clock:Singleton","Db:Scoped","Mapper:Transient"], ["r1:Clock","r1:Db","r1:Db","r1:Mapper","r2:Clock","r2:Db","r2:Mapper"])
Labels(["Db:Scoped"], ["a:Db","b:Db","a:Db","b:Db","c:Db"])

Loading editor…