Installers

Component: NServiceBus
NuGet Package NServiceBus (6.x)

Installers ensure that endpoint-specific artifacts (e.g. queues, directories, databases etc) are installed and configured when the endpoint is started.

Running installers

Running installers requires the process to run with permissions to create/delete tables, queues, folders and other resources. It is recommended to apply the principle of least privilege and prevent running an endpoint process with too many permissions. Consider running the installers only during the initial setup using elevated permissions.

By default, installers are only run when the application starts with a debugger attached. This includes applications being debugged remotely.

Installers can be enabled to always run at startup:

endpointConfiguration.EnableInstallers();

// this will run the installers
await Endpoint.Start(endpointConfiguration)
    .ConfigureAwait(false);

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:

public static void Main(string[] args)
{
    var runInstallers = args.Any(x => x.ToLower() == "/runInstallers");

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

They can also be enabled by a machine name convention like:

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

Starting with NServiceBus Version 6.4, installers can be disabled to never run at startup:

endpointConfiguration.DisableInstallers();

// this will not run the installers
await Endpoint.Start(endpointConfiguration)
    .ConfigureAwait(false);

Custom installers

To create a custom installer implement the INeedToInstallSomething interface.

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

        return Task.CompletedTask;
    }
}

Assemblies in the runtime directory are scanned for installers so no code is needed to register them.

Related Articles


Last modified