Connection settings

Target Version: NServiceBus 6.x
Standard support for version 6.x of NServiceBus has expired. For more information see our Support Policy.

The RabbitMQ transport requires a connection string to connect to the RabbitMQ broker. While RabbitMQ uses the AMQP URI Specification, the RabbitMQ transport uses its own connection string format.

Specifying the connection string via code

To specify the connection string in code:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();
transport.ConnectionString("My custom connection string");

Specifying the connection string via app.config

By default, the transport will look for a connection string called NServiceBus/Transport in app.config:

  <add name="NServiceBus/Transport"

To use a custom name for the connection string:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();

Connection string options

Below is the list of connection string options. When constructing a connection string, these options should be separated by a semicolon.


The host name of the broker.

This Host value is required.

By default, the guest user can only connect via localhost. If connecting to a remote host, a user name and password must be provided.

   <add name="NServiceBus/Transport"


The port where the broker listens.

Default: 5671 if the UseTls setting is set to true, otherwise the default value is 5672


The virtual host to use.

Default: /


The user name to use to connect to the broker.

Default: guest


The password to use to connect to the broker.

Default: guest


The interval for heartbeats between the endpoint and the broker.

Default: 5 seconds


The time to wait before trying to reconnect to the broker if the connection is lost.

Default: 10 seconds


Indicates if the connection to the broker should be secured with TLS.

Default: false


The file path to the client authentication certificate when using TLS.


The password for the client authentication certificate specified in CertPath

Transport Layer Security support

Secure connections to the broker using Transport Layer Security (TLS) are supported. To enable TLS support, set the UseTls setting to true in the connection string:

TLS 1.2 must be enabled on the broker to establish a secure connection.

Client authentication

If the broker has been configured to require client authentication, a client certificate must be specified in the CertPath setting. If that certificate requires a password, it must be specified in the CertPassphrase setting.

A sample connection string using these settings:


In Versions 4.3 and above, client certificates can be specified via code instead of using CertPath and CertPassphrase:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();
transport.SetClientCertificates(new X509CertificateCollection());
If a certificate is specified via the code API, the CertPath and CertPassphrase connection string settings are ignored.

Remote certificate validation

By default, the RabbitMQ client will refuse to connect to the broker if the remote server certificate is invalid. In Versions 4.4 and above, this validation can be disabled by using the following setting:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();

External authentication

By default, the broker requires a username and password to authenticate the client, but it can be configured to use other external authentication mechanisms. If the broker requires an external authentication mechanism, the client can be configured to use it with the following setting:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();

Controlling the prefetch count

When consuming messages from the broker, throughput can be improved by having the consumer prefetch additional messages. The prefetch count is calculated by multiplying maximum concurrency by the prefetch multiplier. The default value of the multiplier is 3, but it can be changed by using the following:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();

Alternatively, the whole calculation can be overridden by setting the prefetch count directly using the following:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();
If the configured value is less than the maximum concurrency, the prefetch count will be set to the maximum concurrency value instead.

Publisher confirms

Publisher confirms are enabled by default, but they can be disabled by using the following:

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();
When publisher confirms are disabled, send operations might not fail with an exception when the destination exchanges/queues don't exist.

Controlling behavior when the broker connection is lost

The RabbitMQ transport monitors the connection to the broker and will trigger the critical error action if the connection fails and stays disconnected for the configured amount of time.


Controls the amount of time the transport waits after a failure is detected before triggering the critical error action.

Type: System.TimeSpan

Default: 00:02:00 (2 minutes)

var transport = endpointConfiguration.UseTransport<RabbitMQTransport>();

Debugging recommendations

For debugging purposes, it can be helpful to increase the RequestedHeartbeat setting as shown below:

  <add name="NServiceBus/Transport"

Increasing this setting can help avoiding the connection timeout while the debugging.

Last modified