Snowberry.DependencyInjection
6.0.0
dotnet add package Snowberry.DependencyInjection --version 6.0.0
NuGet\Install-Package Snowberry.DependencyInjection -Version 6.0.0
<PackageReference Include="Snowberry.DependencyInjection" Version="6.0.0" />
<PackageVersion Include="Snowberry.DependencyInjection" Version="6.0.0" />
<PackageReference Include="Snowberry.DependencyInjection" />
paket add Snowberry.DependencyInjection --version 6.0.0
#r "nuget: Snowberry.DependencyInjection, 6.0.0"
#:package Snowberry.DependencyInjection@6.0.0
#addin nuget:?package=Snowberry.DependencyInjection&version=6.0.0
#tool nuget:?package=Snowberry.DependencyInjection&version=6.0.0
Snowberry.DependencyInjection
A lightweight, fast IoC container for .NET with singleton, scoped and transient lifetimes, keyed services, open generics, property injection and graph validation. It targets .NET 11, .NET 10 and .NET Standard 2.0, is trimming and Native AOT compatible, and matches or beats Microsoft.Extensions.DependencyInjection on warm resolves with identical allocations.
Unlike build-once providers the container stays mutable: you can keep registering while the application runs, and with read-only mode turned off you can also overwrite and remove registrations. When configuration is final, an opt-in Freeze() validates the graph and locks it in for maximum speed. The contracts live in Snowberry.DependencyInjection.Abstractions, which this package references.
Table of Contents
- Installation
- Quick Start
- Top Features at a Glance
- Service Lifetimes
- Registration
- Scopes
- Injection Attributes
- Validation
- Freezing
- Disposal
- Native AOT and Trimming
- How It Works
- Pitfalls
- Related Packages
Installation
dotnet add package Snowberry.DependencyInjection
Quick Start
using Snowberry.DependencyInjection;
using Snowberry.DependencyInjection.Abstractions.Extensions;
// 1. Create the container (it disposes the instances it creates).
await using var container = new ServiceContainer();
// 2. Register services with a lifetime.
container.RegisterSingleton<IClock, SystemClock>();
container.RegisterScoped<IUnitOfWork, UnitOfWork>();
container.RegisterTransient<OrderService>();
// 3. Optional: validate the graph and lock the configuration.
container.Freeze();
// 4. Resolve inside a scope; scoped services live until the scope is disposed.
using (var scope = container.CreateScope())
{
var orders = scope.ServiceProvider.GetRequiredService<OrderService>();
orders.Place("book");
}
public interface IClock { DateTime UtcNow { get; } }
public sealed class SystemClock : IClock { public DateTime UtcNow => DateTime.UtcNow; }
public interface IUnitOfWork { void Commit(); }
public sealed class UnitOfWork : IUnitOfWork, IDisposable
{
public void Commit() { }
public void Dispose() { }
}
public sealed class OrderService(IClock clock, IUnitOfWork unitOfWork)
{
public void Place(string item)
{
Console.WriteLine($"{clock.UtcNow:O}: {item}");
unitOfWork.Commit();
}
}
Top Features at a Glance
- Three lifetimes plus keys. Singleton, scoped and transient registrations, each optionally keyed with any object, resolved through
GetRequiredService<T>()orGetRequiredKeyedService<T>(key). - Constructor and property injection. The constructor with the most parameters is used (or the one marked
[PreferredConstructor]);[Inject]properties are filled after construction;[FromKeyedServices]picks a keyed dependency. - Open generics. Register
IRepository<>once and resolve any closedIRepository<T>. - Fail-fast validation.
Validate()/TryValidate()report missing dependencies, cycles and unconstructable types without constructing anything. - Mutable or frozen. Keep the container mutable for runtime reconfiguration, or
Freeze()it to lock registrations and inline whole transient subtrees. - Fast and lean. Warm singleton and scoped resolves allocate nothing; activation starts on reflection and compiles to expression trees on reuse, so startup stays cheap.
- Safe disposal. Created instances are disposed in reverse order, synchronously or with
DisposeAsync; a throwing instance never stops the others from being disposed. - Native AOT ready. Fully annotated for trimming; under Native AOT the reflection path is used and the expression compiler is trimmed away.
Service Lifetimes
| Lifetime | Instances | Disposed by |
|---|---|---|
| Singleton | One per container. | The container. |
| Scoped | One per scope. | The scope that created it. |
| Transient | A new instance on every resolve. | The scope that created it. |
container.RegisterSingleton<IFoo, Foo>();
container.RegisterScoped<IBar, Bar>();
container.RegisterTransient<IBaz, Baz>();
Registration
Instances and factories. Register a pre-built singleton instance (never disposed by the container), or a factory that receives the resolving provider and the service key:
container.RegisterSingleton<IFoo>(instance: new Foo());
container.RegisterTransient<IBar>((serviceProvider, serviceKey) => new Bar());
Keyed services. Every Register* method takes an optional service key:
container.RegisterTransient<IFoo, Foo>("primary");
var foo = container.GetRequiredKeyedService<IFoo>("primary");
Open generic types. Register the generic type definitions through a ServiceDescriptor:
using Snowberry.DependencyInjection.Abstractions.Implementation;
container.Register(ServiceDescriptor.Transient(typeof(IRepository<>), typeof(Repository<>)));
var repository = container.GetRequiredService<IRepository<User>>();
Register only once. The TryRegister* methods return false instead of replacing or throwing when the service is already registered:
bool added = container.TryRegisterSingleton<IFoo, Foo>();
Overwriting and removing. By default the container is read-only for existing registrations (ServiceContainerOptions.Default is ReadOnly): registering a service twice or unregistering it throws ServiceRegistryReadOnlyException. Clear the flag to allow both:
var container = new ServiceContainer(ServiceContainerOptions.Default & ~ServiceContainerOptions.ReadOnly);
container.RegisterTransient<IFoo, Foo>();
container.RegisterSingleton<IFoo, OtherFoo>(); // replaces the registration
container.UnregisterService<IFoo>(serviceKey: null, out bool removed);
Instances created before a change are still disposed as usual. Unregistering a singleton disposes its current instance immediately when it implements IDisposable, including an instance you supplied.
Scopes
container.RegisterScoped<IUnitOfWork, UnitOfWork>();
using (var scope = container.CreateScope())
{
// Created for this scope and disposed when the scope is disposed.
var unitOfWork = scope.ServiceProvider.GetRequiredService<IUnitOfWork>();
}
Resolving a scoped service directly from the container uses the container's own root scope, so the instance lives as long as the container. To make that an error instead, enable scope validation:
var container = new ServiceContainer(ServiceContainerOptions.Default | ServiceContainerOptions.ValidateScopes);
// Resolving a scoped service from the container now throws ServiceScopeRequiredException.
Injection Attributes
InjectAttribute ([Inject])
Injects a service into a property after construction.
- Valid on properties with a setter. Cannot be applied more than once. Inherited.
- Required by default: if the service is not registered, resolution throws
ServiceTypeNotRegistered. PassisRequired: falseto make it optional; an unregistered optional service assignsnull(or the default value of a value type) to the property. - Can be combined with
[FromKeyedServices].
[Inject]
public IFoo Foo { get; set; } = null!;
[Inject(isRequired: false)]
public ILogger? OptionalLogger { get; set; }
FromKeyedServicesAttribute ([FromKeyedServices])
Selects which keyed service to use for a property or constructor parameter.
- Valid on properties and parameters. Cannot be applied more than once. Inherited.
- On a property, combine it with
[Inject]; on a constructor parameter it works on its own.
// Property:
[Inject]
[FromKeyedServices("primary")]
public IFoo? PrimaryFoo { get; set; }
// Constructor parameter:
public MyService([FromKeyedServices("primary")] IFoo foo) { }
PreferredConstructorAttribute ([PreferredConstructor])
Specifies which constructor the container uses. Without it, the public constructor with the most parameters is chosen.
- Valid on constructors only. Cannot be applied more than once. Not inherited.
- Not needed when the type has a single public constructor.
public class MyService
{
public MyService() { }
[PreferredConstructor]
public MyService(IFoo foo) { }
}
Constructor parameters with a non-null default value are optional: when their service is not registered, the default is passed.
Validation
Check the whole registered graph up front ("fail fast at startup") without constructing any instances. The container stays mutable; run it again after further changes.
// Throws ServiceValidationException listing every problem.
container.Validate();
// Or collect the problems without throwing.
if (!container.TryValidate(out var errors))
{
foreach (var error in errors)
Console.WriteLine($"{error.Kind}: {error.Message}"); // MissingDependency, CircularDependency, NoPublicConstructor
}
Factory and instance registrations are treated as opaque, and open generic registrations are checked structurally only. Missing required dependencies and dependency cycles also surface at resolve time (ServiceTypeNotRegistered, CircularDependencyException).
Freezing
When configuration is complete, Freeze() locks the container for the fastest resolves:
container.Freeze(); // validates first; Freeze(validate: false) skips validation
bool locked = container.IsFrozen;
container.RegisterTransient<IBaz, Baz>(); // throws ServiceRegistryReadOnlyException
- Validates by default.
Freeze()runsValidate()first; on a problem it throwsServiceValidationExceptionand the container stays mutable. - One-way and idempotent. Freezing again is a no-op and does not re-validate.
- Stronger than
ReadOnly.ServiceContainerOptions.ReadOnlyblocks overwriting and removing; freezing blocks every registration change, including new ones. - Inlines whole transient subtrees. A frozen container constructs non-disposable transient dependencies directly inside their parent, which mainly speeds up deep graphs.
| Mode | Add / remove / overwrite | Warm-resolve speed |
|---|---|---|
| Mutable (default) | Add; remove and overwrite when not read-only | Fast: at or ahead of MS.DI on singleton, scoped and transient |
Frozen (Freeze()) |
No (locked) | Fastest for deep graphs: full transient-subtree inlining |
Disposal
Dispose the container (Dispose() or await container.DisposeAsync()) when you are done, and dispose every scope you create. Each disposes the instances it created, in reverse creation order; instances you registered yourself are not disposed (unless you unregister them, see Registration).
- Every instance is disposed, even when some throw. A single failure is rethrown unchanged; several failures are thrown together as an
AggregateException, in disposal order. This matchesMicrosoft.Extensions.DependencyInjectionfrom .NET 11 on. - Async-only services need
DisposeAsync. SynchronousDisposereports an instance that only implementsIAsyncDisposableas anInvalidOperationException, after disposing the rest. - Disposed means closed. Resolving from a disposed scope or container throws
ObjectDisposedException.
Native AOT and Trimming
The library is annotated for trimming and Native AOT (IsAotCompatible), and the registration APIs carry [DynamicallyAccessedMembers] so the constructors and properties of registered types are preserved. Under Native AOT activation always runs through ConstructorInvoker (reflection) instead of compiled expression trees.
- Register closed generic types. Open generic registrations close the implementation with
MakeGenericTypeat runtime, which needs dynamic code. - Prefer factories for full control. A factory registration runs no reflection at all.
CreateInstanceis not AOT-safe.IServiceProvider.CreateInstance(...)constructs unregistered types and is annotated[RequiresUnreferencedCode]/[RequiresDynamicCode].
How It Works
Every service gets a resolver, cached per container. The first resolve builds the resolver graph for the requested type; later resolves are a dictionary lookup plus a delegate call.
GetService<T>()
|
v
resolver cache --hit--> invoke resolver --> instance
| miss
v
build resolver graph: select constructor, collect [Inject] properties,
capture each dependency's resolver (cycles throw CircularDependencyException)
|
v
1st activation: construct through reflection (ConstructorInvoker)
2nd activation: compile an expression tree and swap it in
(skipped for singletons and under Native AOT)
Singletons are baked into constants after their first construction, and scoped instances are read lock-free, so warm singleton and scoped resolves allocate nothing. A registration change discards the cached resolvers, which rebuild on the next resolve; this is what keeps a mutable container correct. See ARCHITECTURE.md for diagrams of the resolver graph and the mutable to frozen lifecycle, and the benchmark results for numbers against Microsoft.Extensions.DependencyInjection.
Pitfalls
- Registering a service twice throws by default.
ServiceContainerOptions.DefaultisReadOnly, so overwriting or unregistering throwsServiceRegistryReadOnlyException. ClearReadOnlyif you reconfigure at runtime, or useTryRegister*. - Scoped services resolved from the container live as long as the container. They come from the root scope. Resolve them from
CreateScope(), and enableValidateScopesto catch mistakes. - An explicit
= nulldefault does not make a constructor parameter optional. Only a non-null default value does; a parameter declaredIFoo? foo = nullis still required. - Optional
[Inject(false)]properties are overwritten. When the service is not registered the property is set tonull(or default), replacing any initializer value. - Synchronous
Disposecannot dispose async-only services. Useawait container.DisposeAsync()(andDisposeAsyncon scopes) when any service only implementsIAsyncDisposable. - The second resolve of a type pays for compilation. The first activation is cheap reflection; the second compiles the expression tree once. Warm up hot paths at startup if that one-time cost matters.
- Open generics need dynamic code. Under Native AOT, register the closed generic types you resolve.
Related Packages
| Package | Purpose |
|---|---|
| Snowberry.DependencyInjection.Abstractions | Interfaces, attributes, ServiceDescriptor and the registration and resolution extension methods. |
| Snowberry.Mediator.DependencyInjection | Registers Snowberry.Mediator handlers in this container. |
| Snowberry.Mediator.OpenTelemetry | Snowberry.Mediator OpenTelemetry tracing and metrics, wired through this container. |
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Snowberry.DependencyInjection.Abstractions (>= 6.0.0)
-
net10.0
- Snowberry.DependencyInjection.Abstractions (>= 6.0.0)
-
net11.0
- Snowberry.DependencyInjection.Abstractions (>= 6.0.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Snowberry.DependencyInjection:
| Package | Downloads |
|---|---|
|
Snowberry.Mediator.DependencyInjection
Extension for the main package to work with `Snowberry.DependencyInjection`. |
|
|
Snowberry.Mediator.OpenTelemetry
Snowberry.DependencyInjection integration for Snowberry.Mediator OpenTelemetry. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated | |
|---|---|---|---|
| 6.0.0 | 201 | 11/12/2026 | |
| 5.2.0 | 1,661 | 5/31/2026 | |
| 5.1.1 | 2,001 | 1/28/2026 | |
| 5.1.0 | 729 | 11/15/2025 | |
| 5.0.0.2 | 510 | 11/4/2025 | |
| 5.0.0.1 | 398 | 11/4/2025 | |
| 5.0.0 | 409 | 11/4/2025 | |
| 4.0.0 | 327 | 10/7/2025 | |
| 3.8.0 | 469 | 9/22/2025 | |
| 3.7.0 | 336 | 8/1/2025 | |
| 3.6.0 | 794 | 11/14/2024 | |
| 3.5.0 | 533 | 10/9/2024 | |
| 3.4.0 | 793 | 8/28/2024 | |
| 3.3.0 | 2,085 | 3/28/2024 | |
| 3.2.0 | 1,189 | 1/31/2024 | |
| 3.1.0 | 382 | 1/31/2024 | |
| 3.0.0 | 394 | 1/31/2024 | |
| 2.0.0 | 907 | 12/20/2023 | |
| 1.0.3 | 2,274 | 3/8/2023 |