Installers

Component: NServiceBus
NuGet Package NServiceBus (3.x)
Standard support for version 3.x of NServiceBus has expired. For more information see our Support Policy.

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

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.

For example, an endpoint can be started manually as an administrator or elevated user to allow installers to run. The required resources will be ready as soon as the endpoint has successfully started. The endpoint can then be shut down and installed as a service, which can run as a regular user that does not have permission to modify resources.

The alternative to using installers is to create the required resources before the endpoint is run. The method of doing this varies for each transport or persistence package. For more information, see operations.

Running installers

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:

var configUnicastBus = configure.UnicastBus();
var startableBus = configUnicastBus.CreateBus();
startableBus.Start(
    startupAction: () =>
    {
        configure.ForInstallationOn<Windows>().Install();
    });

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

    var configUnicastBus = configure.UnicastBus();
    var startableBus = configUnicastBus.CreateBus();

    if (runInstallers)
    {
        startableBus.Start(
            startupAction: () =>
            {
                configure.ForInstallationOn<Windows>().Install();
            });
    }
}

They can also be enabled by a machine name convention:

var configUnicastBus = configure.UnicastBus();
var startableBus = configUnicastBus.CreateBus();

if (!Environment.MachineName.EndsWith("-PROD"))
{
    startableBus.Start(
        startupAction: () =>
        {
            configure.ForInstallationOn<Windows>().Install();
        });
}

Custom installers

Implement the INeedToInstallSomething interface to create a custom installer:

public class MyInstaller :
    INeedToInstallSomething
{
    public void Install(WindowsIdentity identity)
    {
        // Code to install something
    }
}

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

Related Articles


Last modified