The RabbitMQ transport requires a connection string to connect to the RabbitMQ broker, and there are two different styles to choose from. It can accept the standard AMQP URI connection strings, and it also can use a custom format that is documented below.
Specifying the connection string via code
To specify the connection string in code:
endpointConfiguration.UseTransport(
new RabbitMQTransport(Topology.Conventional, "My custom connection string"));
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.
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 heartbeats between the endpoint and the broker.
Default: 60
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
CertPath
The file path to the client authentication certificate when using TLS.
CertPassphrase
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:
host=broker1;UseTls=true
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.
Here is a sample connection string using these settings:
host=broker1;UseTls=true;CertPath=C:\CertificatePath\ssl.pfx;CertPassphrase=securePassword
Client certificates can also be specified via code instead of using the connection string:
var transport = new RabbitMQTransport(Topology.Conventional, "host=localhost")
{
ClientCertificate = new X509Certificate2()
};
endpointConfiguration.UseTransport(transport);
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 NServiceBus.RabbitMQ versions 4.4 and above, this validation can be disabled with the following setting:
var transport = new RabbitMQTransport(Topology.Conventional, "host=localhost")
{
ValidateRemoteCertificate = false
};
endpointConfiguration.UseTransport(transport);
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 = new RabbitMQTransport(Topology.Conventional, "host=localhost")
{
UseExternalAuthMechanism = true
};
endpointConfiguration.UseTransport(transport);
Controlling the prefetch count
When consuming messages from the broker, throughput can be improved by having the consumer prefetch additional messages. By default, the prefetch count is calculated by multiplying maximum concurrency by the prefetch multiplier of 3. The default prefetch count calculation can be overridden with a custom algorithm. The configured concurrency setting is passed as an input to the calculation function.
var transport = new RabbitMQTransport(Topology.Conventional, "host=localhost")
{
PrefetchCountCalculation = concurrency => concurrency * 4
};
endpointConfiguration.UseTransport(transport);
Alternatively, the whole calculation can be overridden by setting the prefetch count directly using the following:
var transport = new RabbitMQTransport(Topology.Conventional, "host=localhost")
{
PrefetchCountCalculation = _ => 100
};
endpointConfiguration.UseTransport(transport);
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.
Heartbeat interval
Controls how frequently AMQP heartbeat messages will be sent between the endpoint and the broker.
Type: System.
Default: 00:01:00
(1 minute)
var transport = new RabbitMQTransport(Topology.Conventional, "host=localhost")
{
HeartbeatInterval = TimeSpan.FromSeconds(30)
};
endpointConfiguration.UseTransport(transport);
Network recovery interval
Controls the time to wait between attempts to reconnect to the broker if the connection is lost.
Type: System.
Default: 00:00:10
(10 seconds)
var transport = new RabbitMQTransport(Topology.Conventional, "host=localhost")
{
NetworkRecoveryInterval = TimeSpan.FromSeconds(30)
};
endpointConfiguration.UseTransport(transport);
TimeToWaitBeforeTriggering
Controls the amount of time the transport waits after a failure is detected before triggering the critical error action.
Type: System.
Default: 00:02:00
(2 minutes)
var transport = new RabbitMQTransport(Topology.Conventional, "host=localhost")
{
TimeToWaitBeforeTriggeringCircuitBreaker = TimeSpan.FromMinutes(2)
};
endpointConfiguration.UseTransport(transport);
Debugging recommendations
For debugging purposes, it can be helpful to increase the heartbeat interval via the connection string:
var transport = new RabbitMQTransport(Topology.Conventional, "host=broker1;RequestedHeartbeat=600")
{
ClientCertificate = new X509Certificate2()
};
endpointConfiguration.UseTransport(transport);
Or via the API:
var transport = new RabbitMQTransport(Topology.Conventional, "host=localhost")
{
HeartbeatInterval = TimeSpan.FromMinutes(10)
};
endpointConfiguration.UseTransport(transport);
Increasing this setting can help to avoid connection timeouts while debugging.