Stashbox Dependency Injection Framework

Stashbox supports .NET variance for generic interfaces using the in and out keywords. Variance checking is enabled by default.

• Contravariance (in): Allows argument types that are less derived than the defined generic parameter. For example, an IEventHandler<IGeneralEvent> can be resolved as an IEventHandler<IUpdatedEvent> if the interface is marked in.
• Covariance (out): Allows argument types that are more derived than the defined generic parameter. For example, an IEventHandler<IUpdatedEvent> can be resolved as an IEventHandler<IGeneralEvent> if the interface is marked out.

Note: You can disable variance checking via container configuration options.

// Contravariance Example
interface IEventHandler<in TEvent> { } 
interface IGeneralEvent { }
interface IUpdatedEvent : IGeneralEvent { }
class GeneralEventHandler : IEventHandler<IGeneralEvent> { }

container.Register<IEventHandler<IGeneralEvent>, GeneralEventHandler>();
// Returns GeneralEventHandler because IGeneralEvent is less derived than IUpdatedEvent
IEnumerable<IEventHandler<IUpdatedEvent>> eventHandlers = container.ResolveAll<IEventHandler<IUpdatedEvent>>();

// Covariance Example
interface IEventHandler<out TEvent> { } 
// Returns both GeneralEventHandler and UpdatedEventHandler because IUpdatedEvent is more derived than IGeneralEvent
IEnumerable<IEventHandler<IGeneralEvent>> eventHandlers = container.ResolveAll<IEventHandler<IGeneralEvent>>();

Using the dependency resolver parameter inside a factory delegate creates a "black box" for the container. This can bypass critical validations for lifetime (e.g., captive dependencies) and circular dependencies because the container cannot see the resolution tree inside the delegate.

Recommended Pattern: Instead of using the resolver, let the container inject the required dependencies directly into the factory delegate as parameters. This ensures the resolution tree remains stable and all parameters are validated.

// RECOMMENDED: Dependencies are injected as parameters
container.Register<IEventProcessor, EventProcessor>(options => options
    .WithFactory<ILogger, IEventValidator>((logger, validator) => 
        new EventProcessor(logger, validator)));

// AVOID: Using the resolver inside the delegate
container.Register<IEventProcessor, EventProcessor>(options => options
    .WithFactory(resolver => 
        new EventProcessor(resolver.Resolve<ILogger>(), resolver.Resolve<IEventValidator>())));

Open-generic types (generic types without specific arguments, e.g., IValidator<>) allow you to register a single generic definition that Stashbox uses to satisfy various closed-generic requests.

When a matching closed service type is requested, Stashbox automatically binds the type parameters to construct the appropriate closed-generic implementation.

Priority Rule: A registered closed-generic type always takes priority over an open-generic type during service selection.

// Register the open-generic definition
container.Register(typeof(IValidator<>), typeof(Validator<>));

// Stashbox binds the type parameters automatically
IValidator<User> userValidator = container.Resolve<IValidator<User>>();
IValidator<Role> roleValidator = container.Resolve<IValidator<Role>>();

// Priority Example: Closed-generic registration overrides open-generic
container.Register<IValidator<User>, UserValidator>();
container.Register(typeof(IValidator<>), typeof(Validator<>));
// UserValidator will be returned instead of Validator<User>
IValidator<User> validator = container.Resolve<IValidator<User>>();

An ICompositionRoot is an entry point used to define how services are wired together for a specific component or assembly. This helps modularize the registration logic.

Implementation: Implement ICompositionRoot and define your registration logic inside the Compose(IStashboxContainer container) method. Your implementation can itself have dependencies that the container resolves.

Usage:

• container.ComposeBy<TRoot>(): Wires up a specific composition root implementation.
• container.ComposeAssembly(Assembly assembly): Automatically finds and executes all ICompositionRoot implementations within the specified assembly.
• container.ComposeBy<TRoot>(object dependencyOverride): Wires up a specific root while providing an override for its dependencies.

class ExampleRoot : ICompositionRoot
{
    public ExampleRoot(IDependency rootDependency) { }

    public void Compose(IStashboxContainer container)
    {
       container.Register<IServiceA, ServiceA>();
       container.Register<IServiceB, ServiceB>();
    }
}

// Usage patterns:
container.ComposeBy<ExampleRoot>(); // Single
container.ComposeAssembly(typeof(IServiceA).Assembly); // Assembly
container.ComposeBy<ExampleRoot>(new CustomRootDependency()); // Override

Child containers allow you to build hierarchical relationships where a child container can contain a different subset of services than its parent.

Key behaviors:

• Resolution Fallback: If a service is missing in the child, Stashbox asks the parent. If found in the parent, the parent returns the registration, and the resolution process jumps back to the child to resolve dependencies.
• Overriding: Registrations in a child container with the same service type will override the parent's services.
• Lifecycle: By default, disposing a parent container also disposes all its child containers. You can decouple this by setting attachToParent: false in CreateChildContainer().
• Multi-tenancy: Child containers are the foundation for the ASP.NET Core multi-tenant extension.

interface IDependency {}
class B : IDependency {}
class C : IDependency {}
class A { public A(IDependency dependency) { } }

using (var container = new StashboxContainer())
{
    container.Register<A>();
    container.Register<IDependency, B>();

    var child = container.CreateChildContainer();
    child.Register<IDependency, C>();
    
    // 'A' is resolved from parent but gets 'C' (from child) as its dependency
    A fromChild = child.Resolve<A>();

    // 'A' gets 'B' (from parent) as its dependency
    A fromParent = container.Resolve<A>();
}