Dependency Injection

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.

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.AddTransient<MyService>();
    });

or using a delegate:

endpointConfiguration.RegisterComponents(
    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.

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.AddScoped<MyService>();
    });

or using a delegate:

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

Single instance

The same instance will be returned each time.

Represented by the enum value ServiceLifetime.Singleton.

endpointConfiguration.RegisterComponents(
    registration: configureComponents =>
    {
        configureComponents.AddSingleton<MyService>();
    });

or using a delegate:

endpointConfiguration.RegisterComponents(
    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.

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);

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.

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:

• Injecting dependencies into behaviors