Pure.DI Documentation

Pure.DI is a C# code generator for dependency injection that builds the dependency graph at compile-time. Instead of using a runtime container with reflection or service locators, it generates standard C# code (essentially a chain of new calls) to instantiate objects.

Key Concepts

• Compile-Time Generation: The generator analyzes your dependency graph, validates it (checking for missing dependencies, cycles, or inaccessible constructors), and generates a partial composition class.
• Zero Overhead: Since the output is plain C# code, there is no runtime reflection, no assembly scanning, and no hidden allocations typical of traditional DI containers.
• Composition Roots: Instead of calling Resolve<T>() from anywhere, Pure.DI uses explicit properties or methods in a composition class as entry points to the object graph.
• Built-in BCL Support: It natively supports common .NET Base Class Library types like Func<>, Lazy<>, IEnumerable<>, Task, ValueTask, Span, and Tuple.

// Pure.DI generates code that effectively performs:
var service = new CheckoutService(new PaymentGatewayClient(new HttpClient(), "api-key"), new ConsoleLogger());

By default, Pure.DI manages disposables per composition. However, you can use the Owned<T> type to track and dispose of disposable instances per a specific composition root.

To implement this, declare your root using .Root<Owned<T>>("Name"). Each time you access this root property on the Composition instance, it returns an Owned<T> wrapper. This wrapper owns every disposable instance created within that specific dependency graph. Calling .Dispose() on the Owned<T> instance cleans up exactly those instances associated with that specific access, without affecting other roots or instances created from the same composition.

// Setup the composition with an Owned root
partial class Composition
{
    static void Setup() =>
        DI.Setup()
            .Bind().To<DbConnection>()
            .Bind().To<OrderProcessingService>()
            .Root<Owned<IOrderProcessingService>>("OrderProcessingService");
}

// Usage
var composition = new Composition();
var service1 = composition.OrderProcessingService;
var service2 = composition.OrderProcessingService;

// Disposing service2 only cleans up its specific dependency graph
service2.Dispose();

// service1.Value.DbConnection remains alive
// service2.Value.DbConnection is now disposed

Recent releases have introduced several advanced features for DI configuration and performance:

DI Configuration & Contracts

• Union types as DI contracts: Using union types to define dependency requirements.
• Interface generation: Automatically generating interfaces from classes using [GenerateInterface].
• Attribute-based bindings: Defining bindings directly in implementations using attributes like [Bind], [Type], [Tag], and [Lifetime].
• [Export] attribute: Using class members as dependency sources.
• Custom binding attributes: Support for user-defined binding attributes.
• Nullable Reference Types: Full support for nullable reference types.
• TryBuildUp: A mechanism for safe object 'completion' or 'building up'.

Scopes

• SetupScope for general DI setup.
• Unity-specific scene scopes.
• CreateScope() for integration with Microsoft DI.

High-Performance & Hot Path DI

• Stack-only support: Support for Span<T>, ReadOnlySpan<T>, and ref struct dependencies.
• Ref struct factories: Factories that allow allows ref struct.
• Zero-copy patterns: Support for zero-copy parsing and method injection on hot paths.
• Non-boxing union results: Optimized handling of union types to avoid boxing.
• Advanced performance patterns: Support for ArrayPool, object pools, closure-free factories, ValueTask<T> roots, and ThreadSafe = Off configurations.

Pure.DI allows you to collect all registered implementations of a generic interface into an IEnumerable<T>. This is particularly useful for implementing middleware patterns or plugin architectures where multiple handlers must be invoked in sequence.

When you bind a generic type (e.g., IMiddleware<TT>) to an implementation (e.g., LoggingMiddleware<TT>), Pure.DI tracks all such bindings. When a consumer requests IEnumerable<IMiddleware<T>>, the generated composition root provides an enumeration containing all matching implementations, including those with specific tags.

using Pure.DI;
using System.Collections.Immutable;

DI.Setup(nameof(Composition))
    // Register generic middleware components.
    .Bind<IMiddleware<TT>>().To<LoggingMiddleware<TT>>()
    // Register with a specific tag
    .Bind<IMiddleware<TT>>("Metrics").To<MetricsMiddleware<TT>>()

    // Register the pipeline that consumes the collection
    .Bind<IPipeline<TT>>().To<Pipeline<TT>>()

    // Define composition roots
    .Root<IPipeline<int>>("IntPipeline")
    .Root<IPipeline<string>>("StringPipeline");

var composition = new Composition();
var intPipeline = composition.IntPipeline;
// intPipeline.Middlewares will contain both LoggingMiddleware<int> and MetricsMiddleware<int>

In Pure.DI, ctx.ConsumerType provides access to the type of the class that is currently receiving the dependency being resolved. This is particularly useful for creating context-aware objects, such as loggers that are automatically tagged with the name of the consuming class.

When using .Bind().To(ctx => { ... }), you can access ctx.ConsumerType to customize the instance returned based on where it is being injected.

DI.Setup(nameof(Composition))
    .Arg<Serilog.ILogger>("logger", "from arg")
    .Bind().To(ctx => {
        ctx.Inject<Serilog.ILogger>("from arg", out var logger);

        // ctx.ConsumerType represents the type into which the dependency is being injected.
        // This allows logs to be tagged with the name of the class that created them.
        return logger.ForContext(ctx.ConsumerType);
    })
    .Bind().To<Dependency>()
    .Bind().To<Service>()
    .Root<IService>(nameof(Root));

When configuring a factory, you can control how far override values propagate into the dependency graph. This is useful when you want to override a constructor parameter for a specific class without affecting its nested dependencies.

Deep Overrides (ctx.Override)

Using ctx.Override(value) inside a factory binding causes the override to propagate into the entire nested dependency graph. Any dependencies required by the object being injected will also receive this overridden value if they are of the same type.

Shallow Overrides (ctx.Let)

Using ctx.Let(value) inside a factory binding keeps the override local to the immediate injection level. The object being injected will use the overridden value, but its nested dependencies will continue to use the original values defined in the DI setup.

Summary Table

// Deep Override: Dependency.Id will also be 42
DI.Setup("Deep")
    .Bind().To<Service>(ctx =>
    {
        ctx.Override(42);
        ctx.Inject(out Service service);
        return service;
    })
    .Root<Service>("Service");

// Shallow Override: Dependency.Id remains the original bound value (e.g., 7)
DI.Setup("Shallow")
    .Bind().To<Service>(ctx =>
    {
        ctx.Let(42);
        ctx.Inject(out Service service);
        return service;
    })
    .Root<Service>("Service");

The PerResolve lifetime ensures that a single instance of a dependency is shared within a single resolution of a composition root. This is ideal for request-scoped context (e.g., locale, pricing rules, or feature flags) where you want all dependencies in a single 'planning session' or request to see the same instance, but want a fresh instance for every new root access.

To use it, bind your type using .Bind().As(PerResolve).To<T>().

using Pure.DI;
using static Pure.DI.Lifetime;

DI.Setup(nameof(Composition))
    .Bind().As(PerResolve).To<RoutePlanningSession>()
    .Root<TrainTripPlanner>("Planner");

var composition = new Composition();

// Every time you access the root, you get a new PerResolve instance
var plan1 = composition.Planner;
var plan2 = composition.Planner;

// plan1.SessionForOutbound will be the same as plan1.SessionForReturn
// plan2.SessionForOutbound will NOT be the same as plan1.SessionForOutbound