Getting Started

Dependency Injection

Component: NServiceBus
NuGet Package: NServiceBus (8.x)

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

NServiceBus supports two modes of operation for containers, internally managed and externally managed.

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 uses the Microsoft.Extensions.DependencyInjection container by default. Custom services may be registered using the IServiceCollection API.

Instance per call

A new instance will be returned for each call.

Represented by the enum value ServiceLifetime.Transient.

    registration: configureComponents =>

or using a delegate:

    registration: configureComponents =>
        configureComponents.AddTransient(serviceProvider => new MyService());

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 ServiceLifetime.Scoped.

    registration: configureComponents =>

or using a delegate:

    registration: configureComponents =>
        configureComponents.AddScoped(serviceProvider => new MyService());

Single instance

The same instance will be returned each time.

Represented by the enum value ServiceLifetime.Singleton.

Singleton components with dependencies that are scoped Transient or Scoped will still resolve. In effect, these dependencies, while not scoped as Singleton, will behave as if they are Singleton because the instances will exist inside the parent component.
    registration: configureComponents =>

or using a delegate:

    registration: configureComponents =>
        configureComponents.AddSingleton(serviceProvider => new MyService());

Using a third party containers

Third party or custom dependency injection containers can be used via the externally managed mode.

Externally managed mode

In externally managed mode, NServiceBus registers its components in the container but does not own the container's lifecycle. NServiceBus uses the Microsoft.Extensions.DependencyInjection API to integrate with third party containers.

Every NServiceBus endpoint requires its own dependency injection container. Sharing containers across multiple endpoints results in conflicting registrations and might cause incorrect behavior or runtime errors.

During the registration phase, an instance of IServiceCollection is passed to the EndpointWithExternallyManagedContainer.Create method. The following snippets show how to use Microsoft's default implementation from the Microsoft.Extensions.DependencyInjection NuGet package:

IServiceCollection serviceCollection = new ServiceCollection();

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

Later, during the resolution phase, the Start method requires an instance of IServiceProvider.

IServiceProvider builder = serviceCollection.BuildServiceProvider();

var startedEndpoint = await startableEndpoint.Start(builder);
Refer to the container's documentation on how to use the container with the Microsoft.Extensions.DependencyInjection API.

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 session is only valid for use after the endpoint have been started, so it is provided as Lazy<IMessageSession>.

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

Microsoft Generic Host

When hosting NServiceBus with the Microsoft Generic Host using the NServiceBus.Extensions.Hosting package, refer to the configure custom containers documentation for further details.

Resolving dependencies

It is recommended to follow the dependency injection guidelines for .NET. Be aware of the following special cases with NServiceBus:


Related Articles

  • Autofac
    Details on how to Configure NServiceBus to use Autofac for dependency injection.
  • Castle Windsor
    Details on how to Configure NServiceBus to use Castle Windsor for dependency injection.
  • Child containers
    Child containers allow for more granular instance lifetime configuration.
  • Ninject
    Configure NServiceBus to use Ninject for dependency injection.
  • NServiceBus.Extensions.DependencyInjection
    Integration with Microsoft.Extensions.DependencyInjection.
  • Spring
    Details on how to Configure NServiceBus to use Spring for dependency injection.
  • StructureMap
    Details on how to Configure NServiceBus to use StructureMap for dependency injection.
  • Unity
    Details on how to Configure NServiceBus to use Unity for dependency injection.