Class ConnectionFactory

Namespace

RabbitMQ.Client

Assembly

RabbitMQ.Client.dll

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

public sealed class ConnectionFactory : ConnectionFactoryBase, IConnectionFactory

Inheritance

object

ConnectionFactoryBase

ConnectionFactory

Implements

IConnectionFactory

Inherited Members

ConnectionFactoryBase.SocketFactory

ConnectionFactoryBase.DefaultSocketFactory(AddressFamily)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A simple example of connecting to a broker:

ConnectionFactory factory = new ConnectionFactory();
  //
  // The next five lines are optional:
  factory.UserName = ConnectionFactory.DefaultUser;
  factory.Password = ConnectionFactory.DefaultPass;
  factory.VirtualHost = ConnectionFactory.DefaultVHost;
  factory.HostName = hostName;
  factory.Port     = AmqpTcpEndpoint.UseDefaultPort;
  factory.MaxInboundMessageBodySize = 512 * 1024 * 1024;
  //
  IConnection conn = factory.CreateConnection();
  //
  IChannel ch = conn.CreateChannel();
  //
  // ... use ch's IChannel 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 = new 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 trailing slash) also represent the default virtual host. The latter issue means that virtual hosts with an empty name are not addressable.

Constructors

ConnectionFactory()

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

public ConnectionFactory()

Fields

DefaultAuthMechanisms

Default SASL auth mechanisms to use.

public static readonly IEnumerable<IAuthMechanismFactory> DefaultAuthMechanisms

Field Value

IEnumerable<IAuthMechanismFactory>

DefaultChannelMax

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

public const ushort DefaultChannelMax = 2047

Field Value

ushort

DefaultConnectionTimeout

Default value for connection attempt timeout.

public static readonly TimeSpan DefaultConnectionTimeout

Field Value

TimeSpan

DefaultFrameMax

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

public const uint DefaultFrameMax = 0

Field Value

uint

DefaultHeartbeat

Default value for desired heartbeat interval. Default is 60 seconds, TimeSpan.Zero means "heartbeats are disabled".

public static readonly TimeSpan DefaultHeartbeat

Field Value

TimeSpan

DefaultMaxInboundMessageBodySize

Default value for

ConnectionFactory

's

MaxInboundMessageBodySize

.

public const uint DefaultMaxInboundMessageBodySize = 67108864

Field Value

uint

DefaultPass

Default password (value: "guest").

public const string DefaultPass = "guest"

Field Value

string

DefaultUser

Default user name (value: "guest").

public const string DefaultUser = "guest"

Field Value

string

DefaultVHost

Default virtual host (value: "/").

public const string DefaultVHost = "/"

Field Value

string

Properties

AmqpUriSslProtocols

The AMQP URI SSL protocols.

public SslProtocols AmqpUriSslProtocols { get; set; }

Property Value

SslProtocols

AuthMechanisms

SASL auth mechanisms to use.

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

Property Value

IEnumerable<IAuthMechanismFactory>

AutomaticRecoveryEnabled

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

public bool AutomaticRecoveryEnabled { get; set; }

Property Value

bool

ClientProperties

Dictionary of client properties to be sent to the server.

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

Property Value

IDictionary<string, object>

ClientProvidedName

Default client provided name to be used for connections.

public string? ClientProvidedName { get; set; }

Property Value

string

ConsumerDispatchConcurrency

Set to a value greater than one to enable concurrent processing. For a concurrency greater than one IAsyncBasicConsumer 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.

public ushort ConsumerDispatchConcurrency { get; set; }

Property Value

ushort

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.

public TimeSpan ContinuationTimeout { get; set; }

Property Value

TimeSpan

CredentialsProvider

ICredentialsProvider used to obtain username and password.

public ICredentialsProvider? CredentialsProvider { get; set; }

Property Value

ICredentialsProvider

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.

public static AddressFamily DefaultAddressFamily { get; set; }

Property Value

AddressFamily

DefaultAmqpUriSslProtocols

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

public static SslProtocols DefaultAmqpUriSslProtocols { get; set; }

Property Value

SslProtocols

Endpoint

Connection endpoint.

public AmqpTcpEndpoint Endpoint { get; set; }

Property Value

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.

public Func<IEnumerable<AmqpTcpEndpoint>, IEndpointResolver> EndpointResolverFactory { get; set; }

Property Value

Func<IEnumerable<AmqpTcpEndpoint>, IEndpointResolver>

HandshakeContinuationTimeout

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

public TimeSpan HandshakeContinuationTimeout { get; set; }

Property Value

TimeSpan

HostName

The host to connect to.

public string HostName { get; set; }

Property Value

string

MaxInboundMessageBodySize

Maximum allowed message size, in bytes, from RabbitMQ. Corresponds to the

ConnectionFactory.DefaultMaxMessageSize

setting.

public uint MaxInboundMessageBodySize { get; set; }

Property Value

uint

NetworkRecoveryInterval

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

public TimeSpan NetworkRecoveryInterval { get; set; }

Property Value

TimeSpan

Password

Password to use when authenticating to the server.

public string Password { get; set; }

Property Value

string

Port

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

public int Port { get; set; }

Property Value

int

RequestedChannelMax

Maximum channel number to ask for.

public ushort RequestedChannelMax { get; set; }

Property Value

ushort

RequestedConnectionTimeout

Timeout setting for connection attempts.

public TimeSpan RequestedConnectionTimeout { get; set; }

Property Value

TimeSpan

RequestedFrameMax

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

public uint RequestedFrameMax { get; set; }

Property Value

uint

RequestedHeartbeat

Heartbeat timeout to use when negotiating with the server.

public TimeSpan RequestedHeartbeat { get; set; }

Property Value

TimeSpan

SocketReadTimeout

Timeout setting for socket read operations.

public TimeSpan SocketReadTimeout { get; set; }

Property Value

TimeSpan

SocketWriteTimeout

Timeout setting for socket write operations.

public TimeSpan SocketWriteTimeout { get; set; }

Property Value

TimeSpan

Ssl

TLS options setting.

public SslOption Ssl { get; set; }

Property Value

SslOption

TopologyRecoveryEnabled

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

public bool TopologyRecoveryEnabled { get; set; }

Property Value

bool

TopologyRecoveryExceptionHandler

Custom logic for handling topology recovery exceptions that match the specified filters.

public TopologyRecoveryExceptionHandler TopologyRecoveryExceptionHandler { get; set; }

Property Value

TopologyRecoveryExceptionHandler

TopologyRecoveryFilter

Filter to include/exclude entities from topology recovery. Default filter includes all entities in topology recovery.

public TopologyRecoveryFilter TopologyRecoveryFilter { get; set; }

Property Value

TopologyRecoveryFilter

Uri

The uri to use for the connection.

public Uri Uri { get; set; }

Property Value

Uri

UserName

Username to use when authenticating to the server.

public string UserName { get; set; }

Property Value

string

VirtualHost

Virtual host to access during this connection.

public string VirtualHost { get; set; }

Property Value

string

Methods

AuthMechanismFactory(IEnumerable<string>)

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

public IAuthMechanismFactory? AuthMechanismFactory(IEnumerable<string> argServerMechanismNames)

Parameters

argServerMechanismNames IEnumerable<string>

Returns

IAuthMechanismFactory

CreateConnectionAsync(IEndpointResolver, string?, CancellationToken)

Asynchronously create a connection using an IEndpointResolver.

public Task<IConnection> CreateConnectionAsync(IEndpointResolver endpointResolver, string? clientProvidedName, CancellationToken cancellationToken = default)

Parameters

endpointResolver IEndpointResolver

The endpointResolver that returns the endpoints to use for the connection attempt.

clientProvidedName string

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.

cancellationToken CancellationToken

Cancellation token for this connection

Returns

Task<IConnection>

Open connection

Exceptions

BrokerUnreachableException

When no hostname was reachable.

CreateConnectionAsync(IEnumerable<AmqpTcpEndpoint>, string?, CancellationToken)

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

public Task<IConnection> CreateConnectionAsync(IEnumerable<AmqpTcpEndpoint> endpoints, string? clientProvidedName, CancellationToken cancellationToken = default)

Parameters

endpoints IEnumerable<AmqpTcpEndpoint>

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

clientProvidedName string

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.

cancellationToken CancellationToken

Cancellation token for this connection

Returns

Task<IConnection>

Open connection

Exceptions

BrokerUnreachableException

When no hostname was reachable.

CreateConnectionAsync(IEnumerable<AmqpTcpEndpoint>, CancellationToken)

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

public Task<IConnection> CreateConnectionAsync(IEnumerable<AmqpTcpEndpoint> endpoints, CancellationToken cancellationToken = default)

Parameters

endpoints IEnumerable<AmqpTcpEndpoint>

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

cancellationToken CancellationToken

Cancellation token for this connection

Returns

Task<IConnection>

Open connection

Exceptions

BrokerUnreachableException

When no hostname was reachable.

CreateConnectionAsync(IEnumerable<string>, string?, CancellationToken)

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

public Task<IConnection> CreateConnectionAsync(IEnumerable<string> hostnames, string? clientProvidedName, CancellationToken cancellationToken = default)

Parameters

hostnames IEnumerable<string>

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

clientProvidedName string

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.

cancellationToken CancellationToken

Cancellation token for this connection

Returns

Task<IConnection>

Open connection

Exceptions

BrokerUnreachableException

When no hostname was reachable.

CreateConnectionAsync(IEnumerable<string>, CancellationToken)

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

public Task<IConnection> CreateConnectionAsync(IEnumerable<string> hostnames, CancellationToken cancellationToken = default)

Parameters

hostnames IEnumerable<string>

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

cancellationToken CancellationToken

Cancellation token for this connection

Returns

Task<IConnection>

Open connection

Exceptions

BrokerUnreachableException

When no hostname was reachable.

CreateConnectionAsync(string?, CancellationToken)

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

public Task<IConnection> CreateConnectionAsync(string? clientProvidedName, CancellationToken cancellationToken = default)

Parameters

clientProvidedName string

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.

cancellationToken CancellationToken

Cancellation token for this connection

Returns

Task<IConnection>

Exceptions

BrokerUnreachableException

When the configured hostname was not reachable.

CreateConnectionAsync(CancellationToken)

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

public Task<IConnection> CreateConnectionAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token for this connection

Returns

Task<IConnection>

Exceptions

BrokerUnreachableException

When the configured hostname was not reachable.