Configuring Distributor and Workers

Component: Distributor
NuGet Package NServiceBus.Distributor.MSMQ (4.x)
Target NServiceBus Version: 4.x
Standard support for version 4.x of NServiceBus has expired. For more information see our Support Policy.


NServiceBus 4.2 and below

In Version 4.2 and below Distributor was included in the NServiceBus package.

NServiceBus 4.3 to 5.0

In Version 4.3 the built-in Distributor has been deprecated. The new dedicated NServiceBus.Distributor.MSMQ package should be used instead.

NServiceBus 6.0 and above

Running an embedded distributor process alongside the worker (also known as Master mode) is not supported in Versions 6 and higher. Instead, a stand alone Distributor endpoint running NServiceBus 5 should be used.

Worker configuration sections like MasterNodeConfig are obsoleted and endpointConfiguraiton.EnlistWithLegacyMSMQDistributor should be used instead. For more information refer to Upgrading a Distributor-based scaled out endpoint to Version 6 documentation.

Distributor configuration

When hosting endpoints in NServiceBus.Host.exe

If running with NServiceBus.Host.exe, the following profiles start the endpoint with the Distributor functionality:

To start the endpoint as a Distributor install the NServiceBus.Distributor.MSMQ NuGet and then run the host from the command line, as follows:

NServiceBus.Host.exe NServiceBus.MSMQDistributor

The NServiceBus.MSMQDistributor profile instructs the NServiceBus framework to start a distributor process on this endpoint, waiting for workers to enlist to it. Unlike the NServiceBus.MSMQMaster profile, the NServiceBus.MSMQDistributor profile does not execute a worker process.

It is also possible to use the NServiceBus.MSMQMaster profile to start distributor and worker processes on the endpoint. To start the endpoint as a Master install the NServiceBus.Distributor.MSMQ NuGet and then run the host from the command line, as follows:

NServiceBus.Host.exe NServiceBus.MSMQMaster

When self-hosting

When self hosting the endpoint, use this configuration:

// Running the Distributor and a Worker
// or

// Running the Distributor only
configure.RunMSMQDistributor(withWorker: false);

Worker Configuration

Any NServiceBus endpoint can run as a Worker node. To activate it, create a handler for the relevant messages and ensure that the app.config file contains routing information for the Distributor.

When hosting in NServiceBus.Host.exe

If hosting the endpoint with NServiceBus.Host.exe, to run as a Worker, use this command line:

Configure the name of the master node server as shown in this app.config example. Note the MasterNodeConfig section:

    <!-- Other sections go here -->
    <section name="MasterNodeConfig" 
             type="NServiceBus.Config.MasterNodeConfig, NServiceBus.Core" />
  <!-- Other config options go here -->
  <MasterNodeConfig Node="MachineWhereDistributorRuns"/>

Read about the DistributorControlAddress and the DistributorDataAddress in the Routing with the Distributor section.

When self-hosting

If self-hosting the endpoint here is the code required to enlist the endpoint with a Distributor.


Similar to self-hosting, if running NServiceBus prior to Version 6, ensure the app.config of the worker contains the MasterNodeConfig section to point to the hostname where the distributor process is running.

Last modified