Connection settings

Component: RabbitMQ Transport
NuGet Package NServiceBus.RabbitMQ (3.x)
Target NServiceBus Version: 5.x

RabbitMQ uses the AMQP URI Specification. The RabbitMQ transport requires a connection string to connect to the RabbitMQ broker. This connection string can be specified via code or via app.config.

Specifying the connection string via code

To specify the connection string in code:

var transport = busConfiguration.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:

<connectionStrings>
  <add name="NServiceBus/Transport"
       connectionString="host=broker1"/>
</connectionStrings>

To use a custom name for the connection string:

var transport = busConfiguration.UseTransport<RabbitMQTransport>();
transport.ConnectionStringName("MyConnectionStringName");

Connection string options

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

Host

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.

<connectionStrings>
   <add name="NServiceBus/Transport"
        connectionString="host=myremoteserver;
                          username=myusername;
                          password=mypassword"/>
</connectionStrings>

Port

The port where the broker listens.

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

VirtualHost

The virtual host to use.

Default: /

UserName

The user name to use to connect to the broker.

Default: guest

Password

The password to use to connect to the broker.

Default: guest

RequestedHeartbeat

The interval for the heartbeats between the client and the server.

Default: 5 seconds

DequeueTimeout

The time period allowed for the dequeue strategy to dequeue a message.

Default: 1 second

PrefetchCount

The number of messages to prefetch when consuming messages from the broker.

Default: The number of configured threads for the transport (as of Version 2.1)

UsePublisherConfirms

Controls if publisher confirms should be used.

Default: true

MaxWaitTimeForConfirms

How long the client should wait for publisher confirms, if enabled.

Default: 30 seconds.

RetryDelay

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

Default: 10 seconds

UseTls

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

Default: false

Versions: 3.2 and above

CertPath

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

Versions: 3.2 and above

CertPassphrase

The password for the client authentication certificate specified in CertPath

Versions: 3.2 and above

For debugging purposes, it can be helpful to increase the RequestedHeartbeat and DequeueTimeout settings as shown below:
<connectionStrings>
  <add name="NServiceBus/Transport"
       connectionString="host=broker1;RequestedHeartbeat=600;DequeueTimeout=600"/>
</connectionStrings>

Increasing these settings can help prevent the connection to the broker from timing out while the code is paused from hitting a breakpoint.

Transport Layer Security support

In Versions 3.2 and above, 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. 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.

An example connection string using these settings:

3.2 NServiceBus.RabbitMQ
host=broker1;UseTls=true;CertPath=C:\CertificatePath\ssl.pfx;CertPassphrase=securePassword
TLS 1.2 must be enabled on the broker to establish a secure connection.

Providing a custom connection manager

The default connection manager that comes with the transport is usually good enough for most users. To control how the connections with the broker are managed, implement a custom connection manager by inheriting from IManageRabbitMqConnections. This requires that connections be provided for:

  1. Administrative actions like creating queues and exchanges.
  2. Publishing messages to the broker.
  3. Consuming messages from the broker.

In order for the transport to use the above, register it as shown below:

var transport = busConfiguration.UseTransport<RabbitMQTransport>();
transport.UseConnectionManager<MyConnectionManager>();

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.

TimeToWaitBeforeTriggering

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)

<appSettings>
  <add key="NServiceBus/RabbitMqDequeueStrategy/TimeToWaitBeforeTriggering"
       value="00:02:00"/>
</appSettings>

DelayAfterFailure

Controls the amount of time the transport waits after a failure is detected before trying to poll for incoming messages again.

Type: System.TimeSpan

Default: 00:00:05 (5 seconds)

<appSettings>
  <add key="NServiceBus/RabbitMqDequeueStrategy/DelayAfterFailure"
       value="00:00:05"/>
</appSettings>

Last modified