Installers

Installers ensure that endpoint-specific artifacts (e.g. database tables, queues, directories, etc.) are created and configured.

When to run installers

Installers require permissions to administer resources such as database tables, queues, or directories. Following the principle of least privilege, it is recommended to run an endpoint with these elevated permissions only during initial deployment.

The alternative to using installers is to create the required resources before the endpoint is run. This may also result in slightly faster startup times. The method of doing this varies for each transport or persistence package. For more information, see operations.

Running installers

When requiring special privileges to setup the endpoint, the installer API can be used to run all necessary installation steps:

var hostBuilder = new HostApplicationBuilder();
var endpointConfiguration = new EndpointConfiguration("someEndpoint");

hostBuilder.Services.AddNServiceBusEndpoint(endpointConfiguration);

// On run, this will run the installers and then stop the host
hostBuilder.Services.AddNServiceBusInstallers();

// OR, this will run the installers and allow the host to continue
hostBuilder.Services.AddNServiceBusInstallers(options =>
    options.ShutdownBehavior = InstallersShutdownBehavior.Continue);

// This will run the installers with the requested ShutdownBehavior
await hostBuilder.Build()
    .RunAsync();

The installer APIs are intended to be used when resources required by the endpoint must be set up with different privileges than the endpoint itself requires. To setup the endpoint as part of the endpoint host process, see the Running installers during endpoint startup article.

Auto-subscribe is not part of installers

NServiceBus detects all events an endpoint handles and auto-subscribes to these events at startup. Automatic subscriptions can be turned off by disabling the auto subscribe feature.

Running installers during endpoint startup

By default, installers are disabled.

Installers can be enabled to always run at startup:

endpointConfiguration.EnableInstallers();

Installers may need to be run depending on the arguments that are provided to the host or aspects the environment the endpoint is hosted in.

For example, installers can be enabled based on command line arguments:

var runInstallers = Environment.GetCommandLineArgs().Any(x => string.Equals(x, "/runInstallers", StringComparison.OrdinalIgnoreCase));

if (runInstallers)
{
    endpointConfiguration.EnableInstallers();
}

They can also be enabled by a machine name convention:

if (!Environment.MachineName.EndsWith("-PROD"))
{
    endpointConfiguration.EnableInstallers();
}

Custom installers

Implement the INeedToInstallSomething interface to create a custom installer:

public class MyInstaller : INeedToInstallSomething
{
    public Task Install(string identity, CancellationToken cancellationToken)
    {
        // Code to install something

        return Task.CompletedTask;
    }
}

Installer registration

Installers can be added directly to the EndpointConfiguration:

endpointConfiguration.AddInstaller<MyInstaller>();

Or from a Feature class that requires them:

public class MyFeature : Feature
{
    protected override void Setup(FeatureConfigurationContext context)
    {
        context.AddInstaller<MyInstaller>();
    }
}