public class ConnectionFactory

Summary

Main entry point to the RabbitMQ .NET AMQP client API. Constructs instances.

Remarks

A simple example of connecting to a broker:

                 IConnectionFactory 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;
                 //
                 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.Uri = "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 trailling slash) also represent the default virtual host. The latter issue means that virtual hosts with an empty name are not addressable.

Field Summary

Flags Type Name Summary
public IList<AuthMechanismFactory> AuthMechanisms

SASL auth mechanisms to use.

public bool AutomaticRecoveryEnabled

Set to true to enable automatic connection recovery.

public initonly static IList<AuthMechanismFactory> DefaultAuthMechanisms

Default SASL auth mechanisms to use.

public const ushort DefaultChannelMax

Default value for the desired maximum channel number, with zero meaning unlimited (value: 0).

public const int DefaultConnectionTimeout

Default value for connection attempt timeout, in milliseconds.

public const uint DefaultFrameMax

Default value for the desired maximum frame size, with zero meaning unlimited (value: 0).

public const ushort DefaultHeartbeat

Default value for desired heartbeat interval, in seconds, with zero meaning none (value: 60).

public const string DefaultPass

Default password (value: "guest").

public const string DefaultUser

Default user name (value: "guest").

public const string DefaultVHost

Default virtual host (value: "/").

public string HostName

The host to connect to.

public IHostnameSelector HostnameSelector

Used to select next hostname to try when performing connection recovery (re-connecting). Is not used for non-recovering connections.

public TimeSpan NetworkRecoveryInterval

Amount of time client will wait for before re-trying to recover connection.

public int Port

The port to connect on. indicates the default for the protocol should be used.

public IProtocol Protocol

Protocol used, only AMQP 0-9-1 is supported in modern versions.

public int RequestedConnectionTimeout

Timeout setting for connection attempts (in milliseconds).

public int SocketReadTimeout

Timeout setting for socket read operations (in milliseconds).

public int SocketWriteTimeout

Timeout setting for socket write operations (in milliseconds).

public SslOption Ssl

Ssl options setting.

public bool TopologyRecoveryEnabled

Set to true to make automatic connection recovery also recover topology (exchanges, queues, bindings, etc).

Property Summary

Flags Type Name Summary
public virtual final IDictionary<string,object> ClientProperties (rw)

Dictionary of client properties to be sent to the server.

public virtual final TimeSpan ContinuationTimeout (rw)

Amount of time protocol operations (e.g. queue.declare) are allowed to take before timing out.

public AmqpTcpEndpoint Endpoint (rw)

Connection endpoint.

public virtual final TimeSpan HandshakeContinuationTimeout (rw)

Amount of time protocol handshake operations are allowed to take before timing out.

public virtual final string Password (rw)

Password to use when authenticating to the server.

public virtual final ushort RequestedChannelMax (rw)

Maximum channel number to ask for.

public virtual final uint RequestedFrameMax (rw)

Frame-max parameter to ask for (in bytes).

public virtual final ushort RequestedHeartbeat (rw)

Heartbeat timeout to use when negotiating with the server (in seconds).

public virtual final TaskScheduler TaskScheduler (rw)

Task scheduler connections created by this factory will use when dispatching consumer operations, such as message deliveries.

public Uri uri (w)

Set connection parameters using the amqp or amqps scheme.

public string Uri (w)

Set connection parameters using the amqp or amqps scheme.

public virtual final bool UseBackgroundThreadsForIO (rw)

When set to true, background thread will be used for the I/O loop.

public virtual final string UserName (rw)

Username to use when authenticating to the server.

public virtual final string VirtualHost (rw)

Virtual host to access during this connection.

Constructor Summary

Flags Name Summary
public ConnectionFactory()

Construct a fresh instance, with all fields set to their respective defaults.

Method Summary

Flags Name Summary
public virtual final AuthMechanismFactory AuthMechanismFactory(IList<string> mechanismNames)

Given a list of mechanism names supported by the server, select a preferred mechanism, or null if we have none in common.

public IConnection CreateConnection(IList<AmqpTcpEndpoint> endpoints, string clientProvidedName)

Create a connection using a list of hostnames. The first reachable hostname will be used initially. Subsequent hostname picks are determined by the configured.

public IConnection CreateConnection(IList<AmqpTcpEndpoint> endpoints)

Create a connection using a list of hostnames. The first reachable hostname will be used initially. Subsequent hostname picks are determined by the configured.

public virtual final IConnection CreateConnection(IList<string> hostnames, string clientProvidedName)

Create a connection using a list of hostnames. The first reachable hostname will be used initially. Subsequent hostname picks are determined by the configured.

public virtual final IConnection CreateConnection(IList<string> hostnames)

Create a connection using a list of hostnames. The first reachable hostname will be used initially. Subsequent hostname picks are determined by the configured.

public virtual final IConnection CreateConnection(string clientProvidedName)

Create a connection to the specified endpoint.

public virtual IConnection CreateConnection()

Create a connection to the specified endpoint.

public IFrameHandler CreateFrameHandler()

(undocumented)

public IFrameHandler CreateFrameHandler(AmqpTcpEndpoint endpoint)

(undocumented)

public IFrameHandler CreateFrameHandlerForHostname(string hostname)

(undocumented)

Field Detail

public IList<AuthMechanismFactory> AuthMechanisms

Summary

SASL auth mechanisms to use.

public bool AutomaticRecoveryEnabled

Summary

Set to true to enable automatic connection recovery.

public initonly static IList<AuthMechanismFactory> DefaultAuthMechanisms

Summary

Default SASL auth mechanisms to use.

public const ushort DefaultChannelMax

Summary

Default value for the desired maximum channel number, with zero meaning unlimited (value: 0).

Remarks

PLEASE KEEP THIS MATCHING THE DOC ABOVE.

public const int DefaultConnectionTimeout

Summary

Default value for connection attempt timeout, in milliseconds.

public const uint DefaultFrameMax

Summary

Default value for the desired maximum frame size, with zero meaning unlimited (value: 0).

Remarks

PLEASE KEEP THIS MATCHING THE DOC ABOVE.

public const ushort DefaultHeartbeat

Summary

Default value for desired heartbeat interval, in seconds, with zero meaning none (value: 60).

Remarks

PLEASE KEEP THIS MATCHING THE DOC ABOVE.

public const string DefaultPass

Summary

Default password (value: "guest").

Remarks

PLEASE KEEP THIS MATCHING THE DOC ABOVE.

public const string DefaultUser

Summary

Default user name (value: "guest").

Remarks

PLEASE KEEP THIS MATCHING THE DOC ABOVE.

public const string DefaultVHost

Summary

Default virtual host (value: "/").

Remarks

PLEASE KEEP THIS MATCHING THE DOC ABOVE.

public string HostName

Summary

The host to connect to.

public IHostnameSelector HostnameSelector

Summary

Used to select next hostname to try when performing connection recovery (re-connecting). Is not used for non-recovering connections.

public TimeSpan NetworkRecoveryInterval

Summary

Amount of time client will wait for before re-trying to recover connection.

public int Port

Summary

The port to connect on. indicates the default for the protocol should be used.

public IProtocol Protocol

Summary

Protocol used, only AMQP 0-9-1 is supported in modern versions.

public int RequestedConnectionTimeout

Summary

Timeout setting for connection attempts (in milliseconds).

public int SocketReadTimeout

Summary

Timeout setting for socket read operations (in milliseconds).

public int SocketWriteTimeout

Summary

Timeout setting for socket write operations (in milliseconds).

public SslOption Ssl

Summary

Ssl options setting.

public bool TopologyRecoveryEnabled

Summary

Set to true to make automatic connection recovery also recover topology (exchanges, queues, bindings, etc).

Property Detail

public virtual final IDictionary<string,object> ClientProperties (rw)

Summary

Dictionary of client properties to be sent to the server.

public virtual final TimeSpan ContinuationTimeout (rw)

Summary

Amount of time protocol operations (e.g.
queue.declare
) are allowed to take before timing out.

public AmqpTcpEndpoint Endpoint (rw)

Summary

Connection endpoint.

public virtual final TimeSpan HandshakeContinuationTimeout (rw)

Summary

Amount of time protocol handshake operations are allowed to take before timing out.

public virtual final string Password (rw)

Summary

Password to use when authenticating to the server.

public virtual final ushort RequestedChannelMax (rw)

Summary

Maximum channel number to ask for.

public virtual final uint RequestedFrameMax (rw)

Summary

Frame-max parameter to ask for (in bytes).

public virtual final ushort RequestedHeartbeat (rw)

Summary

Heartbeat timeout to use when negotiating with the server (in seconds).

public virtual final TaskScheduler TaskScheduler (rw)

Summary

Task scheduler connections created by this factory will use when dispatching consumer operations, such as message deliveries.

public Uri uri (w)

Summary

Set connection parameters using the amqp or amqps scheme.

public string Uri (w)

Summary

Set connection parameters using the amqp or amqps scheme.

public virtual final bool UseBackgroundThreadsForIO (rw)

Summary

When set to true, background thread will be used for the I/O loop.

public virtual final string UserName (rw)

Summary

Username to use when authenticating to the server.

public virtual final string VirtualHost (rw)

Summary

Virtual host to access during this connection.

Constructor Detail

ConnectionFactory

public ConnectionFactory()

Summary

Construct a fresh instance, with all fields set to their respective defaults.

Method Detail

AuthMechanismFactory

public virtual final AuthMechanismFactory AuthMechanismFactory(IList<string> mechanismNames)

Flags public virtual final
Return type AuthMechanismFactory
Parameters
Name Type
mechanismNames IList<string>

Summary

Given a list of mechanism names supported by the server, select a preferred mechanism, or null if we have none in common.

CreateConnection

public IConnection CreateConnection(IList<AmqpTcpEndpoint> endpoints, string clientProvidedName)

Flags public
Return type IConnection
Parameters
Name Type
endpoints IList<AmqpTcpEndpoint>
clientProvidedName string

Summary

Create a connection using a list of hostnames. The first reachable hostname will be used initially. Subsequent hostname picks are determined by the configured.

Param

List of endpoints to use for the initial connection and recovery.

Param

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

Open connection

Exception

When no hostname was reachable.

CreateConnection

public IConnection CreateConnection(IList<AmqpTcpEndpoint> endpoints)

Flags public
Return type IConnection
Parameters
Name Type
endpoints IList<AmqpTcpEndpoint>

Summary

Create a connection using a list of hostnames. The first reachable hostname will be used initially. Subsequent hostname picks are determined by the configured.

Param

List of endpoints to use for the initial connection and recovery.

Returns

Open connection

Exception

When no hostname was reachable.

CreateConnection

public virtual final IConnection CreateConnection(IList<string> hostnames, string clientProvidedName)

Flags public virtual final
Return type IConnection
Parameters
Name Type
hostnames IList<string>
clientProvidedName string

Summary

Create a connection using a list of hostnames. The first reachable hostname will be used initially. Subsequent hostname picks are determined by the configured.

Param

List of hostnames to use for the initial connection and recovery.

Param

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

Open connection

Exception

When no hostname was reachable.

CreateConnection

public virtual final IConnection CreateConnection(IList<string> hostnames)

Flags public virtual final
Return type IConnection
Parameters
Name Type
hostnames IList<string>

Summary

Create a connection using a list of hostnames. The first reachable hostname will be used initially. Subsequent hostname picks are determined by the configured.

Param

List of hostnames to use for the initial connection and recovery.

Returns

Open connection

Exception

When no hostname was reachable.

CreateConnection

public virtual final IConnection CreateConnection(string clientProvidedName)

Flags public virtual final
Return type IConnection
Parameters
Name Type
clientProvidedName string

Summary

Create a connection to the specified endpoint.

Param

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.

Exception

When the configured hostname was not reachable.

CreateConnection

public virtual IConnection CreateConnection()

Flags public virtual
Return type IConnection

Summary

Create a connection to the specified endpoint.

Exception

When the configured hostname was not reachable.

CreateFrameHandler

public IFrameHandler CreateFrameHandler()

Flags public
Return type IFrameHandler

CreateFrameHandler

public IFrameHandler CreateFrameHandler(AmqpTcpEndpoint endpoint)

Flags public
Return type IFrameHandler
Parameters
Name Type
endpoint AmqpTcpEndpoint

CreateFrameHandlerForHostname

public IFrameHandler CreateFrameHandlerForHostname(string hostname)

Flags public
Return type IFrameHandler
Parameters
Name Type
hostname string