Class ConnectionFactory

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

Inheritance

System.Object

ConnectionFactoryBase

ConnectionFactory

Implements

IAsyncConnectionFactory

IConnectionFactory

Inherited Members

ConnectionFactoryBase.SocketFactory

ConnectionFactoryBase.DefaultSocketFactory(AddressFamily)

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

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;
    //
    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

| Improve this Doc View Source

ConnectionFactory()

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

Declaration

public ConnectionFactory()

Fields

| Improve this Doc View Source

DefaultAuthMechanisms

Default SASL auth mechanisms to use.

Declaration

public static readonly IList<IAuthMechanismFactory> DefaultAuthMechanisms

Field Value

Type	Description
System.Collections.Generic.IList<IAuthMechanismFactory>

| Improve this Doc View Source

DefaultChannelMax

Default value for the desired maximum channel number. Default: 2047.

Declaration

public const ushort DefaultChannelMax = 2047

Field Value

Type	Description
System.UInt16

| Improve this Doc View Source

DefaultConnectionTimeout

Default value for connection attempt timeout.

Declaration

public static readonly TimeSpan DefaultConnectionTimeout

Field Value

Type	Description
System.TimeSpan

| Improve this Doc View Source

DefaultFrameMax

Default value for the desired maximum frame size. Default is 0 ("no limit").

Declaration

public const uint DefaultFrameMax = 0U

Field Value

Type	Description
System.UInt32

| Improve this Doc View Source

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
System.TimeSpan

| Improve this Doc View Source

DefaultPass

Default password (value: "guest").

Declaration

public const string DefaultPass = "guest"

Field Value

Type	Description
System.String

| Improve this Doc View Source

DefaultUser

Default user name (value: "guest").

Declaration

public const string DefaultUser = "guest"

Field Value

Type	Description
System.String

| Improve this Doc View Source

DefaultVHost

Default virtual host (value: "/").

Declaration

public const string DefaultVHost = "/"

Field Value

Type	Description
System.String

Properties

| Improve this Doc View Source

AmqpUriSslProtocols

The AMQP URI SSL protocols.

Declaration

public SslProtocols AmqpUriSslProtocols { get; set; }

Property Value

Type	Description
System.Security.Authentication.SslProtocols

| Improve this Doc View Source

AuthMechanisms

SASL auth mechanisms to use.

Declaration

public IList<IAuthMechanismFactory> AuthMechanisms { get; set; }

Property Value

Type	Description
System.Collections.Generic.IList<IAuthMechanismFactory>

| Improve this Doc View Source

AutomaticRecoveryEnabled

Set to false to disable automatic connection recovery. Defaults to true.

Declaration

public bool AutomaticRecoveryEnabled { get; set; }

Property Value

Type	Description
System.Boolean

| Improve this Doc View Source

ClientProperties

Dictionary of client properties to be sent to the server.

Declaration

public IDictionary<string, object> ClientProperties { get; set; }

Property Value

Type	Description
System.Collections.Generic.IDictionary<System.String, System.Object>

| Improve this Doc View Source

ClientProvidedName

Default client provided name to be used for connections.

Declaration

public string ClientProvidedName { get; set; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

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
System.Int32

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.

| Improve this Doc View Source

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
System.TimeSpan

| Improve this Doc View Source

DefaultAddressFamily

Address family used by default. Use System.Net.Sockets.AddressFamily.InterNetwork to force to IPv4. Use System.Net.Sockets.AddressFamily.InterNetworkV6 to force to IPv6. Or use System.Net.Sockets.AddressFamily.Unknown to attempt both IPv6 and IPv4.

Declaration

public static AddressFamily DefaultAddressFamily { get; set; }

Property Value

Type	Description
System.Net.Sockets.AddressFamily

| Improve this Doc View Source

DefaultAmqpUriSslProtocols

TLS versions enabled by default: TLSv1.2, v1.1, v1.0.

Declaration

public static SslProtocols DefaultAmqpUriSslProtocols { get; set; }

Property Value

Type	Description
System.Security.Authentication.SslProtocols

| Improve this Doc View Source

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
System.Boolean

| Improve this Doc View Source

Endpoint

Connection endpoint.

Declaration

public AmqpTcpEndpoint Endpoint { get; set; }

Property Value

Type	Description
AmqpTcpEndpoint

| Improve this Doc View Source

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
System.Func<System.Collections.Generic.IEnumerable<AmqpTcpEndpoint>, IEndpointResolver>

| Improve this Doc View Source

HandshakeContinuationTimeout

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

Declaration

public TimeSpan HandshakeContinuationTimeout { get; set; }

Property Value

Type	Description
System.TimeSpan

| Improve this Doc View Source

HostName

The host to connect to.

Declaration

public string HostName { get; set; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

NetworkRecoveryInterval

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

Declaration

public TimeSpan NetworkRecoveryInterval { get; set; }

Property Value

Type	Description
System.TimeSpan

| Improve this Doc View Source

Password

Password to use when authenticating to the server.

Declaration

public string Password { get; set; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

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
System.Int32

| Improve this Doc View Source

RequestedChannelMax

Maximum channel number to ask for.

Declaration

public ushort RequestedChannelMax { get; set; }

Property Value

Type	Description
System.UInt16

| Improve this Doc View Source

RequestedConnectionTimeout

Timeout setting for connection attempts.

Declaration

public TimeSpan RequestedConnectionTimeout { get; set; }

Property Value

Type	Description
System.TimeSpan

| Improve this Doc View Source

RequestedFrameMax

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

Declaration

public uint RequestedFrameMax { get; set; }

Property Value

Type	Description
System.UInt32

| Improve this Doc View Source

RequestedHeartbeat

Heartbeat timeout to use when negotiating with the server.

Declaration

public TimeSpan RequestedHeartbeat { get; set; }

Property Value

Type	Description
System.TimeSpan

| Improve this Doc View Source

SocketReadTimeout

Timeout setting for socket read operations.

Declaration

public TimeSpan SocketReadTimeout { get; set; }

Property Value

Type	Description
System.TimeSpan

| Improve this Doc View Source

SocketWriteTimeout

Timeout setting for socket write operations.

Declaration

public TimeSpan SocketWriteTimeout { get; set; }

Property Value

Type	Description
System.TimeSpan

| Improve this Doc View Source

Ssl

TLS options setting.

Declaration

public SslOption Ssl { get; set; }

Property Value

Type	Description
SslOption

| Improve this Doc View Source

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
System.Boolean

| Improve this Doc View Source

Uri

The uri to use for the connection.

Declaration

public Uri Uri { get; set; }

Property Value

Type	Description
System.Uri

| Improve this Doc View Source

UseBackgroundThreadsForIO

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

Declaration

public bool UseBackgroundThreadsForIO { get; set; }

Property Value

Type	Description
System.Boolean

| Improve this Doc View Source

UserName

Username to use when authenticating to the server.

Declaration

public string UserName { get; set; }

Property Value

Type	Description
System.String

| Improve this Doc View Source

VirtualHost

Virtual host to access during this connection.

Declaration

public string VirtualHost { get; set; }

Property Value

Type	Description
System.String

Methods

| Improve this Doc View Source

AuthMechanismFactory(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
System.Collections.Generic.IList<System.String>	mechanismNames

Returns

Type	Description
IAuthMechanismFactory

| Improve this Doc View Source

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.

| Improve this Doc View Source

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.
System.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.

| Improve this Doc View Source

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
System.Collections.Generic.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.

| Improve this Doc View Source

CreateConnection(IList<AmqpTcpEndpoint>, String)

Declaration

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

Parameters

Type	Name	Description
System.Collections.Generic.IList<AmqpTcpEndpoint>	endpoints	List of endpoints to use for the initial connection and recovery.
System.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.

| Improve this Doc View Source

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
System.Collections.Generic.IList<System.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.

| Improve this Doc View Source

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
System.Collections.Generic.IList<System.String>	hostnames	List of hostnames to use for the initial connection and recovery.
System.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.

| Improve this Doc View Source

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
System.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.

Implements

IAsyncConnectionFactory

IConnectionFactory