Class ConnectionFactory
Main entry point to the RabbitMQ .NET AMQP client API. Constructs IConnection instances.
Inherited Members
Namespace: RabbitMQ.Client
Assembly: RabbitMQ.Client.dll
Syntax
public sealed class ConnectionFactory : ConnectionFactoryBase, IAsyncConnectionFactory, IConnectionFactory
Remarks
A simple example of connecting to a broker:
ConnectionFactory factory = new ConnectionFactory();
//
// The next six lines are optional:
factory.UserName = ConnectionFactory.DefaultUser;
factory.Password = ConnectionFactory.DefaultPass;
factory.VirtualHost = ConnectionFactory.DefaultVHost;
factory.HostName = hostName;
factory.Port = AmqpTcpEndpoint.UseDefaultPort;
factory.MaxMessageSize = 512 * 1024 * 1024;
//
IConnection conn = factory.CreateConnection();
//
IModel ch = conn.CreateModel();
//
// ... use ch's IModel methods ...
//
ch.Close(Constants.ReplySuccess, "Closing the channel");
conn.Close(Constants.ReplySuccess, "Closing the connection");
The same example, written more compactly with AMQP URIs:
ConnectionFactory factory = new ConnectionFactory();
factory.SetUri("amqp://localhost");
IConnection conn = factory.CreateConnection();
...
Please see also the API overview and tutorial in the User Guide.
Note that the Uri property takes a string representation of an AMQP URI. Omitted URI parts will take default values. The host part of the URI cannot be omitted and URIs of the form "amqp://foo/" (note the trailing slash) also represent the default virtual host. The latter issue means that virtual hosts with an empty name are not addressable.
Constructors
| Edit this page View SourceConnectionFactory()
Construct a fresh instance, with all fields set to their respective defaults.
Declaration
public ConnectionFactory()
Fields
| Edit this page View SourceDefaultAuthMechanisms
Default SASL auth mechanisms to use.
Declaration
public static readonly IList<IAuthMechanismFactory> DefaultAuthMechanisms
Field Value
Type | Description |
---|---|
IList<IAuthMechanismFactory> |
DefaultChannelMax
Default value for the desired maximum channel number. Default: 2047.
Declaration
public const ushort DefaultChannelMax = 2047
Field Value
Type | Description |
---|---|
ushort |
DefaultConnectionTimeout
Default value for connection attempt timeout.
Declaration
public static readonly TimeSpan DefaultConnectionTimeout
Field Value
Type | Description |
---|---|
TimeSpan |
DefaultFrameMax
Default value for the desired maximum frame size. Default is 0 ("no limit").
Declaration
public const uint DefaultFrameMax = 0
Field Value
Type | Description |
---|---|
uint |
DefaultHeartbeat
Default value for desired heartbeat interval. Default is 60 seconds, TimeSpan.Zero means "heartbeats are disabled".
Declaration
public static readonly TimeSpan DefaultHeartbeat
Field Value
Type | Description |
---|---|
TimeSpan |
DefaultMaxMessageSize
Default value for the maximum allowed message size, in bytes, from RabbitMQ. Corresponds to the
rabbit.max_message_size
setting.
Note: the default is 0 which means "unlimited".
Declaration
public const uint DefaultMaxMessageSize = 0
Field Value
Type | Description |
---|---|
uint |
DefaultPass
Default password (value: "guest").
Declaration
public const string DefaultPass = "guest"
Field Value
Type | Description |
---|---|
string |
DefaultUser
Default user name (value: "guest").
Declaration
public const string DefaultUser = "guest"
Field Value
Type | Description |
---|---|
string |
DefaultVHost
Default virtual host (value: "/").
Declaration
public const string DefaultVHost = "/"
Field Value
Type | Description |
---|---|
string |
Properties
| Edit this page View SourceAmqpUriSslProtocols
The AMQP URI SSL protocols.
Declaration
public SslProtocols AmqpUriSslProtocols { get; set; }
Property Value
Type | Description |
---|---|
SslProtocols |
AuthMechanisms
SASL auth mechanisms to use.
Declaration
public IList<IAuthMechanismFactory> AuthMechanisms { get; set; }
Property Value
Type | Description |
---|---|
IList<IAuthMechanismFactory> |
AutomaticRecoveryEnabled
Set to false to disable automatic connection recovery. Defaults to true.
Declaration
public bool AutomaticRecoveryEnabled { get; set; }
Property Value
Type | Description |
---|---|
bool |
ClientProperties
Dictionary of client properties to be sent to the server.
Declaration
public IDictionary<string, object> ClientProperties { get; set; }
Property Value
Type | Description |
---|---|
IDictionary<string, object> |
ClientProvidedName
Default client provided name to be used for connections.
Declaration
public string ClientProvidedName { get; set; }
Property Value
Type | Description |
---|---|
string |
ConsumerDispatchConcurrency
Set to a value greater than one to enable concurrent processing. For a concurrency greater than one IBasicConsumer will be offloaded to the worker thread pool so it is important to choose the value for the concurrency wisely to avoid thread pool overloading. IAsyncBasicConsumer can handle concurrency much more efficiently due to the non-blocking nature of the consumer. Defaults to 1.
Declaration
public int ConsumerDispatchConcurrency { get; set; }
Property Value
Type | Description |
---|---|
int |
Remarks
For concurrency greater than one this removes the guarantee that consumers handle messages in the order they receive them. In addition to that consumers need to be thread/concurrency safe.
ContinuationTimeout
Amount of time protocol operations (e.g.
queue.declare
) are allowed to take before
timing out.
Declaration
public TimeSpan ContinuationTimeout { get; set; }
Property Value
Type | Description |
---|---|
TimeSpan |
CredentialsProvider
CredentialsProvider and CredentialsRefresher implementations. If set, these overrides UserName / Password
Declaration
public ICredentialsProvider CredentialsProvider { get; set; }
Property Value
Type | Description |
---|---|
ICredentialsProvider |
CredentialsRefresher
Declaration
public ICredentialsRefresher CredentialsRefresher { get; set; }
Property Value
Type | Description |
---|---|
ICredentialsRefresher |
DefaultAddressFamily
Address family used by default. Use InterNetwork to force to IPv4. Use InterNetworkV6 to force to IPv6. Or use Unknown to attempt both IPv6 and IPv4.
Declaration
public static AddressFamily DefaultAddressFamily { get; set; }
Property Value
Type | Description |
---|---|
AddressFamily |
DefaultAmqpUriSslProtocols
TLS versions enabled by default: TLSv1.2, v1.1, v1.0.
Declaration
public static SslProtocols DefaultAmqpUriSslProtocols { get; set; }
Property Value
Type | Description |
---|---|
SslProtocols |
DispatchConsumersAsync
Set to true will enable a asynchronous consumer dispatcher which is compatible with IAsyncBasicConsumer. Defaults to false.
Declaration
public bool DispatchConsumersAsync { get; set; }
Property Value
Type | Description |
---|---|
bool |
Endpoint
Connection endpoint.
Declaration
public AmqpTcpEndpoint Endpoint { get; set; }
Property Value
Type | Description |
---|---|
AmqpTcpEndpoint |
EndpointResolverFactory
Factory function for creating the IEndpointResolver used to generate a list of endpoints for the ConnectionFactory to try in order. The default value creates an instance of the DefaultEndpointResolver using the list of endpoints passed in. The DefaultEndpointResolver shuffles the provided list each time it is requested.
Declaration
public Func<IEnumerable<AmqpTcpEndpoint>, IEndpointResolver> EndpointResolverFactory { get; set; }
Property Value
Type | Description |
---|---|
Func<IEnumerable<AmqpTcpEndpoint>, IEndpointResolver> |
HandshakeContinuationTimeout
Amount of time protocol handshake operations are allowed to take before timing out.
Declaration
public TimeSpan HandshakeContinuationTimeout { get; set; }
Property Value
Type | Description |
---|---|
TimeSpan |
HostName
The host to connect to.
Declaration
public string HostName { get; set; }
Property Value
Type | Description |
---|---|
string |
MaxMessageSize
Maximum allowed message size, in bytes, from RabbitMQ. Corresponds to the
rabbit.max_message_size
setting.
Declaration
public uint MaxMessageSize { get; set; }
Property Value
Type | Description |
---|---|
uint |
MemoryPool
The memory pool used for allocating buffers. Default is Shared.
Declaration
public ArrayPool<byte> MemoryPool { get; set; }
Property Value
Type | Description |
---|---|
ArrayPool<byte> |
NetworkRecoveryInterval
Amount of time client will wait for before re-trying to recover connection.
Declaration
public TimeSpan NetworkRecoveryInterval { get; set; }
Property Value
Type | Description |
---|---|
TimeSpan |
Password
Password to use when authenticating to the server.
Declaration
public string Password { get; set; }
Property Value
Type | Description |
---|---|
string |
Port
The port to connect on. UseDefaultPort indicates the default for the protocol should be used.
Declaration
public int Port { get; set; }
Property Value
Type | Description |
---|---|
int |
RequestedChannelMax
Maximum channel number to ask for.
Declaration
public ushort RequestedChannelMax { get; set; }
Property Value
Type | Description |
---|---|
ushort |
RequestedConnectionTimeout
Timeout setting for connection attempts.
Declaration
public TimeSpan RequestedConnectionTimeout { get; set; }
Property Value
Type | Description |
---|---|
TimeSpan |
RequestedFrameMax
Frame-max parameter to ask for (in bytes).
Declaration
public uint RequestedFrameMax { get; set; }
Property Value
Type | Description |
---|---|
uint |
RequestedHeartbeat
Heartbeat timeout to use when negotiating with the server.
Declaration
public TimeSpan RequestedHeartbeat { get; set; }
Property Value
Type | Description |
---|---|
TimeSpan |
SocketReadTimeout
Timeout setting for socket read operations.
Declaration
public TimeSpan SocketReadTimeout { get; set; }
Property Value
Type | Description |
---|---|
TimeSpan |
SocketWriteTimeout
Timeout setting for socket write operations.
Declaration
public TimeSpan SocketWriteTimeout { get; set; }
Property Value
Type | Description |
---|---|
TimeSpan |
Ssl
TLS options setting.
Declaration
public SslOption Ssl { get; set; }
Property Value
Type | Description |
---|---|
SslOption |
TopologyRecoveryEnabled
Set to false to make automatic connection recovery not recover topology (exchanges, queues, bindings, etc). Defaults to true.
Declaration
public bool TopologyRecoveryEnabled { get; set; }
Property Value
Type | Description |
---|---|
bool |
TopologyRecoveryExceptionHandler
Custom logic for handling topology recovery exceptions that match the specified filters.
Declaration
public TopologyRecoveryExceptionHandler TopologyRecoveryExceptionHandler { get; set; }
Property Value
Type | Description |
---|---|
TopologyRecoveryExceptionHandler |
TopologyRecoveryFilter
Filter to include/exclude entities from topology recovery. Default filter includes all entities in topology recovery.
Declaration
public TopologyRecoveryFilter TopologyRecoveryFilter { get; set; }
Property Value
Type | Description |
---|---|
TopologyRecoveryFilter |
Uri
The uri to use for the connection.
Declaration
public Uri Uri { get; set; }
Property Value
Type | Description |
---|---|
Uri |
UseBackgroundThreadsForIO
When set to true, background thread will be used for the I/O loop. NB: No-op
Declaration
[Obsolete("Currently a no-op. UseBackgroundThreadsForIO will be removed in version 7")]
public bool UseBackgroundThreadsForIO { get; set; }
Property Value
Type | Description |
---|---|
bool |
UserName
Username to use when authenticating to the server.
Declaration
public string UserName { get; set; }
Property Value
Type | Description |
---|---|
string |
VirtualHost
Virtual host to access during this connection.
Declaration
public string VirtualHost { get; set; }
Property Value
Type | Description |
---|---|
string |
Methods
| Edit this page View SourceAuthMechanismFactory(IList<string>)
Given a list of mechanism names supported by the server, select a preferred mechanism, or null if we have none in common.
Declaration
public IAuthMechanismFactory AuthMechanismFactory(IList<string> mechanismNames)
Parameters
Type | Name | Description |
---|---|---|
IList<string> | mechanismNames |
Returns
Type | Description |
---|---|
IAuthMechanismFactory |
CreateConnection()
Create a connection to one of the endpoints provided by the IEndpointResolver returned by the EndpointResolverFactory. By default the configured hostname and port are used.
Declaration
public IConnection CreateConnection()
Returns
Type | Description |
---|---|
IConnection |
Exceptions
Type | Condition |
---|---|
BrokerUnreachableException | When the configured hostname was not reachable. |
CreateConnection(IEndpointResolver, string)
Create a connection using an IEndpointResolver.
Declaration
public IConnection CreateConnection(IEndpointResolver endpointResolver, string clientProvidedName)
Parameters
Type | Name | Description |
---|---|---|
IEndpointResolver | endpointResolver | The endpointResolver that returns the endpoints to use for the connection attempt. |
string | clientProvidedName | Application-specific connection name, will be displayed in the management UI if RabbitMQ server supports it. This value doesn't have to be unique and cannot be used as a connection identifier, e.g. in HTTP API requests. This value is supposed to be human-readable. |
Returns
Type | Description |
---|---|
IConnection | Open connection |
Exceptions
Type | Condition |
---|---|
BrokerUnreachableException | When no hostname was reachable. |
CreateConnection(IList<AmqpTcpEndpoint>)
Create a connection using a list of endpoints. By default each endpoint will be tried in a random order until a successful connection is found or the list is exhausted. The selection behaviour can be overridden by configuring the EndpointResolverFactory.
Declaration
public IConnection CreateConnection(IList<AmqpTcpEndpoint> endpoints)
Parameters
Type | Name | Description |
---|---|---|
IList<AmqpTcpEndpoint> | endpoints | List of endpoints to use for the initial connection and recovery. |
Returns
Type | Description |
---|---|
IConnection | Open connection |
Exceptions
Type | Condition |
---|---|
BrokerUnreachableException | When no hostname was reachable. |
CreateConnection(IList<AmqpTcpEndpoint>, string)
Create a connection using a list of endpoints. By default each endpoint will be tried in a random order until a successful connection is found or the list is exhausted. The selection behaviour can be overridden by configuring the EndpointResolverFactory.
Declaration
public IConnection CreateConnection(IList<AmqpTcpEndpoint> endpoints, string clientProvidedName)
Parameters
Type | Name | Description |
---|---|---|
IList<AmqpTcpEndpoint> | endpoints | List of endpoints to use for the initial connection and recovery. |
string | clientProvidedName | Application-specific connection name, will be displayed in the management UI if RabbitMQ server supports it. This value doesn't have to be unique and cannot be used as a connection identifier, e.g. in HTTP API requests. This value is supposed to be human-readable. |
Returns
Type | Description |
---|---|
IConnection | Open connection |
Exceptions
Type | Condition |
---|---|
BrokerUnreachableException | When no hostname was reachable. |
CreateConnection(IList<string>)
Create a connection using a list of hostnames using the configured port. By default each hostname is tried in a random order until a successful connection is found or the list is exhausted using the DefaultEndpointResolver. The selection behaviour can be overridden by configuring the EndpointResolverFactory.
Declaration
public IConnection CreateConnection(IList<string> hostnames)
Parameters
Type | Name | Description |
---|---|---|
IList<string> | hostnames | List of hostnames to use for the initial connection and recovery. |
Returns
Type | Description |
---|---|
IConnection | Open connection |
Exceptions
Type | Condition |
---|---|
BrokerUnreachableException | When no hostname was reachable. |
CreateConnection(IList<string>, string)
Create a connection using a list of hostnames using the configured port. By default each endpoint is tried in a random order until a successful connection is found or the list is exhausted. The selection behaviour can be overridden by configuring the EndpointResolverFactory.
Declaration
public IConnection CreateConnection(IList<string> hostnames, string clientProvidedName)
Parameters
Type | Name | Description |
---|---|---|
IList<string> | hostnames | List of hostnames to use for the initial connection and recovery. |
string | clientProvidedName | Application-specific connection name, will be displayed in the management UI if RabbitMQ server supports it. This value doesn't have to be unique and cannot be used as a connection identifier, e.g. in HTTP API requests. This value is supposed to be human-readable. |
Returns
Type | Description |
---|---|
IConnection | Open connection |
Exceptions
Type | Condition |
---|---|
BrokerUnreachableException | When no hostname was reachable. |
CreateConnection(string)
Create a connection to one of the endpoints provided by the IEndpointResolver returned by the EndpointResolverFactory. By default the configured hostname and port are used.
Declaration
public IConnection CreateConnection(string clientProvidedName)
Parameters
Type | Name | Description |
---|---|---|
string | clientProvidedName | Application-specific connection name, will be displayed in the management UI if RabbitMQ server supports it. This value doesn't have to be unique and cannot be used as a connection identifier, e.g. in HTTP API requests. This value is supposed to be human-readable. |
Returns
Type | Description |
---|---|
IConnection |
Exceptions
Type | Condition |
---|---|
BrokerUnreachableException | When the configured hostname was not reachable. |