simpleinjector Wiki Rss Feed

Updated Wiki: Self Hosted Web API Integration

dot_NET_Junkie — Tue, 21 May 2013 12:45:58 GMT

WARNING: Unfortunately the implementation below is flawed and can't be used in a self hosted Web API. Please see here for more information.

ASP.NET Web API Integration Guide for Self Hosted Environments

When running ASP.NET Web API in a self hosted environment, there is no HttpContext, which means that Per Request lifestyle lifestyles can not be used. In that case the Per Lifetime Scope lifestyle can be used instead, but this requires a IDependencyResolver that uses scoping (since Per Lifetime Scope is thread-specific, it can't be wrapped around a HTTP request, since ASP.NET can finish the request on a different thread than where it was started).

The following code snippet defines a SelfHostedSimpleInjectorWebApiDependencyResolver class for a self hosted ASP.NET Web API application. You can create a new C# file in your Web API project and copy paste the code below into it.

using System;
using System.Collections.Generic;
using System.Web.Http.Dependencies;

using SimpleInjector;
using SimpleInjector.Extensions.LifetimeScoping;

public class SelfHostedSimpleInjectorWebApiDependencyResolver
    : IDependencyResolver
{
    private readonly Container container;
    private readonly LifetimeScope lifetimeScope;

    public SelfHostedSimpleInjectorWebApiDependencyResolver(
        Container container)
        : this(container, false)
    {
    }

    private SelfHostedSimpleInjectorWebApiDependencyResolver(
        Container container, bool createScope)
    {
        this.container = container;

        if (createScope)
        {
            this.lifetimeScope = container.BeginLifetimeScope();
        }
    }

    public IDependencyScope BeginScope()
    {
        return new SelfHostedSimpleInjectorWebApiDependencyResolver(
            this.container, true);
    }

    public object GetService(Type serviceType)
    {
        return ((IServiceProvider)this.container)
            .GetService(serviceType);
    }

    public IEnumerable<object> GetServices(Type serviceType)
    {
        return this.container.GetAllInstances(serviceType);
    }

    public void Dispose()
    {
        if (this.lifetimeScope != null)
        {
            this.lifetimeScope.Dispose();
        }
    }
}

The following code snippet shows how to use the SelfHostedSimpleInjectorWebApiDependencyResolver extension method.

// Create the container as usual.
var container = new Container();

// Register your types, for instance:
container.Register<IUserRepository, SqlUserRepository>();
container.RegisterLifetimeScope<IUnitOfWork, EfUnitOfWork>();

// Create your self-host configuration
var configuration = new HttpSelfHostConfiguration(uriBuilder.Uri);

configuration.Routes.MapHttpRoute(
	name: "Default Route",
	routeTemplate: "api/{controller}/{id}",
	defaults: new { id = RouteParameter.Optional });

configuration.DependencyResolver =
	new SelfHostedSimpleInjectorWebApiDependencyResolver(container);

var server = new HttpSelfHostServer(configuration);

// Start the server etc...

New Comment on "Self Hosted Web API Integration"

dot_NET_Junkie — Tue, 21 May 2013 12:42:42 GMT

You can set the DependencyResolver property on the created HttpSelfHostConfiguration instance.

New Comment on "Self Hosted Web API Integration"

kavand — Sun, 19 May 2013 12:01:48 GMT

Hey. The `GlobalConfiguration` does not exist in `Microsoft.AspNet.WebApi.SelfHost`. So, what should we do? Adding a reference to `Microsoft.AspNet.WebApi.WebHost` or there is another way to do this? Thanks in advance.

Updated Wiki: How-to

dot_NET_Junkie — Fri, 17 May 2013 10:49:55 GMT

How To...

How to Register factory delegates
How to Resolve instances by key
How to Resolve array and lists
How to Register multiple interfaces with the same implementation
How to Override existing registrations
How to Verify the container's configuration
How to Work with dependency injection in multi-threaded applications

Register factory delegates

Simple Injector allows you to register a Func<T> delegate for the creation of an instance. This is especially useful in scenarios where it is impossible for the container to create the instance. There are overloads of the Register method available that accept an Func<T> argument:

container.Register<IMyService>(() => SomeSubSystem.CreateMyService());

In situations where a service needs to create multiple instances of a certain dependencies, or needs to explicitly control the lifetime of such dependency, abstract factories can be used. Instead of injecting an IMyService, you should inject an IMyServiceFactory that allows services to create new instances of IMyService:

// Definition
public interface IMyServiceFactory
{
    IMyService CreateNew();
}

// Implementation
sealed class ServiceFactory : IMyServiceFactory
{
    public IMyService CreateNew()
    {
        return new MyServiceImpl();
    }
}

// Registration
container.RegisterSingle<IMyServiceFactory, ServiceFactory>();

// Usage
public class MyService
{
    private readonly IMyServiceFactory factory;
    
    public MyService(IMyServiceFactory factory)
    {
        this.factory = factory;
    }
    
    public void SomeOperation()
    {
        using (var service1 = this.factory.CreateNew())
        {
            // use service 1
        }

        using (var service2 = this.factory.CreateNew())
        {
            // use service 2
        }
    }
}

Instead of creating specific interfaces for your factories, you can also choose to inject Func<T> delegates into your services:

// Registration
container.RegisterSingle<Func<IMyService>>(
    () => new MyServiceImpl());

// Usage
public class MyService
{
    private readonly Func<IMyService> factory;
    
    public MyService(Func<IMyService> factory)
    {
        this.factory = factory;
    }
    
    public void SomeOperation()
    {
        using (var service1 = this.factory.Invoke())
        {
            // use service 1
        }
    }
}

This saves you from having to define a new interface and implementation per factory.

Note: On the downside however, this communicates less clearly the intend of your code and as a result might make your code harder to grasp for other developers.

When you choose Func<T> delegates over specific factory interfaces, you can define the following extension method that makes it easier to register Func<T> factories:

// Extension method
container.RegisterFuncFactory<TService, TImplementation>(
    this Container container,
    Lifestyle lifestyle = null)
    where T : class
{
    lifestyle = lifestyle ?? Lifestyle.Transient;

    // Register the type explicitly to keep the configuration
    // verifiable.
    container.Register<TService, TImplementation>(lifestyle);
    
    // Register the Func<T> that resolves that instance.
    container.RegisterSingle<Func<TService>>(
        () => container.GetInstance<TService>());
}

// Registration
container.RegisterFuncFactory<IMyService, RealService>();

The previous extension method allowed registration of a single factory, but won't be maintainable when you want all registrations to be resolvable using Func<T> delegates by default.

Note: We personally think that allowing to register Func<T> delegates by default is a design smell. The use of Func<T> delegates makes your design harder to follow and your system harder to maintain and test. If you have many constructors in your system that depend on a Func<T>, please take a good look at your dependency strategy. If in doubt, please ask us here on CodePlex or on Stackoverflow.

The following extension method allows Simple Injector to resolve all types using a Func<T> delegate by default:

public static void AllowResolvingFuncFactories(
    this ContainerOptions options)
{
    var container = options.Container;

    container.ResolveUnregisteredType += (sender, e) =>
    {
        if (e.UnregisteredServiceType.IsGenericType &&
            e.UnregisteredServiceType.GetGenericTypeDefinition() ==
                typeof(Func<>))
        {
            Type serviceType = e.UnregisteredServiceType
                .GetGenericArguments().First();

            InstanceProducer registration =
                container.GetRegistration(serviceType);

            if (registration != null)
            {
                Type funcType =
                    typeof(Func<>).MakeGenericType(serviceType);

                var factoryDelegate = 
                    Expression.Lambda(funcType,
                        registration.BuildExpression())
                    .Compile();

                e.Register(Expression.Constant(factoryDelegate));
            }
        }
    };
}

// Registration
container.Options.AllowResolvingFuncFactories();

After calling the AllowResolvingFuncFactories extension method, the container allows resolving Func<T> delegates.

Just like Func<T> delegates can be injected, Lazy<T> instances can be injected into services. Lazy<T> is useful in situations where the creation of a service is time consuming, but is not always used. Thus Lazy<T> allows you to postpone the creation of that service until the moment that it is really needed:

// Extension method
container.RegisterLazy<T>(this Container container)
    where T : class
{
    Func<T> factory = () => container.GetInstance<T>();

    container.Register<Lazy<T>>(() => new Lazy<T>(factory));
}

// Registration    
container.RegisterLazy<IMyService>();

// Usage
public class MyService
{
    private readonly Lazy<IMyService> myService;
    
    public MyService(Lazy<IMyService> myService)
    {
        this.myService = myService;
    }
    
    public void SomeOperation()
    {
        if (someCondition)
        {
            this.myService.Value.Operate();
        }
    }
}

Note that instead of polluting the API of your application with Lazy<T> dependencies, it is usually cleaner to hide the Lazy<T> behind a proxy:

// Proxy definition
public class MyLazyServiceProxy : IMyService
{
    private readonly Lazy<IMyService> wrapped;
    
    public MyLazyServiceProxy(Lazy<IMyService> wrapped)
    {
        this.wrapped = wrapped;
    }
    
    public void Operate()
    {
        this.wrapped.Value.Operate();
    }
}

// Registration
container.RegisterLazy<IMyService>();
container.Register<IMyService, MyLazyServiceProxy>();

This way the application can simply depend on IMyService instead of Lazy<IMyService>.

Warning: The same warning applies to the use of Lazy<T> as it does for the use of Func<T> delegates. For more information about creating an application and container configuration that can be successfully verified, please read the How To Verify the container’s configuration.

Resolve instances by key

Resolving instances by a key is a feature that is deliberately left out of the Simple Injector, because we feel it steers developers to a design were the application tends to have a dependency on the DI container itself. For resolving a keyed instance, you will often need to call into the container itself, which leads to the Service Locator anti-pattern.

This doesn’t mean however, that resolving instances by a key is never useful. Resolving instances by a key however, is much more a job for a specific factory than for a container itself. This makes the design much cleaner, saves you from having to take a dependency on the DI framework, and enables many scenarios that the DI container writer just didn’t consider.

Note: The need for keyed registration can be an indication of ambiguity in the application design. Take a good look if each keyed registration shouldn't have its own unique interface, or perhaps each registration should implement each own version of a generic interface.

Take a look at the following scenario, where we want to retrieve instances of type IRequestHandler by a string key. There are of course several ways to achieve this, but here is a simple but effective way, by defining an IRequestHandlerFactory:

// Definition
public interface IRequestHandlerFactory
{
    IRequestHandler CreateNew(string name);
}

// Usage
var factory =
    container.GetInstance<IRequestHandlerFactory>();
var handler = factory.CreateNew("customers");
handler.Handle(requestContext);

By inheriting from the BCL’s Dictionary<TKey, TValue>, creating an IRequestHandlerFactory implementation, is almost a one-liner:

public class RequestHandlerFactory
    : Dictionary<string, Func<IRequestHandler>>,
    IRequestHandlerFactory
{
    public IRequestHandler CreateNew(string name)
    {
        return this[name]();
    }
}

With this class, we can register Func<IRequestHandler> factory methods by a key. With this in place the registration of keyed instances is a breeze:

var container = new Container();
 
container.RegisterSingle<IRequestHandlerFactory>(
    new RequestHandlerFactory
{
    { "default", () => container.GetInstance<DefaultRequestHandler>() },
    { "orders", () => container.GetInstance<OrdersRequestHandler>() },
    { "customers", () => container.GetInstance<CustomersRequestHandler>() },
});

Note: this design will work with almost all DI containers, making this not only a design that is easy to follow, but making it very easy to migrate to another DI implementation.

If you don’t like a design that uses Func<T> delegates this way, it can easily be changed to be a Dictionary<string, Type> instead. The RequestHandlerFactory can be implemented as follows:

public class RequestHandlerFactory
    : Dictionary<string, Type>, IRequestHandlerFactory
{
    private readonly Container container;
    
    public RequestHandlerFactory(Container container)
    {
        this.container = container;
    }

    public IRequestHandler CreateNew(string name)
    {
        var handler = this.container.GetInstance(this[name]);
        return (IRequestHandler)handler;
    }
}

The registration will then look as follows:

var container = new Container();

container.RegisterSingle<IRequestHandlerFactory>(
    new RequestHandlerFactory(container)
{
    { "default", typeof(DefaultRequestHandler) },
    { "orders", typeof(OrdersRequestHandler) },
    { "customers", typeof(CustomersRequestHandler) },
});

Note: Please remember the previous note about ambiguity in the application design. In the given example the design would probably be better af by using a generic IRequestHandler<TRequest> interface. This would allow the implementations to be batch registered using a single line of code, saves you from using keys, and results in a configuration the is verifiable by the container.

A last option to do keyed registrations is to manually create registrations and store them in a dictionary. The following example shows previous RequestHandlerFactory with this approach:

public class RequestHandlerFactory : IRequestHandlerFactory
{
    private readonly Dictionary<string, InstanceProducer> producers =
        new Dictionary<string, InstanceProducer>(
            StringComparer.OrdinalIgnoreCase);

    private readonly Container container;

    public RequestHandlerFactory(Container container)
    {
        this.container = container;
    }

    IRequestHandler IRequestHandlerFactory.CreateNew(string name)
    {
        var handler = this.producers[name].GetInstance();
        return (IRequestHandler)handler;
    }

    public void Register<TImplementation>(string name,
        Lifestyle lifestyle = null)
        where TImplementation : class, IRequestHandler
    {
        lifestyle = lifestyle ?? Lifestyle.Transient;

        var registration = lifestyle
            .CreateRegistration<IRequestHandler, TImplementation>(container);

        var producer =
            new InstanceProducer(typeof(IRequestHandler), registration);

        this.producers.Add(name, producer);
    }
}

The registration will then look as follows:

var container = new Container();

var factory = new RequestHandlerFactory(container);

factory.Register<DefaultRequestHandler>("default");
factory.Register<OrdersRequestHandler>("orders");
factory.Register<CustomersRequestHandler>("customers");

container.RegisterSingle<IRequestHandlerFactory>(factory);

The advantage of this method is that it completely integrates with the container. For instance, decorators can be applied to individual returned instances and types can be registered multiple times if needed.

Resolve array and lists

The Simple Injector allows registration of collections of elements using the RegisterAll method overloads. Collections can be resolved by using one of the GetAllInstances<T>() method, by calling GetInstance<IEnumerable<T>>(), or by defining an IEnumerable<T> parameter in the constructor of a type that is created using automatic constructor injection.

Injection of other collection types, such as arrays of T or IList<T> into constructors is not supported out of the box. By hooking onto the unregistered type resolution event however, this functionality can be added. Look here for an example extension method that allows this behavior for T[] types.

Please take a look at your design if you think you need to work with a collection of items. Often you can succeed by creating a composite type that can be injected. Take the following interface for instance:

public interface ILogger
{
    void Log(string message);
}

Instead of injecting a collection of dependencies, the consumer might not really be interested in the collection, but simply wishes to operate on all elements. In that scenario you can configure your container to inject a composite of that particular type. That composite might look as follows:

public sealed class CompositeLogger : ILogger
{
    private readonly ILogger[] loggers;

    public CompositeLogger(params ILogger[] loggers)
    {
        this.loggers = loggers ?? new ILogger[0];
    }

    public void Log(string message)
    {
        foreach (var logger in this.loggers)
        {
            logger.Log(message);
        }
    }
}

A composite allows you to remove this boilerplate iteration logic from the application, which makes the application cleaner and when changes have to be made to the way the collection of loggers is processed, only the composite has to be changed.

Register multiple interfaces with the same implementation

To adhere to the Interface Segregation Principle, it is important to keep interfaces narrow. Although in most situations implementations implement a single interface, it can sometimes be beneficial to have multiple interfaces on a single implementation. Here is an example of how to register this:

// Impl implements IInterface1, IInterface2 and IInterface3.
var registration =
    Lifestyle.Singleton.CreateRegistration<Impl, Impl>(container);

container.AddRegistration(typeof(IInterface1), registration);
container.AddRegistration(typeof(IInterface2), registration);
container.AddRegistration(typeof(IInterface3), registration);

var a = container.GetInstance<IInterface1>();
var b = container.GetInstance<IInterface2>();

// Since Impl is a singleton, both requests return the same instance.
Assert.AreEqual(a, b);

The first line creates a Registration instance for the Impl, in this case with a singleton lifestyle. The other lines add this registration to the container, once for each interface. This maps multiple service types to the exact same registration.

Override existing registrations

The default behavior of the Simple Injector is to fail when a service is registered for a second time. Most of the time the developer didn't intend to override a previous registration and allowing this would lead to a configuration that would pass the container's verification, but doesn't behave as expected.

There are certain scenarios however where overriding is useful. An example of such is a bootstrapper project for a Business layer that is reused in multiple applications (in both a web application, web service, and Windows service for instance). Not having a business layer specific bootstrapper project would mean the complete DI configuration would be duplicated in the startup path of each application, which would lead to code duplication. In that situation the applications would roughly have the same configuration, with a few adjustments.

Best is to start of by configuring all possible dependencies in the BL bootstrapper and leave out the service registrations where the implementation differs for each application. In other words, the BL bootstrapper would result in an incomplete configuration. After that, each application can finish the configuration by registering the missing dependencies. This way you still don't need to override the existing configuration.

In certain scenarios it can be beneficial to allow an application override an existing configuration. The container can be configured to allow overriding as follows:

var container = new Container();

container.Options.AllowOverridingRegistrations = true;

// Register IUserService.
container.Register<IUserService, FakeUserService>();

// Replaces the previous registration
container.Register<IUserService, RealUserService>();

The previous example created a Container instance that allows overriding. It is also possible to enable overriding half way the registration process:

// Create a container with overriding disabled
var container = new Container();

// Pass container to the business layer.
BusinessLayer.Bootstrapper.Bootstrap(container);

// Enable overriding
container.Options.AllowOverridingRegistrations = true;

// Replaces the previous registration
container.Register<IUserService, RealUserService>();

Verify the container’s configuration

Dependency Injection promotes the concept of programming against abstractions. This makes your code much easier to test, easier to change and more maintainable. However, since the code itself isn't responsible of maintaining the dependencies between implementations, the compiler will not be able to verify whether the dependency graph is correct.

When starting to use a Dependency Injection container, many developers see their application fail when it is deployed in staging or sometimes even production, because of container misconfigurations. This makes developers often conclude that dependency injection is bad, since the dependency graph cannot be verified. This conclusion however, is incorrect. Although it is impossible for the compiler to verify the dependency graph, verifying the dependency graph is still possible and advisable.

Simple Injector contains a Verify() method, that will simply iterate over all registrations and resolve an instance for each registration. Calling this method directly after configuring the container, allows the application to fail during start-up, when the configuration is invalid.

Calling the Verify() method however, is just part of the story. It is very easy to create a configuration that passes any verification, but still fails at runtime. Here are some tips to help building a verifiable configuration:

Stay away from implicit property injection, where the container is allowed to skip injecting the property if a corresponding or correctly registered dependency can't be found. This will disallow your application to fail fast and will result in NullReferenceExceptions later on. Only use implicit property injection when the property is truly optional, omitting the dependency still keeps the configuration valid, and the application still runs correctly without that dependency. Truly optional dependencies should be very rare though, since most of the time you should prefer injecting empty implementations (a.k.a. the Null Object pattern) instead of allowing dependencies to be a null reference. Explicit property injection on the other hand is fine. With explicit property injection you force the container to inject a property and it will fail when it can't succeed. However, you should prefer constructor injection whenever possible. Note that the need for property injection is often an indication of problems in the design. If you revert to property injection because you otherwise have too many constructor arguments, you're probably violating the Single Responsibility Principle.
Register all root objects explicitly if possible. For instance, register all ASP.NET MVC Controller instances explicitly in the container (Controller instances are requested directly and are therefore called 'root objects'). This way the container can check the complete dependency graph starting from the root object when you call Verify(). Prefer registering all root objects in an automated fashion, for instance by using reflection to find all root types. The Simple Injector ASP.NET MVC Integration NuGet Package for instance, contains a RegisterMvcControllers extension method that will do this for you and the WCF Integration NuGet Package contains a RegisterWcfServices extension method for this purpose.
If registering root objects is not possible or feasible, test the creation of each root object manually during start-up. With ASP.NET Web Form Page classes for instance, you will probably call the container from within their constructor (since Page classes must unfortunately have a default constructor). The key here again is finding them all in once using reflection. By finding all Page classes using reflection and instantiating them, you'll find out (during app start-up or through automated testing) whether there is a problem with your DI configuration or not. The Web Forms Integration guide contains an example of how to verify page classes.
There are scenarios where some dependencies cannot yet be created during application start-up. To ensure that the application can be started normally and the rest of the DI configuration can still be verified, abstract those dependencies behind a proxy or abstract factory. Try to keep those unverifiable dependencies to a minimum and keep good track of them, because you will probably have to test them manually.
But even when all registrations can be resolved succesfully by the container, that still doesn't mean your configuration is correct. It is very easy to accidentally misconfigure the container in a way that only shows up late in the development process. Simple Injector contains Debugger Diagnostics to help you spot common configuration mistakes. Use these diagnostic services and use them often.

Work with dependency injection in multi-threaded applications

Note: Simple Injector is designed for use in highly-concurrent applications. Its lock-free design allows it to scale linearly with the number of threads and processors in your system.

Many applications and application frameworks are inherently multi-threaded. Working in multi-threaded applications forces developers to take special care. It is easy for a less experienced developer to introduce a race condition in the code. Even although some frameworks such as ASP.NET make it easy to write thread-safe code, introducing a simple static field could break thread-safety.

This same holds when working with DI containers in multi-threaded applications. The developer that configures the container, should be aware of the risks of shared state. Not knowing which configured services are thread-safe is a sin. Registering a service that is not thread-safe as singleton, will eventually lead to concurrency bugs, that usually only appear in production code. Those bugs are often hard to reproduce and hard to find, making them costly to fix. And even when you correctly configured a service with the correct lifestyle, when another component that depends on it accidentally as a longer lifetime, the service might be kept alive much longer and might even be accessible from other threads.

Dependency injection however, can actually help in writing multi-threaded applications. Dependency injection forces you to wire all dependencies together in a single place in the application, the Composition Root. This means that there is a single place in the application that knows about how services behave, whether they are thread-safe, and how they should be wired. Without this centralization, this knowledge would be scattered throughout the code base, making it very hard to change the behavior of a service.

Tip: Take a close look at the 'Potential Lifestyle Mismatches' warnings in the Debugger Diagnostics. Lifestyle mismatches are a source of concurrency bugs.

In a multi-threaded application, each thread should get its own object graph. This means that you should typically call container.GetInstance<T>() once at the beginning of the thread to get the root object for processing that thread (or request). The container will build an object graph with all root object's dependencies. Some of those dependencies will be singletons; shared between all threads. Other dependencies might be transient; a new instance is created per dependency. Other dependencies might be thread-specific, request-specific, or with some other lifestyle. The application code itself is unaware of the way the dependencies are registered and that's the way it is supposed to be.

For web applications, you typically call GetInstance<T>() at the beginning of the web request. In an ASP.NET MVC application for instance, one Controller instance will be requested from the container (by the Controller Factory) per web request. When using one of the integration packages, such as the Simple Injector MVC Integration Quick Start NuGet package for instance, you don't have to call GetInstance<T>() yourself, the package will ensure this is done for you. Still, GetInstance<T>() is typically called once per request.

The advice of building a new object graph (calling GetInstance<T>()) at the beginning of a thread, also holds when manually starting a new thread. Although you can pass on data to other threads, you should not pass on container controlled dependencies to other threads. On each new thread, you should ask the container again for the dependencies. When you start passing dependencies from one thread to the other, those parts of the code have to know whether it is safe to pass those dependencies on. For instance, are those dependencies thread-safe? This might be trivial to analyze in some situations, but prevents you to change those dependencies with other implementations, since now you have to remember that there is a place in your code where this is happening and you need to know which dependencies are passed on. You are decentralizing this knowledge again, making it harder to reason about the correctness of your DI configuration and making it easier to misconfigure the container in a way that causes those concurrency problems.

Running code on a new thread can be done by adding a little bit of infrastructural code. Take for instance the following example where we want to send e-mail messages asynchronously. Instead of letting the caller implement this logic, it is better to hide the logic for asynchronicity behind an abstraction; a proxy. This ensures that this logic is centralized to a single place, and by placing this proxy inside the composition root, we prevent the application code to take a dependency on the container itself (which should be prevented).

// Synchronous implementation of IMailSender
public sealed class RealMailSender : IMailSender
{
    private readonly IMailFormatter formatter;
    
    public class RealMailSender(IMailFormatter formatter)
    {
        this.formatter = formatter;
    }

    void IMailSender.SendMail(string to, string message)
    {
        // format mail
        // send mail
    }
}

// Proxy for executing IMailSender asynchronously.
sealed class AsyncMailSenderProxy : IMailSender
{
    private readonly ILogger logger;
    private readonly Func<IMailSender> mailSenderFactory;

    public AsyncMailSenderProxy(ILogger logger,
        Func<IMailSender> mailSenderFactory)
    {
        this.logger = logger;
        this.mailSenderFactory = mailSenderFactory;
    }

    void IMailSender.SendMail(string to, string message)
    {
        // Run on a new thread
        Task.Factory.StartNew(() =>
        {
            this.SendMailAsync(to, message);
        });        
    }

    private void SendMailAsync(string to, string message)
    {
        // Here we run on a different thread and the
        // services should be requested on this thread.
        var mailSender = this.mailSenderFactory();

        try
        {
            mailSender.SendMail(to, message);
        }
        catch (Exception ex)
        {
            // logging is important, since we run on a
            // different thread.
            this.logger.Log(ex);
        }
    }
}

In the Composition Root, instead of registering the MailSender, we register the AsyncMailSenderProxy as follows:

container.Register<ILogger, FileLogger>(Lifestyle.Singleton);
container.Register<IMailSender, RealMailSender>();
container.RegisterSingleDecorator(typeof(IMailSender),
    typeof(AsyncMailSenderProxy));

In this case the container will ensure that when an IMailSender is requested, a single AsyncMailSenderProxy is returned with a Func<IMailSender> delegate that will create a new RealMailSender when requested. The RegisterDecorator and RegisterSingleDecorator overloads natively understand how to handle Func<Decoratee> dependencies. The Decorators section of the Advanced-scenarios wiki page explains more about registering decorators.

Updated Wiki: Home

dot_NET_Junkie — Sun, 12 May 2013 10:53:30 GMT

Welcome to the Simple Injector project

The Simple Injector is an easy-to-use Inversion of Control library for .NET and Silverlight.

Overview

The goal of Simple Injector is to provide .NET application developers with an easy, flexible, and fast dependency injection framework, that uses best practices to steers developers towards the pit of success.

Many of the existing IoC frameworks have a big complicated legacy API or are are new, immature, and lack the features do be used in large developement projects. Simple Injector solves this problem by supplying a simple implementation with a very limited set of carefully chosen features in its core library. For example, file- and attribute-based configuration methods (that result in brittle and maintenance heavy applications) have been abandoned, favoring simple code-based configuration instead. This is enough for most applications, requiring only that configuration be performed at the start of the program. Although the API is limited, the core library does contain many features and allows almost any advanced scenario.

You will need .NET 4.0 or up to use the Simple Injector 2 library. (For .NET 3.5 projects you can use the Simple Injector v1.x releases).
Simple Injector is carefully designed to run in partial trust.
Simple Injector runs in Silverlight 4 and up (Silverlight for Windows Phone is not supported).
Simple Injector 2 runs on Mono.
It is fast; blazingly fast.

New Diagnostic Services in Simple Injector 2

Simple Injector version 2 adds the ability to warn about common misconfigurations while debugging the application. Many Simple Injector users have already used this feature to diagnose their configuration and have successfully fixed problems that would be very hard to find otherwise. Here's a quick example of how this might look in the debugger:

See the Debug Diagnostic Services page for more information.

Getting started

If you're using NuGet, there are NuGet packages available. Take a look here. Otherwise, follow the steps below, to start using the Simple Injector:

Go to the Downloads tab and download the latest runtime library;
Unpack the downloaded .zip file;
Add the SimpleInjector.dll to your start-up project by right-clicking on a project in the Visual Studio solution explorer and selecting 'Add Reference...'.
Add the using SimpleInjector; using directive on the top of the code file where you wish to configure the application.
Look at the Usage section in the documentation on how to configure and use the Simple Injector.
Look at the More information section if you want to learn more or have any questions.

A Quick Example

The general idea behind the Simple Injector (or any DI framework for that matter) is that you design your application around loosely coupled components using the dependency injection pattern. Take for instance the following UserController class in the context of an ASP.NET MVC application:

Note: Simple Injector works for many different technologies, not only for MVC. Please look at the Integration Guide for help using the Simple Injector with your technology of choice.

public class UserController : Controller {
    private readonly IUserRepository repository;
    private readonly ILogger logger;

    // Use constructor injection for the dependencies
    public UserService(IUserRepository rep, ILogger logger) {
        this.repository = rep;
        this.logger = logger;
    }

    // implement UserController methods here:
    public ActionResult Index() {
        this.logger.Log("Index called");
        return View(this.rep.GetAll());
    }	
}

The UserController class depends on the IUserRepository and ILogger interfaces. By not depending on concrete implementations, we can test UserController in isolation. Ease of testing is however, just the start of what Dependency Injection will accomplish. It allows us to design highly flexible systems that can completely be composed at a single place (often the startup path) in the application.

Using the Simple Injector, the configuration of the application using the UserController class, could look as follows:

protected void Application_Start(object sender, EventArgs e) {
    // 1. Create a new Simple Injector container
    var container = new Container();

    // 2. Configure the container (register)
    container.Register<IUserRepository, SqlUserRepository>();

    container.RegisterSingle<ILogger>(() => new CompositeLogger(
        container.GetInstance<DatabaseLogger>(),
        container.GetInstance<MailLogger>()
    ));

    // 3. Optionally verify the container's configuration.
    container.Verify();

    // 4. Register the container as MVC3 IDependencyResolver.
    DependencyResolver.SetResolver(new SimpleInjectorDependencyResolver(container));
}

Tip: If you start with a MVC application, use the NuGet Simple Injector MVC Integration Quick Start package.

The given configuration registers implementations for the IUserRepository and ILogger interfaces. The code snippet shows a few interesting things. First of all, you can map concrete instances (such as SqlUserRepository) to an interface or base type. In the given example, every time you ask the container for an IUserRepository, it will create a new SqlUserRepository on your behalf (in DI terminology: an object with a Transient lifestyle).

The registration of the ILogger is a bit more complex though. It registers a delegate that knows how to create a new ILogger implementation, in this case CompositeLogger (which is an implementation of ILogger). The delegate itself calls back into the container and this allows the container to create the concrete DatabaseLogger and MailLogger and inject them into the CompositeLogger. While the type of registration that we’ve seen with the IUserRepository is much more common, the use of delegates allows many interesting scenarios.

Note: We did not register the UserController, because the UserController is a concrete type, Simple Injector can implicitly create it (as long as its dependencies can be resolved).

This is in fact all it takes to start using the Simple Injector. Design your classes around the dependency injection principle (which is actually the hard part) and configure them in the top of your application. Some frameworks (such as ASP.NET MVC) will do the rest for you. Other frameworks (like ASP.NET Web Forms) will need a little bit more work to get this done. See the Integration Guide for examples of your framework of choice.

Please go to the Using the Simple Injector section in the documentation to see more examples.

More information

For more information about the Simple Injector please visit the following links:

Using the Simple Injector will guide you through the Simple Injector basics.
The Simple Injector and object lifetime management page explains how to configure lifestyles such as transient, singleton, and many others.
See the Reference library for the complete API documentation.
See the Integration Guide for more information about how to integrate the Simple Injector into your specific application framework.
For more information about dependency injection in general, please visit this page on Stackoverflow.
If you have any questions about how to use the Simple Injector or about dependency injection in general, the experts at Stackoverflow.com are waiting for you.
For all other Simple Injector related question and discussions, such as bug reports and feature requests, the Simple Injector discussion forum will be the place to start.

Happy injecting!

This project is supported by

Simple Injector Twitter Feed

_{Twitter / simpleinjector News Feed
simpleinjector: Hi @rossipedia. Please post a question on the http://t.co/9Q0ED2Yk discussion forum or stackoverflow http://t.co/L1eTCQoL with more info.
Monday, September 24, 2012 | From Twitter / simpleinjector
simpleinjector: RT @NuGetLatest: SimpleInjector.Integration.Wcf 1.5.0.12267 http://t.co/N4vkPAbs
Sunday, September 23, 2012 | From Twitter / simpleinjector
simpleinjector: #simpleinjector #WCF Integration Guide: http://t.co/5qSVQu1Z and #NuGet package: https://t.co/ceDMj7YI
Sunday, September 23, 2012 | From Twitter / simpleinjector
simpleinjector: #simpleinjector Integration Guide for http://t.co/s4u4dx9N Web API http://t.co/tGxmP95H
Saturday, September 22, 2012 | From Twitter / simpleinjector
simpleinjector: Just published a new patch release of #SimpleInjector Extensions to #NuGet http://t.co/VTw9P23A Fixes a few bugs with RegisterOpenGeneric
Saturday, August 25, 2012 | From Twitter / simpleinjector
Twitter / simpleinjector News Feed}

Updated Wiki: How-to

dot_NET_Junkie — Fri, 10 May 2013 16:23:27 GMT

How To...

How to Register factory delegates
How to Resolve instances by key
How to Resolve array and lists
How to Register multiple interfaces with the same implementation
How to Override existing registrations
How to Verify the container's configuration
How to Work with dependency injection in multi-threaded applications

Register factory delegates

container.Register<IMyService>(() => SomeSubSystem.CreateMyService());

// Definition
public interface IMyServiceFactory
{
    IMyService CreateNew();
}

// Implementation
sealed class ServiceFactory : IMyServiceFactory
{
    public IMyService CreateNew()
    {
        return new MyServiceImpl();
    }
}

// Registration
container.RegisterSingle<IMyServiceFactory, ServiceFactory>();

// Usage
public class MyService
{
    private readonly IMyServiceFactory factory;
    
    public MyService(IMyServiceFactory factory)
    {
        this.factory = factory;
    }
    
    public void SomeOperation()
    {
        using (var service1 = this.factory.CreateNew())
    	{
            // use service 1
        }

        using (var service2 = this.factory.CreateNew())
    	{
            // use service 2
        }
    }
}

Instead of creating specific interfaces for your factories, you can also choose to inject Func<T> delegates into your services:

// Registration
container.RegisterSingle<Func<IMyService>>(
    () => new MyServiceImpl());

// Usage
public class MyService
{
    private readonly Func<IMyService> factory;
    
    public MyService(Func<IMyService> factory)
    {
        this.factory = factory;
    }
    
    public void SomeOperation()
    {
        using (var service1 = this.factory.Invoke())
    	{
            // use service 1
        }
    }
}

This saves you from having to define a new interface and implementation per factory.

Note: On the downside however, this communicates less clearly the intend of your code and as a result might make your code harder to grasp for other developers.

When you choose Func<T> delegates over specific factory interfaces, you can define the following extension method that makes it easier to register Func<T> factories:

// Extension method
container.RegisterFuncFactory<TService, TImplementation>(
    this Container container,
    Lifestyle lifestyle = null)
    where T : class
{
    lifestyle = lifestyle ?? Lifestyle.Transient;

    // Register the type explicitly to keep the configuration
    // verifiable.
    container.Register<TService, TImplementation>(lifestyle);
	
    // Register the Func<T> that resolves that instance.
    container.RegisterSingle<Func<TService>>(
        () => container.GetInstance<TService>());
}

// Registration
container.RegisterFuncFactory<IMyService, RealService>();

The previous extension method allowed registration of a single factory, but won't be maintainable when you want all registrations to be resolvable using Func<T> delegates by default.

Note: We personally think that allowing to register Func<T> delegates by default is a design smell. The use of Func<T> delegates makes your design harder to follow and your system harder to maintain and test. If you have many constructors in your system that depend on a Func<T>, please take a good look at your dependency strategy. If in doubt, please ask us here on CodePlex or on Stackoverflow.

The following extension method allows Simple Injector to resolve all types using a Func<T> delegate by default:

public static void AllowResolvingFuncFactories(
    this ContainerOptions options)
{
    var container = options.Container;

    container.ResolveUnregisteredType += (sender, e) =>
    {
        if (e.UnregisteredServiceType.IsGenericType &&
            e.UnregisteredServiceType.GetGenericTypeDefinition() ==
                typeof(Func<>))
        {
            Type serviceType = e.UnregisteredServiceType
                .GetGenericArguments().First();

            InstanceProducer registration =
                container.GetRegistration(serviceType);

            if (registration != null)
            {
                Type funcType =
                    typeof(Func<>).MakeGenericType(serviceType);

                var factoryDelegate = 
                    Expression.Lambda(funcType,
                        registration.BuildExpression())
                    .Compile();

                e.Register(Expression.Constant(factoryDelegate));
            }
        }
    };
}

// Registration
container.Options.AllowResolvingFuncFactories();

// Extension method
container.RegisterLazy<T>(this Container container)
    where T : class
{
    Func<T> factory = () => container.GetInstance<T>();

    container.Register<Lazy<T>>(() => new Lazy<T>(factory));
}

// Registration    
container.RegisterLazy<IMyService>();

// Usage
public class MyService
{
    private readonly Lazy<IMyService> myService;
    
    public MyService(Lazy<IMyService> myService)
    {
        this.myService = myService;
    }
    
    public void SomeOperation()
    {
        if (someCondition)
        {
            this.myService.Value.Operate();
        }
    }
}

Note that instead of polluting the API of your application with Lazy<T> dependencies, it is usually cleaner to hide the Lazy<T> behind a proxy:

// Proxy definition
public class MyLazyServiceProxy : IMyService
{
    private readonly Lazy<IMyService> wrapped;
    
    public MyLazyServiceProxy(Lazy<IMyService> wrapped)
    {
        this.wrapped = wrapped;
    }
    
    public void Operate()
    {
        this.wrapped.Value.Operate();
    }
}

// Registration
container.RegisterLazy<IMyService>();
container.Register<IMyService, MyLazyServiceProxy>();

This way the application can simply depend on IMyService instead of Lazy<IMyService>.

Warning: The same warning applies to the use of Lazy<T> as it does for the use of Func<T> delegates. For more information about creating an application and container configuration that can be successfully verified, please read the How To Verify the container’s configuration.

Resolve instances by key

Note: The need for keyed registration can be an indication of ambiguity in the application design. Take a good look if each keyed registration shouldn't have its own unique interface, or perhaps each registration should implement each own version of a generic interface.

// Definition
public interface IRequestHandlerFactory
{
    IRequestHandler CreateNew(string name);
}

// Usage
var factory =
    container.GetInstance<IRequestHandlerFactory>();
var handler = factory.CreateNew("customers");
handler.Handle(requestContext);

By inheriting from the BCL’s Dictionary<TKey, TValue>, creating an IRequestHandlerFactory implementation, is almost a one-liner:

public class RequestHandlerFactory
    : Dictionary<string, Func<IRequestHandler>>,
    IRequestHandlerFactory
{
    public IRequestHandler CreateNew(string name)
    {
        return this[name]();
    }
}

With this class, we can register Func<IRequestHandler> factory methods by a key. With this in place the registration of keyed instances is a breeze:

var container = new Container();
 
container.RegisterSingle<IRequestHandlerFactory>(
    new RequestHandlerFactory
{
    { "default", () => container.GetInstance<DefaultRequestHandler>() },
    { "orders", () => container.GetInstance<OrdersRequestHandler>() },
    { "customers", () => container.GetInstance<CustomersRequestHandler>() },
});

Note: this design will work with almost all DI containers, making this not only a design that is easy to follow, but making it very easy to migrate to another DI implementation.

If you don’t like a design that uses Func<T> delegates this way, it can easily be changed to be a Dictionary<string, Type> instead. The RequestHandlerFactory can be implemented as follows:

public class RequestHandlerFactory
    : Dictionary<string, Type>, IRequestHandlerFactory
{
    private readonly Container container;
    
    public RequestHandlerFactory(Container container)
    {
        this.container = container;
    }

    public IRequestHandler CreateNew(string name)
    {
        var handler = this.container.GetInstance(this[name]);
        return (IRequestHandler)handler;
    }
}

The registration will then look as follows:

var container = new Container();

container.RegisterSingle<IRequestHandlerFactory>(
    new RequestHandlerFactory(container)
{
    { "default", typeof(DefaultRequestHandler) },
    { "orders", typeof(OrdersRequestHandler) },
    { "customers", typeof(CustomersRequestHandler) },
});

Note: Please remember the previous note about ambiguity in the application design. In the given example the design would probably be better af by using a generic IRequestHandler<TRequest> interface. This would allow the implementations to be batch registered using a single line of code, saves you from using keys, and results in a configuration the is verifiable by the container.

Resolve array and lists

public interface ILogger
{
    void Log(string message);
}

public sealed class CompositeLogger : ILogger
{
    private readonly ILogger[] loggers;

    public CompositeLogger(params ILogger[] loggers)
    {
        this.loggers = loggers ?? new ILogger[0];
    }

    public void Log(string message)
    {
        foreach (var logger in this.loggers)
        {
            logger.Log(message);
        }
    }
}

Register multiple interfaces with the same implementation

// Impl implements IInterface1, IInterface2 and IInterface3.
var registration =
    Lifestyle.Singleton.CreateRegistration<Impl, Impl>(container);

container.AddRegistration(typeof(IInterface1), registration);
container.AddRegistration(typeof(IInterface2), registration);
container.AddRegistration(typeof(IInterface3), registration);

var a = container.GetInstance<IInterface1>();
var b = container.GetInstance<IInterface2>();

// Since Impl is a singleton, both requests return the same instance.
Assert.AreEqual(a, b);

Override existing registrations

var container = new Container();

container.Options.AllowOverridingRegistrations = true;

// Register IUserService.
container.Register<IUserService, FakeUserService>();

// Replaces the previous registration
container.Register<IUserService, RealUserService>();

The previous example created a Container instance that allows overriding. It is also possible to enable overriding half way the registration process:

// Create a container with overriding disabled
var container = new Container();

// Pass container to the business layer.
BusinessLayer.Bootstrapper.Bootstrap(container);

// Enable overriding
container.Options.AllowOverridingRegistrations = true;

// Replaces the previous registration
container.Register<IUserService, RealUserService>();

Verify the container’s configuration

Stay away from implicit property injection, where the container is allowed to skip injecting the property if a corresponding or correctly registered dependency can't be found. This will disallow your application to fail fast and will result in NullReferenceExceptions later on. Only use implicit property injection when the property is truly optional, omitting the dependency still keeps the configuration valid, and the application still runs correctly without that dependency. Truly optional dependencies should be very rare though, since most of the time you should prefer injecting empty implementations (a.k.a. the Null Object pattern) instead of allowing dependencies to be a null reference. Explicit property injection on the other hand is fine. With explicit property injection you force the container to inject a property and it will fail when it can't succeed. However, you should prefer constructor injection whenever possible. Note that the need for property injection is often an indication of problems in the design. If you revert to property injection because you otherwise have too many constructor arguments, you're probably violating the Single Responsibility Principle.
Register all root objects explicitly if possible. For instance, register all ASP.NET MVC Controller instances explicitly in the container (Controller instances are requested directly and are therefore called 'root objects'). This way the container can check the complete dependency graph starting from the root object when you call Verify(). Prefer registering all root objects in an automated fashion, for instance by using reflection to find all root types. The Simple Injector ASP.NET MVC Integration NuGet Package for instance, contains a RegisterMvcControllers extension method that will do this for you and the WCF Integration NuGet Package contains a RegisterWcfServices extension method for this purpose.
If registering root objects is not possible or feasible, test the creation of each root object manually during start-up. With ASP.NET Web Form Page classes for instance, you will probably call the container from within their constructor (since Page classes must unfortunately have a default constructor). The key here again is finding them all in once using reflection. By finding all Page classes using reflection and instantiating them, you'll find out (during app start-up or through automated testing) whether there is a problem with your DI configuration or not. The Web Forms Integration guide contains an example of how to verify page classes.
There are scenarios where some dependencies cannot yet be created during application start-up. To ensure that the application can be started normally and the rest of the DI configuration can still be verified, abstract those dependencies behind a proxy or abstract factory. Try to keep those unverifiable dependencies to a minimum and keep good track of them, because you will probably have to test them manually.
But even when all registrations can be resolved succesfully by the container, that still doesn't mean your configuration is correct. It is very easy to accidentally misconfigure the container in a way that only shows up late in the development process. Simple Injector contains Debugger Diagnostics to help you spot common configuration mistakes. Use these diagnostic services and use them often.

Work with dependency injection in multi-threaded applications

Note: Simple Injector is designed for use in highly-concurrent applications. Its lock-free design allows it to scale linearly with the number of threads and processors in your system.

Tip: Take a close look at the 'Potential Lifestyle Mismatches' warnings in the Debugger Diagnostics. Lifestyle mismatches are a source of concurrency bugs.

// Synchronous implementation of IMailSender
public sealed class RealMailSender : IMailSender
{
    private readonly IMailFormatter formatter;
    
    public class RealMailSender(IMailFormatter formatter)
    {
        this.formatter = formatter;
    }

    void IMailSender.SendMail(string to, string message)
    {
        // format mail
        // send mail
    }
}

// Proxy for executing IMailSender asynchronously.
sealed class AsyncMailSenderProxy : IMailSender
{
    private readonly ILogger logger;
    private readonly Func<IMailSender> mailSenderFactory;

    public AsyncMailSenderProxy(ILogger logger,
        Func<IMailSender> mailSenderFactory)
    {
        this.logger = logger;
        this.mailSenderFactory = mailSenderFactory;
    }

    void IMailSender.SendMail(string to, string message)
    {
        // Run on a new thread
        Task.Factory.StartNew(() =>
        {
            this.SendMailAsync(to, message);
        });        
    }

    private void SendMailAsync(string to, string message)
    {
        // Here we run on a different thread and the
        // services should be requested on this thread.
        var mailSender = this.mailSenderFactory();

        try
        {
            mailSender.SendMail(to, message);
        }
        catch (Exception ex)
        {
            // logging is important, since we run on a
            // different thread.
            this.logger.Log(ex);
        }
    }
}

In the Composition Root, instead of registering the MailSender, we register the AsyncMailSenderProxy as follows:

container.Register<ILogger, FileLogger>(Lifestyle.Singleton);
container.Register<IMailSender, RealMailSender>();
container.RegisterSingleDecorator(typeof(IMailSender),
    typeof(AsyncMailSenderProxy));

Updated Wiki: PotentialLifestyleMismatches

dot_NET_Junkie — Thu, 02 May 2013 21:34:03 GMT

Diagnostic Warning - Potential Lifestyle Mismatches

Cause

The component depends on a service with a lifestyle that is shorter than that of the component.

Warning Description

In general, components should only depend on other components that are configured to live at least as long. In other words, it is safe for a transient component to depend on a singleton, but not the other way around. Since components store a reference to their dependencies in (private) instance fields, those dependencies are kept alive for the lifetime of that component. This means that dependencies that are configured with a shorter lifetime than their consumer, accidentally live longer than intended. This can lead to all sorts of bugs, such as hard to debug multi-threading issues.

The Diagnostic Services detect this kind of misconfiguration and report it. The container will be able to compare all built-in lifestyles (and sometimes even custom lifestyles). Here is an overview of the built-in lifestyles ordered by their length:

How to Fix Violations

There are multiple ways to fix this violation:

Change the lifestyle of the component to a lifestyle that is as short or shorter than that of the dependency.
Change the lifestyle of the dependency to a lifestyle as long or longer than that of the component.
Instead of injecting the dependency, inject a factory for the creation of that dependency and call that factory every time an instance is required.

When to Ignore Warnings

Do not ignore these warnings. False positives for this warning are rare and even when they occur, the registration or the application design can always be changed in a way that the warning disappears.

Example

The following example shows a configuration that will trigger the warning:

var container = new Container();

container.Register<IUserRepository, InMemoryUserRepository>(Lifestyle.Transient);

// RealUserService depends on IUserRepository
container.RegisterSingle<RealUserService>();

// FakeUserService depends on IUserRepository
container.RegisterSingle<FakeUserService>();

container.Verify();

The RealUserService component is registered as Singleton but it depends on IUserRepository which is configured with the shorter Transient lifestyle. Below is an image that shows the output for this configuration in a watch window. The watch window shows two mismatches and one of the warnings is unfolded.

What about Hybrid lifestyles?

A Hybrid lifestyle is a mix between two or more other lifestyles. Here is an example of a custom lifestyle that mixes the Transient and Singleton lifestyles together:

var hybrid = Lifestyle.CreateHybrid(
    lifestyleSelector: () => someCondition,
    trueLifestyle: Lifestyle.Transient,
    falseLifestyle: Lifestyle.Singleton);

Note that this example is quite bizarre, since it is a very unlikely combination of lifestyles to mix together, but it serves us well for the purpose of this explanation.

As explained, components should only depend on longer lived components. But how long does a component with this hybrid lifestyle live? For components that are configured with the lifestyle defined above, it depends on the implementation of `someCondition`. But without taking this condition into consideration, we can say that it will at most live as long as the longest wrapped lifestyle (Singleton in this case) and at least live as long as shortest wrapped lifestyle (in this case Transient).

From the Diagnostic Services' perspective, a component can only safely depend on a hybrid lifestyled service if the consuming component's lifestyle is shorter than or equal the shortest lifestyle the hybrid is composed of. On the other hand, a hybrid lifestyled component can only safely depend on another service when the longest lifestyle of the hybrid is shorter than or equal to the lifestyle of the dependency. Thus, when a relationship between a component and its dependency is evaluated by the Diagnostic Services, the longest lifestyle is used in the comparison when the hybrid is part of the consuming component, and the shortest lifestyle is used when the hybrid is part of the dependency.

This does imply that two components with the same hybrid lifestyle can't safely depend on each other. This is true since in theory the supplied predicate could change results in each call. In practice however, those components would usually be able safely relate, since it is normally unlikely that the predicate changes lifestyles within a single object graph. This is an exception the Diagnostic Services can make pretty safely. From the Diagnostic Services' perspective, components can safely be related when both share the exact same lifestyle instance and no warning will be displayed in this case. This does mean however, that you should be very careful using predicates that change the lifestyle during the object graph.

Updated Wiki: How-to

dot_NET_Junkie — Thu, 02 May 2013 20:58:13 GMT

How To...

How to Register factory delegates
How to Resolve instances by key
How to Resolve array and lists
How to Register multiple interfaces with the same implementation
How to Override existing registrations
How to Verify the container's configuration
How to Work with dependency injection in multi-threaded applications

Register factory delegates

container.Register<IMyService>(() => SomeSubSystem.CreateMyService());

// Definition
public interface IMyServiceFactory
{
    IMyService CreateNew();
}

// Implementation
sealed class ServiceFactory : IMyServiceFactory
{
    public IMyService CreateNew()
    {
        return new MyServiceImpl();
    }
}

// Registration
container.RegisterSingle<IMyServiceFactory, ServiceFactory>();

// Usage
public class MyService
{
    private readonly IMyServiceFactory factory;
    
    public MyService(IMyServiceFactory factory)
    {
        this.factory = factory;
    }
    
    public void SomeOperation()
    {
        using (var service1 = this.factory.CreateNew())
    	{
            // use service 1
        }

        using (var service2 = this.factory.CreateNew())
    	{
            // use service 2
        }
    }
}

Instead of creating specific interfaces for your factories, you can also choose to inject Func<T> delegates into your services:

// Registration
container.RegisterSingle<Func<IMyService>>(
    () => new MyServiceImpl());

// Usage
public class MyService
{
    private readonly Func<IMyService> factory;
    
    public MyService(Func<IMyService> factory)
    {
        this.factory = factory;
    }
    
    public void SomeOperation()
    {
        using (var service1 = this.factory.Invoke())
    	{
            // use service 1
        }
    }
}

This saves you from having to define a new interface and implementation per factory.

Note: On the downside however, this communicates less clearly the intend of your code and as a result might make your code harder to grasp for other developers.

When you choose Func<T> delegates over specific factory interfaces, you can define the following extension method that makes it easier to register Func<T> factories:

// Extension method
container.RegisterFuncFactory<T>(this Container container)
    where T : class
{
    container.RegisterSingle<Func<T>>(
        () => container.GetInstance<T>());
}

// Registration
container.RegisterFuncFactory<IMyService>();

Warning: Although the use of factories can be useful, they do pose a thread in the maintainability of your application. Because the creation of instances is postponed to a later moment in time, their creation is not tested by the container when calling Verify or when requesting an object that depends on the Func<T>. When there is a misconfiguration, your application could break much later in time, instead of when starting (or unit testing) your application. For more information about creating an application and container configuration that can be successfully verified, please read the How To Verify the container’s configuration.

Just like Func<T> delegates can be injected, Lazy<T> instances can be injected into services. Lazy<T> is useful in situations where the creation of a service is time consuming, but is not always used. Thus Lazy<T> allows you to postpone the creation of that service until the moment that it is really needed:

// Extension method
container.RegisterLazy<T>(this Container container)
    where T : class
{
    Func<T> factory = () => container.GetInstance<T>();

    container.Register<Lazy<T>>(() => new Lazy<T>(factory));
}

// Registration	
container.RegisterLazy<IMyService>();

// Usage
public class MyService
{
    private readonly Lazy<IMyService> myService;
    
    public MyService(Lazy<IMyService> myService)
    {
        this.myService = myService;
    }
    
    public void SomeOperation()
    {
        if (someCondition)
        {
            this.myService.Value.Operate();
        }
    }
}

Note that instead of polluting the API of your application with Lazy<T> dependencies, it is usually cleaner to hide the Lazy<T> behind a proxy:

// Proxy definition
public class MyLazyServiceProxy : IMyService
{
    private readonly Lazy<IMyService> wrapped;
    
    public MyLazyServiceProxy(Lazy<IMyService> wrapped)
    {
        this.wrapped = wrapped;
    }
    
    public void Operate()
    {
        this.wrapped.Value.Operate();
    }
}

// Registration
container.RegisterLazy<IMyService>();
container.Register<IMyService, MyLazyServiceProxy>();

This way the application can simply depend on IMyService instead of Lazy<IMyService>.

Warning: The same warning applies to the use of Lazy<T> as it does for the use of Func<T> delegates. For more information about creating an application and container configuration that can be successfully verified, please read the How To Verify the container’s configuration.

Resolve instances by key

Note: The need for keyed registration can be an indication of ambiguity in the application design. Take a good look if each keyed registration shouldn't have its own unique interface, or perhaps each registration should implement each own version of a generic interface.

// Definition
public interface IRequestHandlerFactory
{
    IRequestHandler CreateNew(string name);
}

// Usage
var factory =
    container.GetInstance<IRequestHandlerFactory>();
var handler = factory.CreateNew("customers");
handler.Handle(requestContext);

By inheriting from the BCL’s Dictionary<TKey, TValue>, creating an IRequestHandlerFactory implementation, is almost a one-liner:

public class RequestHandlerFactory
    : Dictionary<string, Func<IRequestHandler>>,
    IRequestHandlerFactory
{
    public IRequestHandler CreateNew(string name)
    {
        return this[name]();
    }
}

With this class, we can register Func<IRequestHandler> factory methods by a key. With this in place the registration of keyed instances is a breeze:

var container = new Container();
 
container.RegisterSingle<IRequestHandlerFactory>(
    new RequestHandlerFactory
{
    { "default", () => container.GetInstance<DefaultRequestHandler>() },
    { "orders", () => container.GetInstance<OrdersRequestHandler>() },
    { "customers", () => container.GetInstance<CustomersRequestHandler>() },
});

Note: this design will work with almost all DI containers, making this not only a design that is easy to follow, but making it very easy to migrate to another DI implementation.

If you don’t like a design that uses Func<T> delegates this way, it can easily be changed to be a Dictionary<string, Type> instead. The RequestHandlerFactory can be implemented as follows:

public class RequestHandlerFactory
    : Dictionary<string, Type>, IRequestHandlerFactory
{
    private readonly Container container;
    
    public RequestHandlerFactory(Container container)
    {
        this.container = container;
    }

    public IRequestHandler CreateNew(string name)
    {
        var handler = this.container.GetInstance(this[name]);
        return (IRequestHandler)handler;
    }
}

The registration will then look as follows:

var container = new Container();

container.RegisterSingle<IRequestHandlerFactory>(
    new RequestHandlerFactory(container)
{
    { "default", typeof(DefaultRequestHandler) },
    { "orders", typeof(OrdersRequestHandler) },
    { "customers", typeof(CustomersRequestHandler) },
});

Note: Please remember the previous note about ambiguity in the application design. In the given example the design would probably be better af by using a generic IRequestHandler<TRequest> interface. This would allow the implementations to be batch registered using a single line of code, saves you from using keys, and results in a configuration the is verifiable by the container.

Resolve array and lists

public interface ILogger
{
    void Log(string message);
}

public sealed class CompositeLogger : ILogger
{
    private readonly ILogger[] loggers;

    public CompositeLogger(params ILogger[] loggers)
    {
        this.loggers = loggers ?? new ILogger[0];
    }

    public void Log(string message)
    {
        foreach (var logger in this.loggers)
        {
            logger.Log(message);
        }
    }
}

Register multiple interfaces with the same implementation

// Impl implements IInterface1, IInterface2 and IInterface3.
var registration =
    Lifestyle.Singleton.CreateRegistration<Impl, Impl>(container);

container.AddRegistration(typeof(IInterface1), registration);
container.AddRegistration(typeof(IInterface2), registration);
container.AddRegistration(typeof(IInterface3), registration);

var a = container.GetInstance<IInterface1>();
var b = container.GetInstance<IInterface2>();

// Since Impl is a singleton, both requests return the same instance.
Assert.AreEqual(a, b);

Override existing registrations

var container = new Container();

container.Options.AllowOverridingRegistrations = true;

// Register IUserService.
container.Register<IUserService, FakeUserService>();

// Replaces the previous registration
container.Register<IUserService, RealUserService>();

The previous example created a Container instance that allows overriding. It is also possible to enable overriding half way the registration process:

// Create a container with overriding disabled
var container = new Container();

// Pass container to the business layer.
BusinessLayer.Bootstrapper.Bootstrap(container);

// Enable overriding
container.Options.AllowOverridingRegistrations = true;

// Replaces the previous registration
container.Register<IUserService, RealUserService>();

Verify the container’s configuration

Stay away from implicit property injection, where the container is allowed to skip injecting the property if a corresponding or correctly registered dependency can't be found. This will disallow your application to fail fast and will result in NullReferenceExceptions later on. Only use implicit property injection when the property is truly optional, omitting the dependency still keeps the configuration valid, and the application still runs correctly without that dependency. Truly optional dependencies should be very rare though, since most of the time you should prefer injecting empty implementations (a.k.a. the Null Object pattern) instead of allowing dependencies to be a null reference. Explicit property injection on the other hand is fine. With explicit property injection you force the container to inject a property and it will fail when it can't succeed. However, you should prefer constructor injection whenever possible. Note that the need for property injection is often an indication of problems in the design. If you revert to property injection because you otherwise have too many constructor arguments, you're probably violating the Single Responsibility Principle.
Register all root objects explicitly if possible. For instance, register all ASP.NET MVC Controller instances explicitly in the container (Controller instances are requested directly and are therefore called 'root objects'). This way the container can check the complete dependency graph starting from the root object when you call Verify(). Prefer registering all root objects in an automated fashion, for instance by using reflection to find all root types. The Simple Injector ASP.NET MVC Integration NuGet Package for instance, contains a RegisterMvcControllers extension method that will do this for you and the WCF Integration NuGet Package contains a RegisterWcfServices extension method for this purpose.
If registering root objects is not possible or feasible, test the creation of each root object manually during start-up. With ASP.NET Web Form Page classes for instance, you will probably call the container from within their constructor (since Page classes must unfortunately have a default constructor). The key here again is finding them all in once using reflection. By finding all Page classes using reflection and instantiating them, you'll find out (during app start-up or through automated testing) whether there is a problem with your DI configuration or not. The Web Forms Integration guide contains an example of how to verify page classes.
There are scenarios where some dependencies cannot yet be created during application start-up. To ensure that the application can be started normally and the rest of the DI configuration can still be verified, abstract those dependencies behind a proxy or abstract factory. Try to keep those unverifiable dependencies to a minimum and keep good track of them, because you will probably have to test them manually.
But even when all registrations can be resolved succesfully by the container, that still doesn't mean your configuration is correct. It is very easy to accidentally misconfigure the container in a way that only shows up late in the development process. Simple Injector contains Debugger Diagnostics to help you spot common configuration mistakes. Use these diagnostic services and use them often.

Work with dependency injection in multi-threaded applications

Note: Simple Injector is designed for use in highly-concurrent applications. Its lock-free design allows it to scale linearly with the number of threads and processors in your system.

Tip: Take a close look at the 'Potential Lifestyle Mismatches' warnings in the Debugger Diagnostics. Lifestyle mismatches are a source of concurrency bugs.

// Synchronous implementation of IMailSender
public sealed class RealMailSender : IMailSender
{
    private readonly IMailFormatter formatter;
    
    public class RealMailSender(IMailFormatter formatter)
    {
        this.formatter = formatter;
    }

    void IMailSender.SendMail(string to, string message)
    {
        // format mail
        // send mail
    }
}

// Proxy for executing IMailSender asynchronously.
sealed class AsyncMailSenderProxy : IMailSender
{
    private readonly ILogger logger;
    private readonly Func<IMailSender> mailSenderFactory;

    public AsyncMailSenderProxy(ILogger logger,
        Func<IMailSender> mailSenderFactory)
    {
        this.logger = logger;
        this.mailSenderFactory = mailSenderFactory;
    }

    void IMailSender.SendMail(string to, string message)
    {
        // Run on a new thread
        Task.Factory.StartNew(() =>
        {
            this.SendMailAsync(to, message);
        });        
    }

    private void SendMailAsync(string to, string message)
    {
        // Here we run on a different thread and the
        // services should be requested on this thread.
        var mailSender = this.mailSenderFactory();

        try
        {
            mailSender.SendMail(to, message);
        }
        catch (Exception ex)
        {
            // logging is important, since we run on a
            // different thread.
            this.logger.Log(ex);
        }
    }
}

In the Composition Root, instead of registering the MailSender, we register the AsyncMailSenderProxy as follows:

container.Register<ILogger, FileLogger>(Lifestyle.Singleton);
container.Register<IMailSender, RealMailSender>();
container.RegisterSingleDecorator(typeof(IMailSender),
    typeof(AsyncMailSenderProxy));

Updated Wiki: Using the Simple Injector

dot_NET_Junkie — Thu, 02 May 2013 20:56:23 GMT

Note: this documentation is specific for Simple Injector version 2.0 and up. Look here for 1.x specific documentation.

Using the Simple Injector

This section will walk you through the basics of the Simple Injector. After reading this section, you will have a good idea how to use the Simple Injector.

Using the Simple Injector

A good practice is to minimize the dependency between your application and the IoC framework. This increases the testability and the flexibility of your application, results in cleaner code, and makes it easier to migrate to another IoC framework if ever required. Minimizing can be achieved by designing the types in your application around the constructor injection pattern. Define all dependencies of a class in the single public constructor of that type. Do this for all service types that need to be resolved and resolve only the top most types in the application directly (let the container build up the complete graph of dependent objects for you).

The Simple Injector's main type is the Container class. An instance of Container is used to register mappings between an abstraction (service) and implementation (component). Your application code should depend on abstractions, and it is the role of the Container to supply the application with the right implementation. The easiest way to look at a Container is as a big dictionary where the type of the abstraction is used as key, and its value is the definition of how to create the implementation. When the application requests for a service, it is looked up in the dictionary, and the correct implementation is returned.

Tip: You should typically create a single Container instance for the whole application (one instance per app domain); Container instances are thread-safe.

Warning: Do not create an infinite number of Container instances (such as one instance per request). This could drain the performance of your application. The container is optimized for using a limited number of Container instances. Creating and initializing a container instance has a lot of overhead, but is extremely fast once initialized.

Creating a new container is done by newing up a new instance and start calling the RegisterXXX overloads to register new services:

Container container = new SimpleInjector.Container();

// Registrations here
container.Register<ILogger, FileLogger>();

Ideally, the only place in an application that should directly reference and use the Simple Injector is the startup path. For an ASP.NET Web Forms or MVC application this will usually be the Application_OnStart event in the Global.asax page of the web application project. For a Windows Forms or console application this will be the Main method in the application assembly.

For more information about usage of the Simple Injector for a specific technology, please see the Integration Guide.

The usage of the Simple Injector consists of four or five simple steps:

Create a new container
Configure the container (register)
Optionally verify the container
Store the container for use by the application
Retrieve instances from the container (resolve)

While the first three steps are platform agnostic, performing the last two steps depends on your own taste and which presentation framework you use, but below is an example for an ASP.NET Web Forms application:

using SimpleInjector;

public class Global : System.Web.HttpApplication 
{
    public static Container Container { get; private set; }

    protected void Application_Start(object sender, EventArgs e) 
    {
        // 1. Create a new Simple Injector container
        var container = new Container();

        // 2. Configure the container (register)
        container.Register<IUserService, UserService>(Lifestyle.Transient);
        container.Register<IUserRepository, SqlUserRepository>(Lifestyle.Singleton);

        // See below for more configuration examples

        // 3. Optionally verify the container's configuration.
        container.Verify();

        // 4. Store the container for use by Page classes.
        Global.Container = container;
    }
}

The example below shows the fifth step inside a ASP.NET Web Page:

using System;

public partial class User : BasePage
{
    private readonly IUserRepository repository;
    private readonly ILogger logger;

    public User()
    {
        // 5. Retrieve instances from the container (resolve)
        this.repository = Global.Container.GetInstance<IUserRepository>();
        this.logger = Global.Container.GetInstance<ILogger>();
    }

    protected void Page_Load(object sender, EventArgs e)
    {
        // Use repository and logger here.
    }
}

Note: Calling the GetInstance method in the constructor is suboptimal and should be avoided whenever possible. With ASP.NET Web Forms however, it is hard to completely avoid this. Please see the Integration Guide for alternatives.

Resolving instances

The Simple Injector allows two scenarios by which you can retrieve instances:

1. Getting an object by a specified type

var repository = container.GetInstance<IUserRepository>();

// Alternatively, you can use the weakly typed version
var repository = (IUserRepository)container.GetInstance(typeof(IUserRepository));

2. Getting a collection of objects by their type

IEnumerable<ICommand> commands = container.GetAllInstances<ICommand>();

// Alternatively, you can use the weakly typed version
IEnumerable<object> commands = container.GetAllInstances(typeof(ICommand));

Configuring the Simple Injector

The Container class consists of several methods that enable registering instances to be retrieved when requested from the application. These methods enable most common scenarios. Here are the most common scenarios with a code example per scenario:

Configuring an automatically constructed single instance to be always returned:
The following example configures that a single instance of type RealUserService will always be returned when an instance of IUserService is requested. The RealUserService will be constructed using automatic constructor injection.

// Configuration
container.RegisterSingle<IUserService, RealUserService>();

// Alternatively you can supply a Lifestyle with the same effect.
container.Register<IUserService, RealUserService>(Lifestyle.Singleton);

// Usage
IUserService service = container.GetInstance<IUserService>();

Note: instances that are declared as Single should be thread-safe in a multi-threaded environment.

Configuring a single -manually created- instance to be always returned:
The following example configures a single instance that will always be returned when an instance of that type will be requested.

// Configuration
container.RegisterSingle<IUserRepository>(new SqlUserRepository());

// Usage
IUserRepository repository = container.GetInstance<IUserRepository>();

Note: Registering types using automatic constructor injection (auto-wiring) is the preferred way of registering types. Only new up instances manually when automatic constructor injection is not possible.

Configuring a single instance using a delegate:
The following example configures a single instance using a delegate. The container will ensure that the delegate is not called more than once.

// Configuration
container.RegisterSingle<IUserRepository>(() => UserRepFactory.Create("some constr"));

// Alternatively you can supply the singleton Lifestyle with the same effect.
container.Register<IUserRepository>(() => UserRepFactory.Create("some constr"), Lifestyle.Singleton);

// Usage
IUserRepository repository = container.GetInstance<IUserRepository>();

Note: Registering types using automatic constructor injection (auto-wiring) is the preferred way of registering types. Only new up instances manually when automatic constructor injection is not possible.

Configuring an automatically constructed new instance to be returned:
By supplying the service type and the created implementation as generic types, the container can create new instances of the implementation (MoveCustomerHandler in this case) by using automatic constructor injection.

// Configuration
container.Register<IHandler<MoveCustomerCommand>, MoveCustomerHandler>();

// Alternatively you can supply the transient Lifestyle with the same effect.
container.Register<IHandler<MoveCustomerCommand>, MoveCustomerHandler>(Lifestyle.Transient);

// Usage
var handler = container.GetInstance<IHandler<MoveCustomerCommand>>();

Configuring a new instance to be returned on each call using a delegate:
By supplying a delegate, types can be registered that can not be created by using automatic constructor injection. By calling the container inside the delegate, you can let the container do as much as work for you as possible:

// Configuration
container.Register<IHandler<MoveCustomerCommand>>(() =>
{
    // Get a new instance of the concrete MoveCustomerHandler class:
    var handler = container.GetInstance<MoveCustomerHandler>();

    // Configure the handler:
    handler.ExecuteAsynchronously = true;

    return handler;
});

container.Register<IHandler<MoveCustomerCommand>>(() => { ... }, Lifestyle.Transient);
// Alternatively you can supply the transient Lifestyle with the same effect.
// Usage
var handler = container.GetInstance<IHandler<MoveCustomerCommand>>();

Configuring property injection on an instance:
For types that need to be injected, define a single public constructor that holds all dependencies whenever possible. In scenarios where constructor injection is not possible, property injection is your second best pick. The previous example already showed an example of this. The preferred way of doing this however, is by using the RegisterInitializer method:

// Configuration
container.Register<IHandler<MoveCustomerCommand>>, MoveCustomerHandler>();
container.Register<IHandler<ShipOrderCommand>>, ShipOrderHandler>();

// MoveCustomerCommand and ShipOrderCommand both inherit from HandlerBase
container.RegisterInitializer<HandlerBase>(handlerToInitialize =>
{
    handlerToInitialize.ExecuteAsynchronously = true;
});

// Usage
var handler1 = container.GetInstance<IHandler<MoveCustomerCommand>>();
Assert.IsTrue(handler1.ExecuteAsynchronously);

var handler2 = container.GetInstance<IHandler<ShipOrderCommand>>();
Assert.IsTrue(handler2.ExecuteAsynchronously);

The Action<T> delegate that is registered using the RegisterInitializer method will be called after the container created a new instance that inherits from or implements the given T (or inherits from or implements the given T). In the case of the given example, the MoveCustomerHandler inherits from HandlerBase and because of this, Action<HandlerBase> delegate will get called with the reference to the created instance.

Note: The container will not be able to call an initializer delegate on a type that is manually constructed using the new operator. Use automatic constructor injection whenever possible.

Tip: Multiple initializers can apply to a concrete type and the container will call all initializers that apply to that type. They are guaranteed to run in the same order as they are registered.

Configuring a collection of instances to be returned:
The Simple Injector contains several methods for registration and resolving collections of types. Here are some examples:

// Configuration
// Registering a list of instances that will be created by the container.
// Supplying a collection of types is the preferred way of registering collections.
container.RegisterAll<ILogger>(typeof(IMailLogger), typeof(SqlLogger));

// Register a fixed list (these instances should be thread-safe).
container.RegisterAll<ILogger>(new MailLogger(), new SqlLogger());

// Using a collection from another subsystem
container.RegisterAll<ILogger>(Logger.Providers);

// Usage
var loggers = container.GetAllInstances<ILogger>();

Note: When no instances are registered using RegisterAll, Container.GetAllInstances will always return an empty list.

Just as with normal types, the Simple Injector can inject collections of instances into constructors:

// Definition
public class Service : IService
{
    private readonly IEnumerable<ILogger> loggers;

    public Service(IEnumerable<ILogger> loggers)
    {
        this.loggers = loggers;
    }

    void IService.DoStuff()
    {
        // Log to all loggers
        foreach (var logger in this.loggers)
        {
            logger.Log("Some message");
        }
    }
}

// Configuration
container.RegisterAll<ILogger>(typeof(MailLogger)), typeof(SqlLogger));
container.RegisterSingle<IService, Service>();

// Usage
var service = container.GetInstance<IService>();
service.DoStuff();

The RegisterAll overloads that take a collection of Type instances, forward the creation of those types to the container, which means that the same rules apply to them. Take a look at the following configuration:

// Configuration
container.Register<MailLogger>(Lifestyle.Singleton);
container.Register<ILogger, FileLogger>();

container.RegisterAll<ILogger>(typeof(MailLogger)), typeof(SqlLogger), typeof(ILogger));

When the registered collection of ILogger instance is resolved, the container will resolve each and every one of them using their configuration. When no such registration exists, the type is created with the Transient lifestyle (which means, that a new instance is created every time the returned collection is iterated). The MailLogger type however, has an explicit registration and since it is registered as Singleton, the resolved ILogger collections will always have the same instance.

Since the creation is forwarded, also abstract types can be registered using RegisterAll. In this case the ILogger type itself is registered using RegisterAll. This seems like a recursive definition, but it will work nonetheless. In this particular case you could imagine this to be a registration with a default ILogger registration, that is included in the collection of ILogger instances as well.

While resolving collections is useful and also works with automatic constructor injection, the registration of composites is preferred over the use of collections as constructor arguments in application code. Register a composite whenever possible, as shown in the example below:

// Definition
public class CompositeLogger : ILogger
{
    private readonly ILogger[] loggers;

    public CompositeLogger(params ILogger[] loggers)
    {
        this.loggers = loggers;
    }

    public void Log(string message)
    {
        foreach (var logger in this.loggers)
            logger.Log(message);
    }
}

// Configuration
container.RegisterSingle<IService, Service>();
container.RegisterSingle<ILogger>(() => 
    new CompositeLogger(
        container.GetInstance<MailLogger>(),
        container.GetInstance<SqlLogger>()
    )
);

// Usage
var service = container.GetInstance<IService>();
service.DoStuff();

When using the approach given above, your services don’t need a dependency on IEnumerable<ILogger>, but can simply have a dependency on the ILogger interface itself.

Verifying the container's configuration

Optionally, you can call the Verify method of the Container. This method allows a fail-fast mechanism to prevent the application to start when the container is misconfigured. The Verify method checks the container's configuration by creating an instance of all registered types.

For more information about creating an application and container configuration that can be succesfully verified, please read the How To Verify the container’s configuration.

Automatic constructor injection / auto-wiring.

The Simple Injector uses the public constructor of a registered type and looks at the arguments of that constructor. The container will resolve instances for the argument types and invokes the constructor using those instances. This mechanism is called automatic constructor injection or auto-wiring and this is one of the core differences that separates DI containers from doing injection manually. For the Simple Injector to be able to use auto-wiring, the following requirements must be met:

The type is concrete (not abstract, no interface, no generic type definition).
The type has exactly one public constructor (this may be a default constructor).
All types of the arguments on that constructor can be resolved by the container.

The Simple Injector can create a type even if it hasn’t registered in the container by using constructor injection.

The following code shows an example of the use of automatic constructor injection. The example shows an IUserRepository interface with a concrete SqlUserRepository implementation and a concrete UserService class. The UserService class has one public constructor with an IUserRepository argument. Because the dependencies of the UserService are registered, the Simple Injector is able to create a new UserService instance.

// Definitions
public interface IUserRepository { }
public class SqlUserRepository : IUserRepository { }
public class UserService : IUserService
{
    public UserService(IUserRepository repository) { }
}

// Configuration
var container = new Container();

container.RegisterSingle<IUserRepository, SqlUserRepository>();
container.RegisterSingle<IUserService, UserService>();

// Usage
var service = container.GetInstance<IUserService>();

Note: Because UserService is a concrete type, calling container.GetInstance<UserService>() without registering it explicitly will work as well. This can simplify the container’s configuration significantly for more complex scenarios. However, keep in mind that the best practice is to program to an interface, not a concrete type. Prevent using and depending on concrete types whenever possible.

More information

For more information about the Simple Injector please visit the following links:

The Simple Injector and object lifetime management page explains how to configure lifestyles such as transient, singleton, and many others.
See the Integration Guide for more information about how to integrate the Simple Injector into your specific application framework.
For more information about dependency injection in general, please visit this page on Stackoverflow.
If you have any questions about how to use the Simple Injector or about dependency injection in general, the experts at Stackoverflow.com are waiting for you.
For all other Simple Injector related question and discussions, such as bug reports and feature requests, the Simple Injector discussion forum will be the place to start.

New Comment on "Unity"

dot_NET_Junkie — Thu, 25 Apr 2013 23:16:22 GMT

See: http://stackoverflow.com/questions/16225737

New Comment on "Unity"

Vaccano — Thu, 25 Apr 2013 21:43:27 GMT

Does it have an IContainer interface like unity has? I can't seem to find it.

Updated Wiki: Integration Guide

dot_NET_Junkie — Sun, 21 Apr 2013 20:34:59 GMT

Integration Guide

The Simple Injector library can be used in a wide range of .NET technologies, both server side as client side. Jump directly to to the integration page for the application framework of your choice. When the framework of your choice is not listed, doesn't mean it isn't supported, but just that we didn't have the time write it :-)

Besides integration with standard .NET technologies, Simple Injector can be integrated with a wide range of other technologies. Here are a few to help you get started quickly:

Here is guidance about some general patterns:

Working with the Unit of Work pattern such as Entity Framework's ObjectContext, LINQ to SQL's DataContext, and NHibernate's ISession.
Working with multi-tenant applications

Updated Wiki: Web API Integration

dot_NET_Junkie — Wed, 10 Apr 2013 11:41:01 GMT

ASP.NET Web API Integration Guide

The following code snippet defines a SimpleInjectorWebApiDependencyResolver class for an IIS hosted ASP.NET Web API application (for self hosted applications, go here). You can create a new C# file in your Web API project and copy paste the code below into it.

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Reflection;
using System.Web.Http.Controllers;
using System.Web.Http.Dependencies;
    
using SimpleInjector;
using SimpleInjector.Extensions;

public sealed class SimpleInjectorWebApiDependencyResolver 
    : IDependencyResolver
{
    private readonly Container container;

    public SimpleInjectorWebApiDependencyResolver(
        Container container)
    {
        this.container = container;
    }

    [DebuggerStepThrough]
    public IDependencyScope BeginScope()
    {
        return this;
    }

    [DebuggerStepThrough]
    public object GetService(Type serviceType)
    {
        return ((IServiceProvider)this.container)
            .GetService(serviceType);
    }

    [DebuggerStepThrough]
    public IEnumerable<object> GetServices(Type serviceType)
    {
        return this.container.GetAllInstances(serviceType);
    }

    [DebuggerStepThrough]
    public void Dispose()
    {
    }
}

The following code snippet shows how to use the SimpleInjectorWebApiDependencyResolver class.

protected void Application_Start(object sender, EventArgs e)
{
    // Create the container as usual.
    var container = new Container();

    // register Web API controllers (important!)
    var controllerTypes =
        from type in Assembly.GetExecutingAssembly().GetExportedTypes()
        where typeof(IHttpController).IsAssignableFrom(type)
        where !type.IsAbstract
        where !type.IsGenericTypeDefinition
        where type.Name.EndsWith("Controller", StringComparison.Ordinal)
        select type;

    foreach (var controllerType in controllerTypes)
    {
        container.Register(controllerType);
    }

    // Register your types, for instance:
    container.Register<IUserRepository, SqlUserRepository>();

    // Verify the container configuration
    container.Verify();

    // Register the dependency resolver.
    GlobalConfiguration.Configuration.DependencyResolver = 
        new SimpleInjectorWebApiDependencyResolver(container);
}

With this configuration, ASP.NET Web API will create new ApiController instances through the container. Because controllers are concrete classes, the container will be able to create them without any registration. However, because of the way Web API requests types from the DependencyResolver, it is very important to register your controllers explicitly. Otherwise, a very generic, non-descriptive exception will be thrown by Web API, when a Controller instance could not be created caused by a misconfiguration. Explicitly registering controller types solves this problem.

Given the configuration above, an actual controller could look like this:

public class UserController : ApiController
{
    private readonly IUserRepository repository;

    // Use constructor injection here
    public UserController(IUserRepository repository)
    {
        this.repository = repository;
    }

    public IEnumerable<User> GetAllUsers()
    {
        return this.repository.GetAll();
    }

    public Product GetUserById(int id)
    {
        try
        {
            return this.repository.GetById(id);
        }
        catch (KeyNotFoundException)
        {
            throw new HttpResponseException(HttpStatusCode.NotFound);
        }
    }
}

New Comment on "Unity"

bdeem — Tue, 09 Apr 2013 14:52:57 GMT

See http://stackoverflow.com/a/13859582 for Batch Registration of generic interfaces in Unity.

Updated Wiki: Advanced-scenarios

dot_NET_Junkie — Fri, 05 Apr 2013 15:33:20 GMT

Note: this documentation is specific for Simple Injector version 2.0 and up. Look here for 1.x specific documentation.

Advanced scenarios with the Simple Injector

Although its name might not indicate it, Simple Injector is capable of handling many complex scenarios. Sometimes by writing some custom code, taking code from this wiki, or by using the extension points from the SimpleInjector.Extensions namespace of the core library.

Note: After including the SimpleInjector.dll to your project, you will have to add the SimpleInjector.Extensions namespace to your code to be able to use most features that are presented in this wiki page.

This page discusses the following subjects:

Batch registration / Automatic registration
Registration of open generic types
Unregistered type resolution
Context based injection / Contextual binding
Decorators
Interception
Property injection
Covariance and Contravariance
Registering plugins dynamically

Batch registration / Automatic registration

Batch registration or automatic registration is a way to register all types in a given source based on some sort of convention. This saves you from adding a new line to your configuration for each new type that you register, as in the following example:

container.Register<IUserRepository, SqlUserRepository>();
container.Register<ICustomerRepository, SqlCustomerRepository>();
container.Register<IOrderRepository, SqlOrderRepository>();
container.Register<IProductRepository, SqlProductRepository>();
// and the list goes on...

To prevent having to change the container configuration too often, we can use the non-generic registration overloads, combined with a simple LINQ query:

var repositoryAssembly = typeof(SqlUserRepository).Assembly;

var registrations =
    from type in repositoryAssembly.GetExportedTypes()
    where type.Namespace == "MyComp.MyProd.BL.SqlRepositories"
    where type.GetInterfaces().Any()
    select new
    {
        Service = type.GetInterfaces().Single(),
        Implementation = type
    };

foreach (var reg in registrations)
{
    container.Register(reg.Service, reg.Implementation, Lifestyle.Transient);
}

Although many DI frameworks contain an advanced API for doing convention based registration, we found that doing this with custom LINQ queries is often easier to write, easier to understand, and even more flexible than using such an API.

Another interesting scenario is that of registering implementations of some generic interface. Say for instance that your application contains the following interface:

public interface IValidate<T>
{
    ValidationResults Validate(T instance);
}

Your application might contain many implementations of this interface, for instance for validating customers, employees, orders, products, etc. You would normally end up with a registration as follows:

container.Register<IValidate<Customer>, CustomerValidator>();
container.Register<IValidate<Employee>, EmployeeValidator>();
container.Register<IValidate<Order>, OrderValidator>();
container.Register<IValidate<Product>, ProductValidator>();
// and the list goes on...

Using the extension methods for batch registration of open generic types from the SimpleInjector.Extesions namespace however, you can write it down to a single line:

container.RegisterManyForOpenGeneric(typeof(IValidate<>),
    typeof(IValidate<>).Assembly);

This call searches in the supplied assembly for all public types that implement the IValidate<T> interface and it registers each type by their specific interface (closed generic) interface. It even works for types that implement multiple closed versions of the given interface.

Note: There are RegisterManyForOpenGeneric overloads available that take a list of System.Type instances, instead a list of Assembly instances.

This however is just one example of what you can do using batch registration. A more advanced scenario is the registration of multiple implementations of the same closed generic type to a single interface. Because there are many possible variations of this scenario, Simple Injector does not contain any methods to do this. It does contain however, multiple overloads of the RegisterManyForOpenGeneric that allows you to supply a callback delegate that lets you do the registration yourself. Take for instance the scenario where you have a CustomerValidator and a GoldCustomerValidator type, that each implement IValidate<Customer>, and you want to register both of them. The previous registration would throw an exception telling you that you have multiple types implementing the same closed generic type. The following registration however, does enable this scenario:

container.RegisterManyForOpenGeneric(typeof(IValidate<>),
    AccessibilityOption.PublicTypesOnly,
    (serviceType, implTypes) => container.RegisterAll(serviceType, implTypes),
    typeof(IValidate<>).Assembly
);

The previous code snippet registers all types from the given assembly that implement IValidate<T> and it registers them as a collection of instances. In other words, with the given example, IValidate<T> instances can be retrieved by calling container.GetAllInstances<IValidate<T>>() or by using an IEnumerable<IValidate<T>> argument in a constructor. However, using an IEnumerable<IValidate<T>> dependency in your constructor or calling into the container directly, are generally not recommended approaches. Depending on a collection of types complicates your application design, and can often be simplified with the right configuration of your container. Your constructors should simply depend on a single IValidator<T>. A better solution would therefore be to create and inject a CompositeValidator<T> in that case:

public class CompositeValidator<T> : IValidate<T>
{
    private readonly IEnumerable<IValidate<T>> validators;

    public CompositeValidator(IEnumerable<IValidate<T>> validators)
    {
        this.validators = validators;
    }

    public ValidationResults Validate(T instance)
    {
        var allResults = ValidationResults.Valid;

        foreach (var validator in this.validators)
        {
            var results = validator.Validate(instance);
            allResults = ValidationResults.Join(allResults, results);
        }

        return allResults;
    }
}

This CompositeValidator<T> can be registered as follows:

container.RegisterSingleOpenGeneric(typeof(IValidate<>), 
    typeof(CompositeValidator<>));

This maps the open generic IValidate<T> interface to the open generic CompositeValidator<T> implementation. Because the CompositeValidator<T> contains an IEnumerable<IValidator<T>> dependency, the registered types will be injected into its constructor. This allows you to let the rest of the application simply depend on the IValidate<T>, while registering a collection of IValidate<T> implementations under the covers.

The next section will explain mapping of open generic types, as the one we've just seen.

Registration of open generic types

When working with generic interfaces, we will often see many implementations of that interface being registered:

container.Register<IValidate<Customer>, CustomerValidator>();
container.Register<IValidate<Employee>, EmployeeValidator>();
container.Register<IValidate<Order>, OrderValidator>();
container.Register<IValidate<Product>, ProductValidator>();
// and the list goes on...

As the previous section explained, this can be rewritten to the following one-liner:

container.RegisterManyForOpenGeneric(typeof(IValidate<>), 
    typeof(IValidate<>).Assembly);

Sometimes you'll find that many implementations of the given generic interface are no-ops. The IValidate<T> is a good example, because it is very likely that not all entities will need validation. Still we would like to prevent from having to write an empty validation class per entity or having to write special application logic to check if an entity has validation. In this situation, we will probably want to use the registration as described in the previous section, and fallback to returning the default implementation when no such registration exists for a given type. Such default implementation could look like this, for instance:

// Implementation of the Null Object pattern.
class NullValidator<T> : IValidate<T>
{
    public ValidationResults Validate(T instance)
    {
        return ValidationResults.Valid;
    }
}

We can use this NullValidator<T> for all entities that don't need validation:

container.Register<IValidate<OrderLine>, NullValidator<OrderLine>>();
container.Register<IValidate<Address>, NullValidator<Address>>();
container.Register<IValidate<UploadImage>, NullValidator<UploadImage>>();
container.Register<IValidate<Mothership>, NullValidator<Mothership>>();
// and the list goes on...

This is of course not very practical. Falling back to such a default implementation is a typical scenario for unregistered type resolution. The Simple Injector contains an event that you can hook to that allows to fallback to a default implementation. On top of this event, the RegisterOpenGeneric extension method available. The given situation would be implemented as follows:

container.RegisterSingleOpenGeneric(
    typeof(IValidate<>), 
    typeof(NullValidator<>));

The result of this registration is that for instance an NullValidator<Department> instance is returned when an IValidate<Department> is requested.

Note: Because the use of unregistered type resolution, a NullValidator<T> will only get returned for types that are not registered, therefore allowing the default implementation to be overridden for a specific implementation. The RegisterManyForOpenGeneric method, for instance, doesn’t use unregistered type resolution, but simply registers all concrete types it finds in the given assemblies. Those types will therefore always be returned, giving a very convenient and easy to grasp mix.

Unregistered type resolution

Unregistered type resolution is the ability to get notified by the container when a type is requested that is currently unregistered in the container. This gives the user the change of registering that type. The Simple Injector supports this scenario with the ResolveUnregisteredType event. Unregistered type resolution enables many advanced scenarios. The framework itself uses this event for implementing the registration of open generic types. Other examples of possible scenarios that can be built on top of this event are resolving array and lists and covariance and contravariance. Those scenarios are described here in the advanced scenarios page.

For more information about how to use this event, please look at the ResolveUnregisteredType event documentation in the reference library.

Context based injection

Context based injection is the ability to inject a dependency based on the context it lives in. This context is often supplied by the container. Some DI frameworks contain a feature that allows this, while others don’t. The Simple Injector does not does not contain such a feature out of the box, but this ability can easily be added by using the context based injection extension method code snippet.

Note: In many cases context based injection is not the best solution, and the design should be reevaluated. In some narrow cases however it can make sense.

The most common scenario is to base the type of the injected dependency on the type of the consumer. Take for instance the following ILogger interface with a generic Logger<T> class that needs to be injected into several consumers.

public interface ILogger
{
    void Log(string message);
}

public class Logger<T> : ILogger
{
    public void Log(string message) { }
}

public class Consumer1
{
    public Consumer1(ILogger logger) { }
}

public class Consumer2
{
    public Consumer2(ILogger logger) { }
}

In this case we want to inject a Logger<Consumer1> into Consumer1 and a Logger<Consumer2> into Consumer2. By using the previous extension method, we can accomplish this as follows:

container.RegisterWithContext<ILogger>(dependencyContext =>
{
    var type = typeof(Logger<>).MakeGenericType(
        dependencyContext.ImplementationType);
    
    return (ILogger)container.GetInstance(type);
});

In the previous code snippet we registered a Func<DependencyContext, ILogger> delegate, that will get called each time a ILogger dependency gets resolved. The DependencyContext instance that gets supplied to that instance, contains the ServiceType and ImplementationType into which the ILogger is getting injected.

Note: Although building a generic type using MakeGenericType is relatively slow, the call to the Func<DependencyContext, TService> delegate itself is about as cheap as calling a Func<TService> delegate. If performance of the MakeGenericType gets a problem, you can always cache the generated types, cache InstanceProducer instances, or cache ILogger instances (note that caching the ILogger instances will make them singletons).

Note: Even though the use of a generic Logger<T> is a common design (with log4net as the grand godfather of this design), doesn't always make it a good design. The need for having the logger contain information about its parent type, might indicate design problems. If you're doing this, please take a look at this Stackoverflow answer. It talks about logging in conjunction with the SOLID design principles.

Decorators

The SOLID principles give us important guidance when it comes to writing maintainable software. The 'O' of the 'SOLID' acronym stands for the Open/closed Principle which states that classes should be open for extension, but closed for modification. Designing systems around the Open/closed principle means that new behavior can be plugged into the system, without the need to change any existing parts, making the change of breaking existing code much smaller.

One of the ways to add new functionality (such as cross-cutting concerns) to types is by the use of the decorator pattern. The decorator pattern can be used to extend (decorate) the functionality of a certain object at run-time. Especially when using generic interfaces, the concept of decorators gets really powerful. Take for instance the examples given in the Registration of open generic types section of this page or for instance the use of an generic ICommandHandler<TCommand> interface.

Tip: This article describes an architecture based on the use of the ICommandHandler<TCommand> interface.

Take the plausible scenario where we want to validate all commands that get executed by an ICommandHandler<TCommand> implementation. The Open/Closed principle states that we want to do this, without having to alter each and every implementation. We can do this using a (single) decorator:

public class ValidationCommandHandlerDecorator<TCommand>
    : ICommandHandler<TCommand>
{
    private readonly IValidator validator;
    private readonly ICommandHandler<TCommand> handler;

    public ValidationCommandHandlerDecorator(
        IValidator validator, 
        ICommandHandler<TCommand> handler)
    {
        this.validator = validator;
        this.handler = handler;
    }

    void ICommandHandler<TCommand>.Handle(TCommand command)
    {
        // validate the supplied command (throws when invalid).
        this.validator.ValidateObject(command);
		
        // forward the (valid) command to the real
        // command handler.
        this.handler.Handle(command);
    }
}

The ValidationCommandHandlerDecorator<TCommand> class is an implementation of the ICommandHandler<TCommand> interface, but it also wraps / decorates an ICommandHandler<TCommand> instance. Instead of injecting the real implementation directly into a consumer, we can (let Simple Injector) inject a validator decorator that wraps the real implementation.

The ValidationCommandHandlerDecorator<TCommand> depends on an IValidator interface. An implementation that used Microsoft Data Annotations might look like this:

using System.ComponentModel.DataAnnotations;

public class DataAnnotationsValidator : IValidator
{
    private readonly IServiceProvider container;
    
    public DataAnnotationsValidator(Container container)
    {
        this.container = container;
    }
    
    void IValidator.ValidateObject(object instance)
    {
        var context = new ValidationContext(instance,
            this.container, null);

        // Throws an exception when instance is invalid.
        Validator.ValidateObject(instance, context);    
    }
}

The implementations of the ICommandHandler<T> interface can be registered using the RegisterManyForOpenGeneric extension method:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);

By using the following extension method from the SimpleInjector.Extensions namespace, you can wrap the ValidationCommandHandlerDecorator<TCommand> around each and every ICommandHandler<TCommand> implementation:

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

Multiple decorators can be wrapped by calling the RegisterDecorator method multiple times, as the following registration shows:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(TransactionCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(DeadlockRetryCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

The decorators are applied in the order in which they are registered, which means that the first decorator (TransactionCommandHandlerDecorator<T> in this case) wraps the real instance, the second decorator (DeadlockRetryCommandHandlerDecorator<T> in this case) wraps the first decorator, and so on.

There's an overload of the RegisterDecorator available that allows you to supply a predicate to determine whether that decorator should be applied to a specific service type. Using a given context you can determine whether the decorator should be applied. Here is an example:

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(AccessValidationCommandHandlerDecorator<>),
    context => !context.ImplementationType.Namespace.EndsWith("Admins"));

The given context contains several properties that allows you to analyze whether a decorator should be applied to a given service type, such as the current closed generic service type (using the ServiceType property) and the concrete type that will be created (using the ImplementationType property). The predicate will (under normal circumstances) be called only once per generic type, so there is no performance implication for using it.

Tip: This extension method allows registering decorators that can be applied based on runtime conditions (such as the role of the current user).

Decorators with Func<T> factories

In certain scenarios, it is needed to postpone building part of the object graph. For instance when a service needs to control the lifetime of a dependency, need multiple instances, when instances need to be executed on a different thread, or when instances need to be created in a certain scope or (security) context.

When building a 'normal' object graph with dependencies, you can easily delay building a part of the graph by letting a service depend on a factory. This allows building that part of the object graph to be postponed until the time the type starts using the factory. When working with decorators however, injecting a factory to postpone the creation of the decorated instance will not work. Take for instance a AsyncCommandHandlerDecorator<T> that allows executing a command handler on a different thread. We could let the AsyncCommandHandlerDecorator<T> depend on a CommandHandlerFactory<T>, and let this factory call back into the container to retrieve a new ICommandHandler<T>. Unfortunately this would fail, since requesting an ICommandHandler<T> would again wrap this instance with a new AsyncCommandHandlerDecorator<T>, and we'd end up causing a stack overflow.

Since this is a scenario that is really hard to solve without framework support, Simple Injector allows injecting a Func<T> delegate into registered decorators. This delegate functions as a factory for the creation of the decorated instance. Taking the AsyncCommandHandlerDecorator<T> as example, it could be implemented as follows:

public class AsyncCommandHandlerDecorator<T>
    : ICommandHandler<T>
{
    private readonly Func<ICommandHandler<T>> factory;

    public AsyncCommandHandlerDecorator(
        Func<ICommandHandler<T>> factory)
    {
        this.factory = factory;
    }
	
    public void Handle(T command)
    {
        // Execute on different thread.
        ThreadPool.QueueUserWorkItem(_ =>
        {
            // Create new handler in this thread.
            var handler = this.factory();
            handler.Handle(command)
        });
    }
}

This special decorator can be registered just as any other decorator:

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));

However, since the AsyncCommandHandlerDecorator<T> solely has singleton dependencies (the Func<T> is a singleton), and creates a new decorated instance each time it’s called, we can even register it as a singleton itself:

container.RegisterSingleDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));

When mixing this with other (synchronous) decorators, you'll get an extremely powerful and pluggable system:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(TransactionCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(DeadlockRetryCommandHandlerDecorator<>));

container.RegisterSingleDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

This configuration has an interesting mix of decorator registrations. The registration of the AsyncCommandHandlerDecorator<T> allows (some of) the command handlers to be executed on the background (while others -who's name does not start with 'Async'- still run synchronously), but before execution, all commands are validated synchronously (to allow communicating validation errors to the caller). And all handlers (even the asynchronous ones) are executed in a transaction and the operation is retried when the database rolled back because of a deadlock).

Decorated collections

When registering a decorator, Simple Injector will automatically decorate any collection with elements of that service type:

container.RegisterAll<IEventHandler<CustomerMovedEvent>>(
    typeof(CustomerMovedEventHandler),
    typeof(NotifyStaffWhenCustomerMovedEventHandler));
    
container.RegisterDecorator(
    typeof(IEventHandler<>),
    typeof(ValidationEventHandlerDecorator<>),
    c => SomeCondition);

The previous registration registers a collection of IEventHandler<CustomerMovedEvent> services. Those services are decorated with a ValidationEventHandlerDecorator<TEvent> when the supplied predicate holds.

For collections of elements that are created by the container (container controlled), the predicate is checked for each element in the collection. For collections of uncontrolled elements (a list of items that is not created by the container), the predicate is checked once for the whole collection. This means that controlled collections can be partially decorated. Taking the previous example for instance, you could let the CustomerMovedEventHandler be decorated, while leaving the NotifyStaffWhenCustomerMovedEventHandler undecorated (determined by the supplied predicate).

When a collection is uncontrolled, it means that the lifetime of its elements are unknown to the container. The following registration is an example of an uncontrolled collection:

IEnumerable<IEventHandler<CustomerMovedEvent>> handlers =
    new IEventHandler<CustomerMovedEvent>[]
    {
        new CustomerMovedEventHandler(),
        new NotifyStaffWhenCustomerMovedEventHandler(),
    };

container.RegisterAll<IEventHandler<CustomerMovedEvent>>(handlers);

Although this registration contains a list of singletons, the container has no way of knowing this. The collection could easily have been a dynamic (an ever changing) collection. In this case, the container calls the registered predicate once (and supplies the predicate with the IEventHandler<CusotmerMovedEvent> type) and if the predicate returns true, each element in the collection is decorated with a decorator instance.

Warning: In general you should prevent registering uncontrolled collections. The container knows nothing about them, and can't help you in doing diagnostics. Since the lifetime of those items is unknown, the container will be unable to wrap a decorator with a lifestyle other than transient. Best practice is to register container-controlled collections which is done by using one of the RegisterAll overloads that take a collection of System.Type instances.

Interception

Interception is the ability to intercept a call from a consumer to a service, and add or change behavior. The decorator pattern describes a form of interception, but when it comes to applying cross-cutting concerns, you might end up writing decorators for many service interfaces, but with the exact same code. If this is happening, it is time to explore the possibilities of interception.

Using the Interception extensions code snippets, you can add the ability to do interception with the Simple Injector. Using the given code, you can for instance define a MonitoringInterceptor that allows logging the execution time of the called service method:

private class MonitoringInterceptor : IInterceptor
{
    private readonly ILogger logger;

    // Using constructor injection on the interceptor
    public MonitoringInterceptor(ILogger logger)
    {
        this.logger = logger;
    }

    public void Intercept(IInvocation invocation)
    {
        var watch = Stopwatch.StartNew();

        // Calls the decorated instance.
        invocation.Proceed();

        var decoratedType =
            invocation.InvocationTarget.GetType();
        
        this.logger.Log(string.Format(
            "{0} executed in {1} ms.",
            decoratedType.Name,
            watch.ElapsedMiliseconds));
    }
}

This interceptor can be registered to be wrapped around a concrete implementation. Using the given extension methods, this can be done as follows:

container.InterceptWith<MonitoringInterceptor>(type => type == typeof(IUserRepository));

This registration ensures that every time an IUserRepository interface is requested, an interception proxy is returned that wraps that instance and uses the MonitoringInterceptor to extend the behavior.

The current example doesn't add much compared to simply using a decorator. When having many interface service types that need to be decorated with the same behavior however, it gets different:

container.InterceptWith<MonitoringInterceptor>(t => t.Name.EndsWith("Repository"));

Note: The Interception extensions code snippets use .NET's System.Runtime.Remoting.Proxies.RealProxy class to generate interception proxies. The RealProxy only allows to proxy interfaces.

Note: the interfaces in the given Interception extensions code snippets are a simplified version of the Castle Project interception facility. If you need to create lots different interceptors, you might benefit from using the interception abilities of the Castle Project. Also please note that the given snippets use dynamic proxies to do the interception, while Castle uses lightweight code generation (LCG). LCG allows much better performance than the use of dynamic proxies.

Note: Don't use interception for intercepting types that all implement the same generic interface, such as ICommandHandler<T> or IValidator<T>. Try using decorator classes instead, as shown in the Decorators section on this page.

Property injection

Simple Injector does not inject any properties into types that get resolved by the container. In general there are two ways of doing property injection, and both are not supported by default for reasons explained below.

Implicit property injection
Some containers (such as Castle Windsor) implicitly inject public writable properties by default for any instance you resolve. They do this by mapping those properties to configured types. When no such registration exists, or when the property doesn’t have a public setter, the property will be skipped. Simple Injector does not do this, and for good reason. We think that implicit property injection is simply too uuhh... implicit :-). Silently skipping properties that can't be mapped can lead to a DI configuration that can't be verified easily and can therefore result in an application that fails at runtime instead of failing when the container is verified.

Explicit property injection
We strongly feel that explicit property injection is a much better way to go. With explicit property injection the container is forced to inject a property and the process will fail immediately when a property can't be mapped or injected. Some containers (such as Unity and Ninject) allow explicit property injection by default by allowing properties to be decorated with attributes. Problem with this is that this forces the application to take a dependency on the framework, which is something that should be prevented.

Because Simple Injector does not encourage its users to take a dependency on the container (except for the startup path of course), Simple Injector does not contain any attributes that allow explicit property injection and it can therefore not explicitly inject properties out-of-the-box.

Besides this, the use of property injection should be very exceptional and in general constructor injection should always be used. If a constructor gets too many parameters (constructor over-injection anti-pattern), it is an indication of a violation of the Single Responsibility Principle (SRP). SRP violations often lead to maintainability issues. So instead of patching constructor over-injection with property injection, the root cause should be analyzed and the type should be refactored, probably with Facade Services. Another common reason to use properties is because those dependencies are optional. Instead of using optional property dependencies, best practice is to inject empty implementations (a.k.a. Null Object pattern) into the constructor.

Enabling property injection
Simple Injector contains two ways to enable property injection. First of all the RegisterInitializer<T> method can be used to inject properties (especially configuration values) on a per-type basis. Take for instance the following code snippet:

container.RegisterInitializer<HandlerBase>(handlerToInitialize =>
{
    handlerToInitialize.ExecuteAsynchronously = true;
});

In the previous example a Action<T> delegate is registered that will be called every time the container creates a type that inherits from HandlerBase. In this case, the handler will set a configuration value on that class.

Note: although this method can also be used injecting services, please note that the Diagnostic Services will be unable to see and analyze this dependency.

The second way to inject properties is by implementing a custom IPropertySelectionBehavior. The property selection behavior is a general extension point provided by the container, to override the library's default behavior. The following code for instance enables explicit property injection using attributes, using any customly defined attribute:

using System;
using System.Diagnostics;
using System.Linq;
using System.Reflection;

using SimpleInjector.Advanced;

public static class AttributedPropertyInjectionExtensions
{
    public static void AutowirePropertiesWithAttribute<TAttribute>(
        this ContainerOptions options)
        where TAttribute : Attribute
    {
        options.PropertySelectionBehavior =
            new AttributePropertyInjectionBehavior(
                options.PropertySelectionBehavior, 
                typeof(TAttribute));
    }

    private sealed class AttributePropertyInjectionBehavior 
        : IPropertySelectionBehavior
    {
        private readonly IPropertySelectionBehavior behavior;
        private readonly Type attribute;

        public AttributePropertyInjectionBehavior(
            IPropertySelectionBehavior baseBehavior, 
            Type attributeType)
        {
            this.behavior = baseBehavior;
            this.attribute = attributeType;
        }

        public bool SelectProperty(Type type, PropertyInfo prop)
        {
            return this.IsPropertyDecorated(prop) ||
                this.behavior.SelectProperty(type, prop);
        }

        private bool IsPropertyDecorated(PropertyInfo p)
        {
            return p.GetCustomAttributes(this.attribute, true).Any();
        }
    }
}

The previous code snippet can be used as follows:

var container = new Container();
container.Options.AutowirePropertiesWithAttribute<MyInjectAttribute>();

This enables explicit property injection on all properties that are marked with the MyInjectAttribute and it will fail when the property cannot be injected for whatever reason.

Tip: Properties injected by the container through the IPropertySelectionBehavior will be analyzed by the Diagnostic Services.

Note: The IPropertySelectionBehavior extension mechanism can also be used to implement implicit property injection. Doing so however is not advised because of the reasons given above.

Covariance and Contravariance

Since version 4.0 of the .NET framework, the type system allows Covariance and Contravariance in Generics (especially interfaces and delegates). This allows for instance, to use a IEnumerable<string> as an IEnumerable<object> (covariance), or to use an Action<object> as an Action<string> (contravariance).

In some circumstances, the application design can benefit from the use of covariance and contravariance (or variance for short) and it would be beneficial when the IoC container returns services that are 'compatible' to the requested service, even although the requested service is not registered. To stick with the previous example, the container could return an IEnumerable<string> even when an IEnumerable<object> is requested.

By default, the Simple Injector does not return variant implementations of given services, but the Simple Injector can be extended to behave this way. The actual way to write this extension depends on the requirements of the application.

Take a look at the following application design around the IEventHandler<in TEvent> interface:

public interface IEventHandler<in TEvent>
{
    void Handle(TEvent e);
}

public class CustomerMovedEvent 
{
    public int CustomerId { get; set; }
    public Address NewAddress { get; set; }
}

public class CustomerMovedAbroadEvent : CustomerMovedEvent
{
    public Country Country { get; set; }
}

public class CustomerMovedEventHandler : IEventHandler<CustomerMovedEvent>
{
    public void Handle(CustomerMovedEvent e) { ... }
}

The design contains two event classes CustomerMovedEvent and CustomerMovedAbroadEvent (where CustomerMovedAbroadEvent inherits from CustomerMovedEvent) one concrete event handler CustomerMovedEventHandler and a generic interface for event handlers.

We can configure the container in such way that not only a request for IEventHandler<CustomerMovedEvent> results in a CustomerMovedEventHandler, but also a request for IEventHandler<CustomerMovedAbroadEvent> results in that same CustomerMovedEventHandler (because CustomerMovedEventHandler also accepts CustomerMovedAbroadEvents).

There are several ways to achieve this, but one of the ways is the following:

container.Register<CustomerMovedEventHandler>();

container.RegisterSingleOpenGeneric(typeof(IEventHandler<>), 
    typeof(ContravarianceEventHandler<>));

This registration depends on the custom ContravarianceEventHandler<TEvent> that should be placed close to the registration itself:

public sealed class ContravarianceEventHandler<TEvent>
    : IEventHandler<TEvent>
{
    private Func<IEventHandler<TEvent>> handlerFactory;

    public ContravarianceEventHandler(Container container)
    {
        var handlerType = typeof(IEventHandler<TEvent>);

        var registration = (
            from r in container.GetCurrentRegistrations()
            let assignableInterfaces = (
                from iface in r.ServiceType.GetInterfaces()
                where handlerType.IsAssignableFrom(iface)
                select iface)
            where assignableInterfaces.Any()
            select r)
            .Single();

        this.handlerFactory =
            () => (IEventHandler<TEvent>)r.GetInstance();
    }

    void IEventHandler<TEvent>.Handle(TEvent e)
    {
        this.handlerFactory().Handle(e);
    }
}

The registration ensures that every time an IEventHandler<TEvent> is requested, a ContravarianceEventHandler<TEvent> is returned. The ContravarianceEventHandler<TEvent> will on creation query the container for a single service type that implements IEventHandler<TEvent>. Because the CustomerMovedEventHandler is not registered by its interface, but by itself, the ContravarianceEventHandler<TEvent> will find that type.

This is just one example and one way of adding variance support. For a more elaborate discussion on this subject, please read the following article: Adding Covariance and Contravariance to the Simple Injector.

Registering plugins dynamically

Applications with a plugin architecture often allow special plugin assemblies to be dropped in a special folder and to be picked up by the application, without the need of a recompile. Although Simple Injector does not support this out of the box, registering plugins from dynamically loaded assemblies can be implemented in a few lines of code. Here is an example:

string pluginDirectory =
    Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Plugins");

var pluginAssemblies =
    from file in new DirectoryInfo(pluginDirectory).GetFiles()
    where file.Extension == ".dll"
    select Assembly.LoadFile(file.FullName);

var pluginTypes =
    from dll in pluginAssemblies
    from type in dll.GetExportedTypes()
    where typeof(IPlugin).IsAssignableFrom(type)
    where !type.IsAbstract
    where !type.IsGenericTypeDefinition
    select type;

container.RegisterAll<IPlugin>(pluginTypes);

The given example makes use of an IPlugin interface that is known to the application, and probably located in a shared assembly. The dynamically loaded plugin .dll files can contain multiple classes that implement IPlugin, and all publicly exposed concrete types that implements IPlugin will be registered using the RegisterAll method and can get resolved using the default auto-wiring behavior of the container, meaning that the plugin must have a single public constructor and all constructor arguments must be resolvable by the container. The plugins can get resolved using container.GetAllInstances<IPlugin>() or by adding an IEnumerable<IPlugin> argument to a constructor.

Resolving instances by key

The information you are looking for has been moved. Please see the Resolve Instances By Key section of the How to documentation page, for the information you are looking for.

Resolving array and lists

The information you are looking for has been moved. Please see the Resolve Arrays and Lists section of the How to page, for the information you are looking for.

Lifetime scoping

The information you are looking for has been moved. Please see the Per Lifetime Scope section of the Object Lifestyle Management documentation page for more information.

Updated Wiki: Runtime-Decorators

dot_NET_Junkie — Fri, 05 Apr 2013 15:29:54 GMT

Applying decorators at runtime using Simple Injector

The RegisterDecorator extension methods contain overloads that allow you to apply a predicate (delegate) that allows you to conditionally apply a decorator.

This predicate is meant to conditionally apply a decorator based on constant information. This can be compile time information such as type names, namespaces, configuration values etc. Because of this this predicate only be called once (or at most a few times) per closed generic type. Whether or not the decorator should be applied is after that point compiled in the delegate.

Sometimes however, decorators must be applied based on some runtime conditions. Take for instance a authorization decorator that must conditionally be applied based on the role of the current user.

The following example shows an extension method that allows registering a decorator using a runtime predicate:

using System;
using System.Linq.Expressions;
using System.Threading;
using SimpleInjector.Extensions;

public static class RuntimeDecoratorExtensions
{
    public static void RegisterRuntimeDecorator(
        this Container container, Type serviceType, Type decoratorType,
        Func<bool> runtimePredicate)
    {
        container.RegisterRuntimeDecorator<Container>(
            serviceType, decoratorType,
            Lifestyle.Transient,
            context => true,
            context => runtimePredicate());
    }

    public static void RegisterRuntimeDecorator<TContextInfo>(
        this Container container, Type serviceType, Type decoratorType,
        Lifestyle lifestyle,
        Predicate<DecoratorPredicateContext> compileTimePredicate,
        Predicate<TContextInfo> runtimePredicate)
        where TContextInfo : class
    {
        var localContext =
                new ThreadLocal<DecoratorPredicateContext>();

        container.RegisterDecorator(serviceType, decoratorType, lifestyle, c =>
        {
            bool mustDecorate = compileTimePredicate(c);
            localContext.Value = mustDecorate ? c : null;
            return mustDecorate;
        });

        container.ExpressionBuilt += (s, e) =>
        {
            if (localContext.Value != null)
            {
                Expression decoratee = localContext.Value.Expression;
                Expression decorated = e.Expression;

                localContext.Value = null;

                var contextInfoRegistration =
                    container.GetRegistration(typeof(TContextInfo), true);

                Expression shouldDecorate = Expression.Invoke(
                    Expression.Constant(runtimePredicate),
                    contextInfoRegistration.BuildExpression());

                e.Expression = Expression.Condition(shouldDecorate,
                    Expression.Convert(decorated, e.RegisteredServiceType),
                    Expression.Convert(decoratee, e.RegisteredServiceType));
            }
        };
    }
}

The following line shows an example of how to use this extension method:

container.RegisterRuntimeDecorator(
    typeof(ICommandHandler<>),
    typeof(AuthorizationHandlerDecorator<>),
    () =>
    {
        var context =
          container.GetInstance<IUserContext>();
        return !context.UserInRole("Admin");
    });

Updated Wiki: Advanced-scenarios

dot_NET_Junkie — Thu, 04 Apr 2013 09:40:40 GMT

Note: this documentation is specific for Simple Injector version 2.0 and up. Look here for 1.x specific documentation.

Advanced scenarios with the Simple Injector

Note: After including the SimpleInjector.dll to your project, you will have to add the SimpleInjector.Extensions namespace to your code to be able to use most features that are presented in this wiki page.

This page discusses the following subjects:

Batch registration / Automatic registration
Registration of open generic types
Unregistered type resolution
Context based injection / Contextual binding
Decorators
Interception
Property injection
Covariance and Contravariance
Registering plugins dynamically

Batch registration / Automatic registration

container.Register<IUserRepository, SqlUserRepository>();
container.Register<ICustomerRepository, SqlCustomerRepository>();
container.Register<IOrderRepository, SqlOrderRepository>();
container.Register<IProductRepository, SqlProductRepository>();
// and the list goes on...

To prevent having to change the container configuration too often, we can use the non-generic registration overloads, combined with a simple LINQ query:

var repositoryAssembly = typeof(SqlUserRepository).Assembly;

var registrations =
    from type in repositoryAssembly.GetExportedTypes()
    where type.Namespace == "MyComp.MyProd.BL.SqlRepositories"
    where type.GetInterfaces().Any()
    select new
    {
        Service = type.GetInterfaces().Single(),
        Implementation = type
    };

foreach (var reg in registrations)
{
    container.Register(reg.Service, reg.Implementation, Lifestyle.Transient);
}

public interface IValidate<T>
{
    ValidationResults Validate(T instance);
}

container.Register<IValidate<Customer>, CustomerValidator>();
container.Register<IValidate<Employee>, EmployeeValidator>();
container.Register<IValidate<Order>, OrderValidator>();
container.Register<IValidate<Product>, ProductValidator>();
// and the list goes on...

Using the extension methods for batch registration of open generic types from the SimpleInjector.Extesions namespace however, you can write it down to a single line:

container.RegisterManyForOpenGeneric(typeof(IValidate<>),
    typeof(IValidate<>).Assembly);

Note: There are RegisterManyForOpenGeneric overloads available that take a list of System.Type instances, instead a list of Assembly instances.

container.RegisterManyForOpenGeneric(typeof(IValidate<>),
    AccessibilityOption.PublicTypesOnly,
    (serviceType, implTypes) => container.RegisterAll(serviceType, implTypes),
    typeof(IValidate<>).Assembly
);

public class CompositeValidator<T> : IValidate<T>
{
    private readonly IEnumerable<IValidate<T>> validators;

    public CompositeValidator(IEnumerable<IValidate<T>> validators)
    {
        this.validators = validators;
    }

    public ValidationResults Validate(T instance)
    {
        var allResults = ValidationResults.Valid;

        foreach (var validator in this.validators)
        {
            var results = validator.Validate(instance);
            allResults = ValidationResults.Join(allResults, results);
        }

        return allResults;
    }
}

This CompositeValidator<T> can be registered as follows:

container.RegisterSingleOpenGeneric(typeof(IValidate<>), 
    typeof(CompositeValidator<>));

Registration of open generic types

When working with generic interfaces, we will often see many implementations of that interface being registered:

container.Register<IValidate<Customer>, CustomerValidator>();
container.Register<IValidate<Employee>, EmployeeValidator>();
container.Register<IValidate<Order>, OrderValidator>();
container.Register<IValidate<Product>, ProductValidator>();
// and the list goes on...

As the previous section explained, this can be rewritten to the following one-liner:

container.RegisterManyForOpenGeneric(typeof(IValidate<>), 
    typeof(IValidate<>).Assembly);

// Implementation of the Null Object pattern.
class NullValidator<T> : IValidate<T>
{
    public ValidationResults Validate(T instance)
    {
        return ValidationResults.Valid;
    }
}

We can use this NullValidator<T> for all entities that don't need validation:

container.Register<IValidate<OrderLine>, NullValidator<OrderLine>>();
container.Register<IValidate<Address>, NullValidator<Address>>();
container.Register<IValidate<UploadImage>, NullValidator<UploadImage>>();
container.Register<IValidate<Mothership>, NullValidator<Mothership>>();
// and the list goes on...

container.RegisterSingleOpenGeneric(
    typeof(IValidate<>), 
    typeof(NullValidator<>));

The result of this registration is that for instance an NullValidator<Department> instance is returned when an IValidate<Department> is requested.

Note: Because the use of unregistered type resolution, a NullValidator<T> will only get returned for types that are not registered, therefore allowing the default implementation to be overridden for a specific implementation. The RegisterManyForOpenGeneric method, for instance, doesn’t use unregistered type resolution, but simply registers all concrete types it finds in the given assemblies. Those types will therefore always be returned, giving a very convenient and easy to grasp mix.

Unregistered type resolution

Context based injection

Note: In many cases context based injection is not the best solution, and the design should be reevaluated. In some narrow cases however it can make sense.

public interface ILogger
{
    void Log(string message);
}

public class Logger<T> : ILogger
{
    public void Log(string message) { }
}

public class Consumer1
{
    public Consumer1(ILogger logger) { }
}

public class Consumer2
{
    public Consumer2(ILogger logger) { }
}

In this case we want to inject a Logger<Consumer1> into Consumer1 and a Logger<Consumer2> into Consumer2. By using the previous extension method, we can accomplish this as follows:

container.RegisterWithContext<ILogger>(dependencyContext =>
{
    var type = typeof(Logger<>).MakeGenericType(
        dependencyContext.ImplementationType);
    
    return (ILogger)container.GetInstance(type);
});

Note: Although building a generic type using MakeGenericType is relatively slow, the call to the Func<DependencyContext, TService> delegate itself is about as cheap as calling a Func<TService> delegate. If performance of the MakeGenericType gets a problem, you can always cache the generated types, cache InstanceProducer instances, or cache ILogger instances (note that caching the ILogger instances will make them singletons).

Note: Even though the use of a generic Logger<T> is a common design (with log4net as the grand godfather of this design), doesn't always make it a good design. The need for having the logger contain information about its parent type, might indicate design problems. If you're doing this, please take a look at this Stackoverflow answer. It talks about logging in conjunction with the SOLID design principles.

Decorators

Tip: This article describes an architecture based on the use of the ICommandHandler<TCommand> interface.

public class ValidationCommandHandlerDecorator<TCommand>
    : ICommandHandler<TCommand>
{
    private readonly IValidator validator;
    private readonly ICommandHandler<TCommand> handler;

    public ValidationCommandHandlerDecorator(
        IValidator validator, 
        ICommandHandler<TCommand> handler)
    {
        this.validator = validator;
        this.handler = handler;
    }

    void ICommandHandler<TCommand>.Handle(TCommand command)
    {
        // validate the supplied command (throws when invalid).
        this.validator.ValidateObject(command);
		
        // forward the (valid) command to the real
        // command handler.
        this.handler.Handle(command);
    }
}

using System.ComponentModel.DataAnnotations;

public class DataAnnotationsValidator : IValidator
{
    private readonly IServiceProvider container;
    
    public DataAnnotationsValidator(Container container)
    {
        this.container = container;
    }
    
    void IValidator.ValidateObject(object instance)
    {
        var context = new ValidationContext(instance,
            this.container, null);

        // Throws an exception when instance is invalid.
        Validator.ValidateObject(instance, context);    
    }
}

The implementations of the ICommandHandler<T> interface can be registered using the RegisterManyForOpenGeneric extension method:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

Multiple decorators can be wrapped by calling the RegisterDecorator method multiple times, as the following registration shows:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(TransactionCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(DeadlockRetryCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(AccessValidationCommandHandlerDecorator<>),
    context => !context.ImplementationType.Namespace.EndsWith("Admins"));

Decorators with Func<T> factories

public class AsyncCommandHandlerDecorator<T>
    : ICommandHandler<T>
{
    private readonly Func<ICommandHandler<T>> factory;

    public AsyncCommandHandlerDecorator(
        Func<ICommandHandler<T>> factory)
    {
        this.factory = factory;
    }
	
    public void Handle(T command)
    {
        // Execute on different thread.
        ThreadPool.QueueUserWorkItem(_ =>
        {
            // Create new handler in this thread.
            var handler = this.factory();
            handler.Handle(command)
        });
    }
}

This special decorator can be registered just as any other decorator:

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));

container.RegisterSingleDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));

When mixing this with other (synchronous) decorators, you'll get an extremely powerful and pluggable system:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(TransactionCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(DeadlockRetryCommandHandlerDecorator<>));

container.RegisterSingleDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

Decorated collections

When registering a decorator, Simple Injector will automatically decorate any collection with elements of that service type:

container.RegisterAll<IEventHandler<CustomerMovedEvent>>(
    typeof(CustomerMovedEventHandler),
    typeof(NotifyStaffWhenCustomerMovedEventHandler));
    
container.RegisterDecorator(
    typeof(IEventHandler<>),
    typeof(ValidationEventHandlerDecorator<>),
    c => SomeCondition);

IEnumerable<IEventHandler<CustomerMovedEvent>> handlers =
    new IEventHandler<CustomerMovedEvent>[]
    {
        new CustomerMovedEventHandler(),
        new NotifyStaffWhenCustomerMovedEventHandler(),
    };

container.RegisterAll<IEventHandler<CustomerMovedEvent>>(handlers);

Warning: In general you should prevent registering uncontrolled collections. The container knows nothing about them, and can't help you in doing diagnostics. Since the lifetime of those items is unknown, the container will be unable to wrap a decorator with a lifestyle other than transient. Best practice is to register container-controlled collections which is done by using one of the RegisterAll overloads that take a collection of System.Type instances.

Interception

private class MonitoringInterceptor : IInterceptor
{
    private readonly ILogger logger;

    // Using constructor injection on the interceptor
    public MonitoringInterceptor(ILogger logger)
    {
        this.logger = logger;
    }

    public void Intercept(IInvocation invocation)
    {
        var watch = Stopwatch.StartNew();

        // Calls the decorated instance.
        invocation.Proceed();

        var decoratedType =
            invocation.InvocationTarget.GetType();
        
        this.logger.Log(string.Format(
            "{0} executed in {1} ms.",
            decoratedType.Name,
            watch.ElapsedMiliseconds));
    }
}

This interceptor can be registered to be wrapped around a concrete implementation. Using the given extension methods, this can be done as follows:

container.InterceptWith<MonitoringInterceptor>(type => type == typeof(IUserRepository));

container.InterceptWith<MonitoringInterceptor>(t => t.Name.EndsWith("Repository"));

Note: The Interception extensions code snippets use .NET's System.Runtime.Remoting.Proxies.RealProxy class to generate interception proxies. The RealProxy only allows to proxy interfaces.

Note: the interfaces in the given Interception extensions code snippets are a simplified version of the Castle Project interception facility. If you need to create lots different interceptors, you might benefit from using the interception abilities of the Castle Project. Also please note that the given snippets use dynamic proxies to do the interception, while Castle uses lightweight code generation (LCG). LCG allows much better performance than the use of dynamic proxies.

Note: Don't use interception for intercepting types that all implement the same generic interface, such as ICommandHandler<T> or IValidator<T>. Try using decorator classes instead, as shown in the Decorators section on this page.

Property injection

container.RegisterInitializer<HandlerBase>(handlerToInitialize =>
{
    handlerToInitialize.ExecuteAsynchronously = true;
});

Note: although this method can also be used injecting services, please note that the Diagnostic Services will be unable to see and analyze this dependency.

using System;
using System.Diagnostics;
using System.Linq;
using System.Reflection;

using SimpleInjector.Advanced;

public static class AttributedPropertyInjectionExtensions
{
    public static void AutowirePropertiesWithAttribute<TAttribute>(
        this ContainerOptions options)
        where TAttribute : Attribute
    {
        options.PropertySelectionBehavior =
            new AttributePropertyInjectionBehavior(
                options.PropertySelectionBehavior, 
                typeof(TAttribute));
    }

    private sealed class AttributePropertyInjectionBehavior 
        : IPropertySelectionBehavior
    {
        private readonly IPropertySelectionBehavior behavior;
        private readonly Type attribute;

        public AttributePropertyInjectionBehavior(
            IPropertySelectionBehavior baseBehavior, 
            Type attributeType)
        {
            this.behavior = baseBehavior;
            this.attribute = attributeType;
        }

        public bool SelectProperty(Type type, PropertyInfo prop)
        {
            return this.IsPropertyDecorated(prop) ||
                this.behavior.SelectProperty(type, prop);
        }

        private bool IsPropertyDecorated(PropertyInfo p)
        {
            return p.GetCustomAttributes(this.attribute, true).Any();
        }
    }
}

The previous code snippet can be used as follows:

var container = new Container();
container.Options.AutowirePropertiesWithAttribute<MyInjectAttribute>();

This enables explicit property injection on all properties that are marked with the MyInjectAttribute and it will fail when the property cannot be injected for whatever reason.

Tip: Properties injected by the container through the IPropertySelectionBehavior will be analyzed by the Diagnostic Services.

Note: The IPropertySelectionBehavior extension mechanism can also be used to implement implicit property injection. Doing so however is not advised because of the reasons given above.

Covariance and Contravariance

public interface IEventHandler<in TEvent>
{
    void Handle(TEvent e);
}

public class CustomerMovedEvent 
{
    public int CustomerId { get; set; }
    public Address NewAddress { get; set; }
}

public class CustomerMovedAbroadEvent : CustomerMovedEvent
{
    public Country Country { get; set; }
}

public class CustomerMovedEventHandler : IEventHandler<CustomerMovedEvent>
{
    public void Handle(CustomerMovedEvent e) { ... }
}

container.Register<CustomerMovedEventHandler>();

container.RegisterSingleOpenGeneric(typeof(IEventHandler<>), 
    typeof(ContravarianceEventHandler<>));

This registration depends on the custom ContravarianceEventHandler<TEvent> that should be placed close to the registration itself:

public sealed class ContravarianceEventHandler<TEvent>
    : IEventHandler<TEvent>
{
    private Func<IEventHandler<TEvent>> handlerFactory;

    public ContravarianceEventHandler(Container container)
    {
        var handlerType = typeof(IEventHandler<TEvent>);

        var registration = (
            from r in container.GetCurrentRegistrations()
            let assignableInterfaces = (
                from iface in r.ServiceType.GetInterfaces()
                where handlerType.IsAssignableFrom(iface)
                select iface)
            where assignableInterfaces.Any()
            select r)
            .Single();

        this.handlerFactory =
            () => (IEventHandler<TEvent>)r.GetInstance();
    }

    void IEventHandler<TEvent>.Handle(TEvent e)
    {
        this.handlerFactory().Handle(e);
    }
}

Registering plugins dynamically

string pluginDirectory =
    Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Plugins");

var pluginAssemblies =
    from file in new DirectoryInfo(pluginDirectory).GetFiles()
    where file.Extension == ".dll"
    select Assembly.LoadFile(file.FullName);

var pluginTypes =
    from dll in pluginAssemblies
    from type in dll.GetExportedTypes()
    where typeof(IPlugin).IsAssignableFrom(type)
    where !type.IsAbstract
    where !type.IsGenericTypeDefinition
    select type;

container.RegisterAll<IPlugin>(pluginTypes);

Resolving instances by key

The information you are looking for has been moved. Please see the Resolve Instances By Key section of the How to documentation page, for the information you are looking for.

Resolving array and lists

The information you are looking for has been moved. Please see the Resolve Arrays and Lists section of the How to page, for the information you are looking for.

Lifetime scoping

The information you are looking for has been moved. Please see the Per Lifetime Scope section of the Object Lifestyle Management documentation page for more information.

Updated Wiki: Advanced-scenarios

dot_NET_Junkie — Thu, 04 Apr 2013 09:40:16 GMT

Note: this documentation is specific for Simple Injector version 2.0 and up. Look here for 1.x specific documentation.

Advanced scenarios with the Simple Injector

Note: After including the SimpleInjector.dll to your project, you will have to add the SimpleInjector.Extensions namespace to your code to be able to use most features that are presented in this wiki page.

This page discusses the following subjects:

Batch registration / Automatic registration
Registration of open generic types
Unregistered type resolution
Context based injection / Contextual binding
Decorators
Interception
Property injection
Covariance and Contravariance
Registering plugins dynamically

Batch registration / Automatic registration

container.Register<IUserRepository, SqlUserRepository>();
container.Register<ICustomerRepository, SqlCustomerRepository>();
container.Register<IOrderRepository, SqlOrderRepository>();
container.Register<IProductRepository, SqlProductRepository>();
// and the list goes on...

To prevent having to change the container configuration too often, we can use the non-generic registration overloads, combined with a simple LINQ query:

var repositoryAssembly = typeof(SqlUserRepository).Assembly;

var registrations =
    from type in repositoryAssembly.GetExportedTypes()
    where type.Namespace == "MyComp.MyProd.BL.SqlRepositories"
    where type.GetInterfaces().Any()
    select new
    {
        Service = type.GetInterfaces().Single(),
        Implementation = type
    };

foreach (var reg in registrations)
{
    container.Register(reg.Service, reg.Implementation, Lifestyle.Transient);
}

public interface IValidate<T>
{
    ValidationResults Validate(T instance);
}

container.Register<IValidate<Customer>, CustomerValidator>();
container.Register<IValidate<Employee>, EmployeeValidator>();
container.Register<IValidate<Order>, OrderValidator>();
container.Register<IValidate<Product>, ProductValidator>();
// and the list goes on...

Using the extension methods for batch registration of open generic types from the SimpleInjector.Extesions namespace however, you can write it down to a single line:

container.RegisterManyForOpenGeneric(typeof(IValidate<>),
    typeof(IValidate<>).Assembly);

Note: There are RegisterManyForOpenGeneric overloads available that take a list of System.Type instances, instead a list of Assembly instances.

container.RegisterManyForOpenGeneric(typeof(IValidate<>),
    AccessibilityOption.PublicTypesOnly,
    (serviceType, implTypes) => container.RegisterAll(serviceType, implTypes),
    typeof(IValidate<>).Assembly
);

public class CompositeValidator<T> : IValidate<T>
{
    private readonly IEnumerable<IValidate<T>> validators;

    public CompositeValidator(IEnumerable<IValidate<T>> validators)
    {
        this.validators = validators;
    }

    public ValidationResults Validate(T instance)
    {
        var allResults = ValidationResults.Valid;

        foreach (var validator in this.validators)
        {
            var results = validator.Validate(instance);
            allResults = ValidationResults.Join(allResults, results);
        }

        return allResults;
    }
}

This CompositeValidator<T> can be registered as follows:

container.RegisterSingleOpenGeneric(typeof(IValidate<>), 
    typeof(CompositeValidator<>));

Registration of open generic types

When working with generic interfaces, we will often see many implementations of that interface being registered:

container.Register<IValidate<Customer>, CustomerValidator>();
container.Register<IValidate<Employee>, EmployeeValidator>();
container.Register<IValidate<Order>, OrderValidator>();
container.Register<IValidate<Product>, ProductValidator>();
// and the list goes on...

As the previous section explained, this can be rewritten to the following one-liner:

container.RegisterManyForOpenGeneric(typeof(IValidate<>), 
    typeof(IValidate<>).Assembly);

// Implementation of the Null Object pattern.
class NullValidator<T> : IValidate<T>
{
    public ValidationResults Validate(T instance)
    {
        return ValidationResults.Valid;
    }
}

We can use this NullValidator<T> for all entities that don't need validation:

container.Register<IValidate<OrderLine>, NullValidator<OrderLine>>();
container.Register<IValidate<Address>, NullValidator<Address>>();
container.Register<IValidate<UploadImage>, NullValidator<UploadImage>>();
container.Register<IValidate<Mothership>, NullValidator<Mothership>>();
// and the list goes on...

container.RegisterSingleOpenGeneric(
    typeof(IValidate<>), 
    typeof(NullValidator<>));

The result of this registration is that for instance an NullValidator<Department> instance is returned when an IValidate<Department> is requested.

Note: Because the use of unregistered type resolution, a NullValidator<T> will only get returned for types that are not registered, therefore allowing the default implementation to be overridden for a specific implementation. The RegisterManyForOpenGeneric method, for instance, doesn’t use unregistered type resolution, but simply registers all concrete types it finds in the given assemblies. Those types will therefore always be returned, giving a very convenient and easy to grasp mix.

Unregistered type resolution

Context based injection

Note: In many cases context based injection is not the best solution, and the design should be reevaluated. In some narrow cases however it can make sense.

public interface ILogger
{
    void Log(string message);
}

public class Logger<T> : ILogger
{
    public void Log(string message) { }
}

public class Consumer1
{
    public Consumer1(ILogger logger) { }
}

public class Consumer2
{
    public Consumer2(ILogger logger) { }
}

In this case we want to inject a Logger<Consumer1> into Consumer1 and a Logger<Consumer2> into Consumer2. By using the previous extension method, we can accomplish this as follows:

container.RegisterWithContext<ILogger>(dependencyContext =>
{
    var type = typeof(Logger<>).MakeGenericType(
        dependencyContext.ImplementationType);
    
    return (ILogger)container.GetInstance(type);
});

Note: Although building a generic type using MakeGenericType is relatively slow, the call to the Func<DependencyContext, TService> delegate itself is about as cheap as calling a Func<TService> delegate. If performance of the MakeGenericType gets a problem, you can always cache the generated types, cache InstanceProducer instances, or cache ILogger instances (note that caching the ILogger instances will make them singletons).

Note: Even though the use of a generic Logger<T> is a common design (with log4net as the grand godfather of this design), doesn't always make it a good design. The need for having the logger contain information about its parent type, might indicate design problems. If you're doing this, please take a look at this Stackoverflow answer. It talks about logging in conjunction with the SOLID design principles.

Decorators

Tip: This article describes an architecture based on the use of the ICommandHandler<TCommand> interface.

public class ValidationCommandHandlerDecorator<TCommand>
    : ICommandHandler<TCommand>
{
    private readonly IValidator validator;
    private readonly ICommandHandler<TCommand> handler;

    public ValidationCommandHandlerDecorator(
        IValidator validator, 
        ICommandHandler<TCommand> handler)
    {
        this.validator = validator;
        this.handler = handler;
    }

    void ICommandHandler<TCommand>.Handle(TCommand command)
    {
        // validate the supplied command (throws when invalid).
        this.validator.ValidateObject(command);
		
        // forward the (valid) command to the real
        // command handler.
        this.handler.Handle(command);
    }
}

using System.ComponentModel.DataAnnotations;

public class DataAnnotationsValidator : IValidator
{
    private readonly IServiceProvider container;
    
    public DataAnnotationsValidator(Container container)
    {
        this.container = container;
    }
    
    void IValidator.ValidateObject(object instance)
    {
        var context = new ValidationContext(instance,
            this.container, null);

        // Throws an exception when instance is invalid.
        Validator.ValidateObject(instance, context);    
    }
}

The implementations of the ICommandHandler<T> interface can be registered using the RegisterManyForOpenGeneric extension method:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

Multiple decorators can be wrapped by calling the RegisterDecorator method multiple times, as the following registration shows:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(TransactionCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(DeadlockRetryCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(AccessValidationCommandHandlerDecorator<>),
    context => !context.ImplementationType.Namespace.EndsWith("Admins"));

Decorators with Func<T> factories

public class AsyncCommandHandlerDecorator<T>
    : ICommandHandler<T>
{
    private readonly Func<ICommandHandler<T>> factory;

    public AsyncCommandHandlerDecorator(
        Func<ICommandHandler<T>> factory)
    {
        this.factory = factory;
    }
	
    public void Handle(T command)
    {
        // Execute on different thread.
        ThreadPool.QueueUserWorkItem(_ =>
        {
            // Create new handler in this thread.
            var handler = this.factory();
            handler.Handle(command)
        });
    }
}

This special decorator can be registered just as any other decorator:

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));

container.RegisterSingleDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));

When mixing this with other (synchronous) decorators, you'll get an extremely powerful and pluggable system:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(TransactionCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(DeadlockRetryCommandHandlerDecorator<>));

container.RegisterSingleDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

Decorated collections

When registering a decorator, Simple Injector will automatically decorate any collection with elements of that service type:

container.RegisterAll<IEventHandler<CustomerMovedEvent>>(
    typeof(CustomerMovedEventHandler),
    typeof(NotifyStaffWhenCustomerMovedEventHandler));
    
container.RegisterDecorator(
    typeof(IEventHandler<>),
    typeof(ValidationEventHandlerDecorator<>),
    c => SomeCondition);

IEnumerable<IEventHandler<CustomerMovedEvent>> handlers =
    new IEventHandler<CustomerMovedEvent>[]
    {
        new CustomerMovedEventHandler(),
        new NotifyStaffWhenCustomerMovedEventHandler(),
    };

container.RegisterAll<IEventHandler<CustomerMovedEvent>>(handlers);

Warning: In general you should prevent registering uncontrolled collections. The container knows nothing about them, and can't help you in doing diagnostics. Since the lifetime of those items is unknown, the container will be unable to wrap a decorator with a lifestyle other than transient. Best practice is to register container-controlled collections which is done by using one of the RegisterAll overloads that take a collection of System.Type instances.

Interception

private class MonitoringInterceptor : IInterceptor
{
    private readonly ILogger logger;

    // Using constructor injection on the interceptor
    public MonitoringInterceptor(ILogger logger)
    {
        this.logger = logger;
    }

    public void Intercept(IInvocation invocation)
    {
        var watch = Stopwatch.StartNew();

        // Calls the decorated instance.
        invocation.Proceed();

        var decoratedType =
            invocation.InvocationTarget.GetType();
        
        this.logger.Log(string.Format(
            "{0} executed in {1} ms.",
            decoratedType.Name,
            watch.ElapsedMiliseconds));
    }
}

This interceptor can be registered to be wrapped around a concrete implementation. Using the given extension methods, this can be done as follows:

container.InterceptWith<MonitoringInterceptor>(type => type == typeof(IUserRepository));

container.InterceptWith<MonitoringInterceptor>(t => t.Name.EndsWith("Repository"));

Note: The Interception extensions code snippets use .NET's System.Runtime.Remoting.Proxies.RealProxy class to generate interception proxies. The RealProxy only allows to proxy interfaces.

Note: the interfaces in the given Interception extensions code snippets are a simplified version of the Castle Project interception facility. If you need to create lots different interceptors, you might benefit from using the interception abilities of the Castle Project. Also please note that the given snippets use dynamic proxies to do the interception, while Castle uses lightweight code generation (LCG). LCG allows much better performance than the use of dynamic proxies.

Note: Don't use interception for intercepting types that all implement the same generic interface, such as ICommandHandler<T> or IValidator<T>. Try using decorator classes instead, as shown in the Decorators section on this page.

Property injection

container.RegisterInitializer<HandlerBase>(handlerToInitialize =>
{
    handlerToInitialize.ExecuteAsynchronously = true;
});

Note: although this method can also be used injecting services, please note that the Diagnostic Services will be unable to see and analyze this dependency.

using System;
using System.Diagnostics;
using System.Linq;
using System.Reflection;

using SimpleInjector.Advanced;

public static class AttributedPropertyInjectionExtensions
{
    public static void AutowirePropertiesWithAttribute<TAttribute>(
        this ContainerOptions options)
        where TAttribute : Attribute
    {
        options.PropertySelectionBehavior =
            new AttributePropertyInjectionBehavior(
                options.PropertySelectionBehavior, 
                typeof(TAttribute));
    }

    private sealed class AttributePropertyInjectionBehavior 
        : IPropertySelectionBehavior
    {
        private readonly IPropertySelectionBehavior behavior;
        private readonly Type attribute;

        public AttributePropertyInjectionBehavior(
            IPropertySelectionBehavior baseBehavior, 
            Type attributeType)
        {
            this.behavior = baseBehavior;
            this.attribute = attributeType;
        }

        public bool SelectProperty(Type type, PropertyInfo prop)
        {
            return this.IsPropertyDecorated(prop) ||
                this.behavior.SelectProperty(type, prop);
        }

        private bool IsPropertyDecorated(PropertyInfo p)
        {
            return p.GetCustomAttributes(this.attribute, true).Any();
        }
    }
}

The previous code snippet can be used as follows:

var container = new Container();
container.Options.AutowirePropertiesWithAttribute<MyInjectAttribute>();

This enables explicit property injection on all properties that are marked with the MyInjectAttribute and it will fail when the property cannot be injected for whatever reason.

Tip: Properties injected by the container through the IPropertySelectionBehavior will be analyzed by the Diagnostic Services.

_Note: The IPropertySelectionBehavior extension mechanism can also be used to implement implicit property injection. Doing so however is not advised because of the reasons given above.

Covariance and Contravariance

public interface IEventHandler<in TEvent>
{
    void Handle(TEvent e);
}

public class CustomerMovedEvent 
{
    public int CustomerId { get; set; }
    public Address NewAddress { get; set; }
}

public class CustomerMovedAbroadEvent : CustomerMovedEvent
{
    public Country Country { get; set; }
}

public class CustomerMovedEventHandler : IEventHandler<CustomerMovedEvent>
{
    public void Handle(CustomerMovedEvent e) { ... }
}

container.Register<CustomerMovedEventHandler>();

container.RegisterSingleOpenGeneric(typeof(IEventHandler<>), 
    typeof(ContravarianceEventHandler<>));

This registration depends on the custom ContravarianceEventHandler<TEvent> that should be placed close to the registration itself:

public sealed class ContravarianceEventHandler<TEvent>
    : IEventHandler<TEvent>
{
    private Func<IEventHandler<TEvent>> handlerFactory;

    public ContravarianceEventHandler(Container container)
    {
        var handlerType = typeof(IEventHandler<TEvent>);

        var registration = (
            from r in container.GetCurrentRegistrations()
            let assignableInterfaces = (
                from iface in r.ServiceType.GetInterfaces()
                where handlerType.IsAssignableFrom(iface)
                select iface)
            where assignableInterfaces.Any()
            select r)
            .Single();

        this.handlerFactory =
            () => (IEventHandler<TEvent>)r.GetInstance();
    }

    void IEventHandler<TEvent>.Handle(TEvent e)
    {
        this.handlerFactory().Handle(e);
    }
}

Registering plugins dynamically

string pluginDirectory =
    Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Plugins");

var pluginAssemblies =
    from file in new DirectoryInfo(pluginDirectory).GetFiles()
    where file.Extension == ".dll"
    select Assembly.LoadFile(file.FullName);

var pluginTypes =
    from dll in pluginAssemblies
    from type in dll.GetExportedTypes()
    where typeof(IPlugin).IsAssignableFrom(type)
    where !type.IsAbstract
    where !type.IsGenericTypeDefinition
    select type;

container.RegisterAll<IPlugin>(pluginTypes);

Resolving instances by key

The information you are looking for has been moved. Please see the Resolve Instances By Key section of the How to documentation page, for the information you are looking for.

Resolving array and lists

The information you are looking for has been moved. Please see the Resolve Arrays and Lists section of the How to page, for the information you are looking for.

Lifetime scoping

The information you are looking for has been moved. Please see the Per Lifetime Scope section of the Object Lifestyle Management documentation page for more information.

Updated Wiki: Advanced-scenarios

dot_NET_Junkie — Thu, 04 Apr 2013 09:37:03 GMT

Note: this documentation is specific for Simple Injector version 2.0 and up. Look here for 1.x specific documentation.

Advanced scenarios with the Simple Injector

Note: After including the SimpleInjector.dll to your project, you will have to add the SimpleInjector.Extensions namespace to your code to be able to use most features that are presented in this wiki page.

This page discusses the following subjects:

Batch registration / Automatic registration
Registration of open generic types
Unregistered type resolution
Context based injection / Contextual binding
Decorators
Interception
Property injection
Covariance and Contravariance
Registering plugins dynamically

Batch registration / Automatic registration

container.Register<IUserRepository, SqlUserRepository>();
container.Register<ICustomerRepository, SqlCustomerRepository>();
container.Register<IOrderRepository, SqlOrderRepository>();
container.Register<IProductRepository, SqlProductRepository>();
// and the list goes on...

To prevent having to change the container configuration too often, we can use the non-generic registration overloads, combined with a simple LINQ query:

var repositoryAssembly = typeof(SqlUserRepository).Assembly;

var registrations =
    from type in repositoryAssembly.GetExportedTypes()
    where type.Namespace == "MyComp.MyProd.BL.SqlRepositories"
    where type.GetInterfaces().Any()
    select new
    {
        Service = type.GetInterfaces().Single(),
        Implementation = type
    };

foreach (var reg in registrations)
{
    container.Register(reg.Service, reg.Implementation, Lifestyle.Transient);
}

public interface IValidate<T>
{
    ValidationResults Validate(T instance);
}

container.Register<IValidate<Customer>, CustomerValidator>();
container.Register<IValidate<Employee>, EmployeeValidator>();
container.Register<IValidate<Order>, OrderValidator>();
container.Register<IValidate<Product>, ProductValidator>();
// and the list goes on...

Using the extension methods for batch registration of open generic types from the SimpleInjector.Extesions namespace however, you can write it down to a single line:

container.RegisterManyForOpenGeneric(typeof(IValidate<>),
    typeof(IValidate<>).Assembly);

Note: There are RegisterManyForOpenGeneric overloads available that take a list of System.Type instances, instead a list of Assembly instances.

container.RegisterManyForOpenGeneric(typeof(IValidate<>),
    AccessibilityOption.PublicTypesOnly,
    (serviceType, implTypes) => container.RegisterAll(serviceType, implTypes),
    typeof(IValidate<>).Assembly
);

public class CompositeValidator<T> : IValidate<T>
{
    private readonly IEnumerable<IValidate<T>> validators;

    public CompositeValidator(IEnumerable<IValidate<T>> validators)
    {
        this.validators = validators;
    }

    public ValidationResults Validate(T instance)
    {
        var allResults = ValidationResults.Valid;

        foreach (var validator in this.validators)
        {
            var results = validator.Validate(instance);
            allResults = ValidationResults.Join(allResults, results);
        }

        return allResults;
    }
}

This CompositeValidator<T> can be registered as follows:

container.RegisterSingleOpenGeneric(typeof(IValidate<>), 
    typeof(CompositeValidator<>));

Registration of open generic types

When working with generic interfaces, we will often see many implementations of that interface being registered:

container.Register<IValidate<Customer>, CustomerValidator>();
container.Register<IValidate<Employee>, EmployeeValidator>();
container.Register<IValidate<Order>, OrderValidator>();
container.Register<IValidate<Product>, ProductValidator>();
// and the list goes on...

As the previous section explained, this can be rewritten to the following one-liner:

container.RegisterManyForOpenGeneric(typeof(IValidate<>), 
    typeof(IValidate<>).Assembly);

// Implementation of the Null Object pattern.
class NullValidator<T> : IValidate<T>
{
    public ValidationResults Validate(T instance)
    {
        return ValidationResults.Valid;
    }
}

We can use this NullValidator<T> for all entities that don't need validation:

container.Register<IValidate<OrderLine>, NullValidator<OrderLine>>();
container.Register<IValidate<Address>, NullValidator<Address>>();
container.Register<IValidate<UploadImage>, NullValidator<UploadImage>>();
container.Register<IValidate<Mothership>, NullValidator<Mothership>>();
// and the list goes on...

container.RegisterSingleOpenGeneric(
    typeof(IValidate<>), 
    typeof(NullValidator<>));

The result of this registration is that for instance an NullValidator<Department> instance is returned when an IValidate<Department> is requested.

Note: Because the use of unregistered type resolution, a NullValidator<T> will only get returned for types that are not registered, therefore allowing the default implementation to be overridden for a specific implementation. The RegisterManyForOpenGeneric method, for instance, doesn’t use unregistered type resolution, but simply registers all concrete types it finds in the given assemblies. Those types will therefore always be returned, giving a very convenient and easy to grasp mix.

Unregistered type resolution

Context based injection

Note: In many cases context based injection is not the best solution, and the design should be reevaluated. In some narrow cases however it can make sense.

public interface ILogger
{
    void Log(string message);
}

public class Logger<T> : ILogger
{
    public void Log(string message) { }
}

public class Consumer1
{
    public Consumer1(ILogger logger) { }
}

public class Consumer2
{
    public Consumer2(ILogger logger) { }
}

In this case we want to inject a Logger<Consumer1> into Consumer1 and a Logger<Consumer2> into Consumer2. By using the previous extension method, we can accomplish this as follows:

container.RegisterWithContext<ILogger>(dependencyContext =>
{
    var type = typeof(Logger<>).MakeGenericType(
        dependencyContext.ImplementationType);
    
    return (ILogger)container.GetInstance(type);
});

Note: Although building a generic type using MakeGenericType is relatively slow, the call to the Func<DependencyContext, TService> delegate itself is about as cheap as calling a Func<TService> delegate. If performance of the MakeGenericType gets a problem, you can always cache the generated types, cache InstanceProducer instances, or cache ILogger instances (note that caching the ILogger instances will make them singletons).

Note: Even though the use of a generic Logger<T> is a common design (with log4net as the grand godfather of this design), doesn't always make it a good design. The need for having the logger contain information about its parent type, might indicate design problems. If you're doing this, please take a look at this Stackoverflow answer. It talks about logging in conjunction with the SOLID design principles.

Decorators

Tip: This article describes an architecture based on the use of the ICommandHandler<TCommand> interface.

public class ValidationCommandHandlerDecorator<TCommand>
    : ICommandHandler<TCommand>
{
    private readonly IValidator validator;
    private readonly ICommandHandler<TCommand> handler;

    public ValidationCommandHandlerDecorator(
        IValidator validator, 
        ICommandHandler<TCommand> handler)
    {
        this.validator = validator;
        this.handler = handler;
    }

    void ICommandHandler<TCommand>.Handle(TCommand command)
    {
        // validate the supplied command (throws when invalid).
        this.validator.ValidateObject(command);
		
        // forward the (valid) command to the real
        // command handler.
        this.handler.Handle(command);
    }
}

using System.ComponentModel.DataAnnotations;

public class DataAnnotationsValidator : IValidator
{
    private readonly IServiceProvider container;
    
    public DataAnnotationsValidator(Container container)
    {
        this.container = container;
    }
    
    void IValidator.ValidateObject(object instance)
    {
        var context = new ValidationContext(instance,
            this.container, null);

        // Throws an exception when instance is invalid.
        Validator.ValidateObject(instance, context);    
    }
}

The implementations of the ICommandHandler<T> interface can be registered using the RegisterManyForOpenGeneric extension method:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

Multiple decorators can be wrapped by calling the RegisterDecorator method multiple times, as the following registration shows:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(TransactionCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(DeadlockRetryCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(AccessValidationCommandHandlerDecorator<>),
    context => !context.ImplementationType.Namespace.EndsWith("Admins"));

Decorators with Func<T> factories

public class AsyncCommandHandlerDecorator<T>
    : ICommandHandler<T>
{
    private readonly Func<ICommandHandler<T>> factory;

    public AsyncCommandHandlerDecorator(
        Func<ICommandHandler<T>> factory)
    {
        this.factory = factory;
    }
	
    public void Handle(T command)
    {
        // Execute on different thread.
        ThreadPool.QueueUserWorkItem(_ =>
        {
            // Create new handler in this thread.
            var handler = this.factory();
            handler.Handle(command)
        });
    }
}

This special decorator can be registered just as any other decorator:

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));

container.RegisterSingleDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));

When mixing this with other (synchronous) decorators, you'll get an extremely powerful and pluggable system:

container.RegisterManyForOpenGeneric(
    typeof(ICommandHandler<>), 
    typeof(ICommandHandler<>).Assembly);
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(TransactionCommandHandlerDecorator<>));

container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(DeadlockRetryCommandHandlerDecorator<>));

container.RegisterSingleDecorator(
    typeof(ICommandHandler<>),
    typeof(AsyncCommandHandlerDecorator<>),
    c => c.ImplementationType.Name.StartsWith("Async"));
	
container.RegisterDecorator(
    typeof(ICommandHandler<>),
    typeof(ValidationCommandHandlerDecorator<>));

Decorated collections

When registering a decorator, Simple Injector will automatically decorate any collection with elements of that service type:

container.RegisterAll<IEventHandler<CustomerMovedEvent>>(
    typeof(CustomerMovedEventHandler),
    typeof(NotifyStaffWhenCustomerMovedEventHandler));
    
container.RegisterDecorator(
    typeof(IEventHandler<>),
    typeof(ValidationEventHandlerDecorator<>),
    c => SomeCondition);

IEnumerable<IEventHandler<CustomerMovedEvent>> handlers =
    new IEventHandler<CustomerMovedEvent>[]
    {
        new CustomerMovedEventHandler(),
        new NotifyStaffWhenCustomerMovedEventHandler(),
    };

container.RegisterAll<IEventHandler<CustomerMovedEvent>>(handlers);

Warning: In general you should prevent registering uncontrolled collections. The container knows nothing about them, and can't help you in doing diagnostics. Since the lifetime of those items is unknown, the container will be unable to wrap a decorator with a lifestyle other than transient. Best practice is to register container-controlled collections which is done by using one of the RegisterAll overloads that take a collection of System.Type instances.

Interception

private class MonitoringInterceptor : IInterceptor
{
    private readonly ILogger logger;

    // Using constructor injection on the interceptor
    public MonitoringInterceptor(ILogger logger)
    {
        this.logger = logger;
    }

    public void Intercept(IInvocation invocation)
    {
        var watch = Stopwatch.StartNew();

        // Calls the decorated instance.
        invocation.Proceed();

        var decoratedType =
            invocation.InvocationTarget.GetType();
        
        this.logger.Log(string.Format(
            "{0} executed in {1} ms.",
            decoratedType.Name,
            watch.ElapsedMiliseconds));
    }
}

This interceptor can be registered to be wrapped around a concrete implementation. Using the given extension methods, this can be done as follows:

container.InterceptWith<MonitoringInterceptor>(type => type == typeof(IUserRepository));

container.InterceptWith<MonitoringInterceptor>(t => t.Name.EndsWith("Repository"));

Note: The Interception extensions code snippets use .NET's System.Runtime.Remoting.Proxies.RealProxy class to generate interception proxies. The RealProxy only allows to proxy interfaces.

Note: the interfaces in the given Interception extensions code snippets are a simplified version of the Castle Project interception facility. If you need to create lots different interceptors, you might benefit from using the interception abilities of the Castle Project. Also please note that the given snippets use dynamic proxies to do the interception, while Castle uses lightweight code generation (LCG). LCG allows much better performance than the use of dynamic proxies.

Note: Don't use interception for intercepting types that all implement the same generic interface, such as ICommandHandler<T> or IValidator<T>. Try using decorator classes instead, as shown in the Decorators section on this page.

Property injection

container.RegisterInitializer<HandlerBase>(handlerToInitialize =>
{
    handlerToInitialize.ExecuteAsynchronously = true;
});

Note: although this method can also be used injecting services, please note that the Diagnostic Services will be unable to see and analyze this dependency.

using System;
using System.Diagnostics;
using System.Linq;
using System.Reflection;

using SimpleInjector.Advanced;

public static class AttributedPropertyInjectionExtensions
{
    public static void AutowirePropertiesWithAttribute<TAttribute>(
        this ContainerOptions options)
        where TAttribute : Attribute
    {
        options.PropertySelectionBehavior =
            new AttributePropertyInjectionBehavior(
                options.PropertySelectionBehavior, 
                typeof(TAttribute));
    }

    private sealed class AttributePropertyInjectionBehavior 
        : IPropertySelectionBehavior
    {
        private readonly IPropertySelectionBehavior behavior;
        private readonly Type attribute;

        public AttributePropertyInjectionBehavior(
            IPropertySelectionBehavior baseBehavior, 
            Type attributeType)
        {
            this.behavior = baseBehavior;
            this.attribute = attributeType;
        }

        public bool SelectProperty(Type type, PropertyInfo prop)
        {
            return this.IsPropertyDecorated(prop) ||
                this.behavior.SelectProperty(type, prop);
        }

        private bool IsPropertyDecorated(PropertyInfo p)
        {
            return p.GetCustomAttributes(this.attribute, true).Any();
        }
    }
}

The previous code snippet can be used as follows:

var container = new Container();
container.Options.AutowirePropertiesWithAttribute<MyInjectAttribute>();

This enables explicit property injection on all properties that are marked with the MyInjectAttribute and it will fail when the property cannot be injected for whatever reason.

Tip: Properties injected by the container through the IPropertySelectionBehavior will be analyzed by the Diagnostic Services.

Covariance and Contravariance

public interface IEventHandler<in TEvent>
{
    void Handle(TEvent e);
}

public class CustomerMovedEvent 
{
    public int CustomerId { get; set; }
    public Address NewAddress { get; set; }
}

public class CustomerMovedAbroadEvent : CustomerMovedEvent
{
    public Country Country { get; set; }
}

public class CustomerMovedEventHandler : IEventHandler<CustomerMovedEvent>
{
    public void Handle(CustomerMovedEvent e) { ... }
}

container.Register<CustomerMovedEventHandler>();

container.RegisterSingleOpenGeneric(typeof(IEventHandler<>), 
    typeof(ContravarianceEventHandler<>));

This registration depends on the custom ContravarianceEventHandler<TEvent> that should be placed close to the registration itself:

public sealed class ContravarianceEventHandler<TEvent>
    : IEventHandler<TEvent>
{
    private Func<IEventHandler<TEvent>> handlerFactory;

    public ContravarianceEventHandler(Container container)
    {
        var handlerType = typeof(IEventHandler<TEvent>);

        var registration = (
            from r in container.GetCurrentRegistrations()
            let assignableInterfaces = (
                from iface in r.ServiceType.GetInterfaces()
                where handlerType.IsAssignableFrom(iface)
                select iface)
            where assignableInterfaces.Any()
            select r)
            .Single();

        this.handlerFactory =
            () => (IEventHandler<TEvent>)r.GetInstance();
    }

    void IEventHandler<TEvent>.Handle(TEvent e)
    {
        this.handlerFactory().Handle(e);
    }
}

Registering plugins dynamically

string pluginDirectory =
    Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Plugins");

var pluginAssemblies =
    from file in new DirectoryInfo(pluginDirectory).GetFiles()
    where file.Extension == ".dll"
    select Assembly.LoadFile(file.FullName);

var pluginTypes =
    from dll in pluginAssemblies
    from type in dll.GetExportedTypes()
    where typeof(IPlugin).IsAssignableFrom(type)
    where !type.IsAbstract
    where !type.IsGenericTypeDefinition
    select type;

container.RegisterAll<IPlugin>(pluginTypes);

Resolving instances by key

The information you are looking for has been moved. Please see the Resolve Instances By Key section of the How to documentation page, for the information you are looking for.

Resolving array and lists

The information you are looking for has been moved. Please see the Resolve Arrays and Lists section of the How to page, for the information you are looking for.

Lifetime scoping

The information you are looking for has been moved. Please see the Per Lifetime Scope section of the Object Lifestyle Management documentation page for more information.

Updated Wiki: UnregisteredTypes

dot_NET_Junkie — Thu, 04 Apr 2013 09:30:36 GMT

Diagnostic Warning - Unregistered Types

Cause

An concrete type that was not registered explicitly and was not resolved using unregistered type resolution, but was created by the container using the transient lifestyle.

Warning Description

The unregistered typed warning shows all concrete types that weren't registered explicitly, but registered by the container as transient for you, because they were referenced by another component's constructor or were resolved through a direct call to container.GetIntance<T>() (inside a RegisterInitializer registered delegate for instance).

This warning deserves your attention, since it might indicate that you program to implementations, instead of abstractions. Although the Potential Lifestyle Mismatches and Short Circuited Dependencies warnings are a very strong signal of a configuration problem, this Unregistered Type warnings is just a point of attention.

How to Fix Violations

Let components depend on an interface that described the contract that this concrete type implements and register that concrete type in the container by that interface.

When to Ignore Warnings

If your intention is to resolve those types as transient and don't depend directly on their concrete types (for instance because you register a collection of transient types), this warning can in general be ignored safely.

Example

var container = new Container();

container.Register<HomeController>();

container.Verify();

// Definition of HomeController
public class HomeController : Controller {
    private readonly SqlUserRepository repository;

    public HomeController(SqlUserRepository repository) {
        this.repository = repository;
    }
}

The given example registers a HomeController class that depends on an unregistered SqlUserRepository class. Injecting a concrete type can lead to a lot of problems, such as:

It makes the HomeController hard to test, since concrete types are often hard to fake (or when using a mocking framework that fixes this, would still result in unit tests that contain a lot of configuration for the mocking framework, instead of pure test logic) making the unit tests hard to read and hard to maintain.
It makes it harder to reuse the class, since it expects a certain implementation of its dependency.
It makes it harder to add cross-cutting concerns (such as logging, audit trailing and authorization) to the system, because this must now either be added directly in the SqlUserRepository class (which will make this class hard to test and hard to maintain) or all constructors of classes that depend on SqlUserRepository must be changed to allow injecting a type that adds these cross-cutting concerns.

Instead of depending directly on SqlUserRepository, HomeController can better depend on an IUserRepository abstraction:

var container = new Container();

container.Register<IUserRepository, SqlUserRepository>();
container.Register<HomeController>();

container.Verify();

// Definition of HomeController
public class HomeController : Controller {
    private readonly IUserRepository repository;

    public HomeController(IUserRepository repository) {
        this.repository = repository;
    }
}

Tip: It would probably be better to define an generic IRepository<T> abstraction. This makes easy to batch registration implementations and allows cross-cutting concerns to be added using decorators.

The following example shows the registration of a collection of types:

var container = new Container();

container.RegisterAll<ILogger>(
    typeof(FileLogger),
    typeof(DbLogger),
    typeof(WindowsEventLogger));

In this case FileLogger, DbLogger and WindowsEventLogger are not registered explicitly, and will be resolved with the transient lifestyle. When the application does not depend directly on one of those types, but only on IEnumerable<ILogger>, the application will still only depend on abstractions. In that case this warning can be ignored safely.