Dependency Injection

NServiceBus automatically registers and invokes message handlers, sagas, and other user-provided extension points using a dependency injection container.

Modes of operation

NServiceBus supports two modes for dependency injection:

• Internally managed: NServiceBus manages the container lifecycle as part of the endpoint lifecycle.
• Externally managed: The application or host provides and controls the container lifecycle.

Internally managed mode

In internally managed mode, NServiceBus manages the entire lifecycle of the container, including registration, component resolution, and disposal.

Built-in default container

NServiceBus has a built-in default container with an API for registration of user types. The following dependency lifecycles are supported:

Instance per call

A new instance will be returned for each call.

Represented by the enum value DependencyLifecycle.InstancePerCall.

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.ConfigureComponent<MyService>(DependencyLifecycle.InstancePerCall);
    });

or using a delegate:

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.ConfigureComponent(
            componentFactory: () =>
            {
                return new MyService();
            },
            dependencyLifecycle: DependencyLifecycle.InstancePerCall);
    });

Instance per unit of work

The instance will be a singleton for the duration of the unit of work. In practice this means the processing of a single transport message.

Represented by the enum value DependencyLifecycle.InstancePerUnitOfWork.

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.ConfigureComponent<MyService>(DependencyLifecycle.InstancePerUnitOfWork);
    });

or using a delegate:

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.ConfigureComponent(
            componentFactory: () =>
            {
                return new MyService();
            },
            dependencyLifecycle: DependencyLifecycle.InstancePerUnitOfWork);
    });

Single instance

The same instance will be returned each time.

Represented by the enum value DependencyLifecycle.SingleInstance.

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.ConfigureComponent<MyService>(DependencyLifecycle.SingleInstance);
    });

or using a delegate:

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.ConfigureComponent(
            componentFactory: () =>
            {
                return new MyService();
            },
            dependencyLifecycle: DependencyLifecycle.SingleInstance);
    });

or using the explicit singleton API:

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.RegisterSingleton(new MyService());
    });

Using a third party container

NServiceBus also supports the following third party containers:

• Autofac
• CastleWindsor
• Ninject
• SimpleInjector (Community project)
• Spring
• StructureMap
• Unity

Plugging in other containers

If a specific library is not supported, create a plugin using the IContainer abstraction. Once this is created and registered, NServiceBus will use the custom dependency injection to look up its own dependencies.

Create a class that implements 'IContainer':

public class MyContainer :
    IContainer
{

Create a class that implements 'ContainerDefinition' and returns the 'IContainer' implementation:

public class MyContainerDefinition :
    ContainerDefinition
{
    public override IContainer CreateContainer(ReadOnlySettings settings)
    {
        return new MyContainer();
    }
}

Then register the ContainerDefinition to be used:

endpointConfiguration.UseContainer<MyContainerDefinition>();

Externally managed mode

In externally managed mode, NServiceBus registers its components in the container but does not own the container's lifecycle. The container is provided by the user in two phases, one for registration (IConfigureComponents) and one for resolution (IBuilder).

During the registration phase, an instance of IConfigureComponents is passed to the EndpointWithExternallyManagedContainer.Create method. For example, for Autofac's ContainerBuilder, this is the phase during which its type registration methods would be called.

IConfigureComponents configureComponents =
    AdaptContainerForRegistrationPhase(myCustomContainer);

var startableEndpoint = EndpointWithExternallyManagedContainer.Create(endpointConfiguration, configureComponents);

Later, during the resolution phase, the Start method requires an instance of IBuilder. At this stage, the container has already been initialized with all its registrations. For example, for Autofac's ContainerBuilder, this is the phase during which its Build method would be called.

IBuilder builder = AdaptContainerForResolutionPhase(myCustomContainer);

var startedEndpoint = await startableEndpoint.Start(builder);

Injecting the message session

IMessageSession is not registered automatically in the container and must be registered explicitly to be injected. Access to the session is provided via IStartableEndpointWithExternallyManagedContainer.MessageSession

The NServiceBus.Extensions.DependencyInjection Usage sample demonstrates how to register the message session.