Table of Contents

Interface IConnection

Namespace
RabbitMQ.Client
Assembly
RabbitMQ.Client.dll

Main interface to an AMQP connection.

public interface IConnection : INetworkConnection, IDisposable
Inherited Members

Remarks

Instances of IConnection are used to create fresh sessions/channels. The ConnectionFactory class is used to construct IConnection instances. Please see the documentation for ConnectionFactory for an example of usage. Alternatively, an API tutorial can be found in the User Guide.

Extends the IDisposable interface, so that the "using" statement can be used to scope the lifetime of a channel when appropriate.

Properties

ChannelMax

The maximum channel number this connection supports (0 if unlimited). Usable channel numbers range from 1 to this number, inclusive.

ushort ChannelMax { get; }

Property Value

ushort

ClientProperties

A copy of the client properties that has been sent to the server.

IDictionary<string, object> ClientProperties { get; }

Property Value

IDictionary<string, object>

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.

string ClientProvidedName { get; }

Property Value

string

CloseReason

Returns null if the connection is still in a state where it can be used, or the cause of its closure otherwise.

ShutdownEventArgs CloseReason { get; }

Property Value

ShutdownEventArgs

Remarks

Applications should use the ConnectionShutdown event to avoid race conditions. The scenario to avoid is checking CloseReason, seeing it is null (meaning the IConnection was available for use at the time of the check), and interpreting this mistakenly as a guarantee that the IConnection will remain usable for a time. Instead, the operation of interest should simply be attempted: if the IConnection is not in a usable state, an exception will be thrown (most likely OperationInterruptedException, but may vary depending on the particular operation being attempted).

Endpoint

Retrieve the endpoint this connection is connected to.

AmqpTcpEndpoint Endpoint { get; }

Property Value

AmqpTcpEndpoint

FrameMax

The maximum frame size this connection supports (0 if unlimited).

uint FrameMax { get; }

Property Value

uint

Heartbeat

The current heartbeat setting for this connection (System.TimeSpan.Zero for disabled).

TimeSpan Heartbeat { get; }

Property Value

TimeSpan

IsOpen

Returns true if the connection is still in a state where it can be used. Identical to checking if CloseReason equal null.

bool IsOpen { get; }

Property Value

bool

KnownHosts

Returns the known hosts that came back from the broker in the connection.open-ok method at connection startup time. Null until the connection is completely open and ready for use.

AmqpTcpEndpoint[] KnownHosts { get; }

Property Value

AmqpTcpEndpoint[]

Protocol

The IProtocol this connection is using to communicate with its peer.

IProtocol Protocol { get; }

Property Value

IProtocol

ServerProperties

A dictionary of the server properties sent by the server while establishing the connection. This typically includes the product name and version of the server.

IDictionary<string, object> ServerProperties { get; }

Property Value

IDictionary<string, object>

ShutdownReport

Returns the list of ShutdownReportEntry objects that contain information about any errors reported while closing the connection in the order they appeared

IList<ShutdownReportEntry> ShutdownReport { get; }

Property Value

IList<ShutdownReportEntry>

Methods

Abort()

Abort this connection and all its channels.

void Abort()

Remarks

Note that all active channels, sessions, and models will be closed if this method is called. In comparison to normal Close() method, Abort() will not throw IOException during closing connection. This method waits infinitely for the in-progress close operation to complete.

Abort(TimeSpan)

Abort this connection and all its channels and wait with a timeout for all the in-progress close operations to complete.

void Abort(TimeSpan timeout)

Parameters

timeout TimeSpan

Remarks

This method, behaves in a similar way as method Abort() with the only difference that it explictly specifies a timeout given for all the in-progress close operations to complete. If timeout is reached and the close operations haven't finished, then socket is forced to close.

To wait infinitely for the close operations to complete use Infinite.

Abort(ushort, string)

Abort this connection and all its channels.

void Abort(ushort reasonCode, string reasonText)

Parameters

reasonCode ushort
reasonText string

Remarks

The method behaves in the same way as Abort(), with the only difference that the connection is closed with the given connection close code and message.

The close code (See under "Reply Codes" in the AMQP 0-9-1 specification)

A message indicating the reason for closing the connection

Abort(ushort, string, TimeSpan)

Abort this connection and all its channels and wait with a timeout for all the in-progress close operations to complete.

void Abort(ushort reasonCode, string reasonText, TimeSpan timeout)

Parameters

reasonCode ushort
reasonText string
timeout TimeSpan

Remarks

The method behaves in the same way as Abort(TimeSpan), with the only difference that the connection is closed with the given connection close code and message.

The close code (See under "Reply Codes" in the AMQP 0-9-1 specification).

A message indicating the reason for closing the connection.

Close()

Close this connection and all its channels.

void Close()

Remarks

Note that all active channels, sessions, and models will be closed if this method is called. It will wait for the in-progress close operation to complete. This method will not return to the caller until the shutdown is complete. If the connection is already closed (or closing), then this method will do nothing. It can also throw IOException when socket was closed unexpectedly.

Close(TimeSpan)

Close this connection and all its channels and wait with a timeout for all the in-progress close operations to complete.

void Close(TimeSpan timeout)

Parameters

timeout TimeSpan

Remarks

Note that all active channels, sessions, and models will be closed if this method is called. It will wait for the in-progress close operation to complete with a timeout. If the connection is already closed (or closing), then this method will do nothing. It can also throw IOException when socket was closed unexpectedly. If timeout is reached and the close operations haven't finished, then socket is forced to close.

To wait infinitely for the close operations to complete use InfiniteTimeSpan.

Close(ushort, string)

Close this connection and all its channels.

void Close(ushort reasonCode, string reasonText)

Parameters

reasonCode ushort
reasonText string

Remarks

The method behaves in the same way as Close(), with the only difference that the connection is closed with the given connection close code and message.

The close code (See under "Reply Codes" in the AMQP specification).

A message indicating the reason for closing the connection.

Close(ushort, string, TimeSpan)

Close this connection and all its channels and wait with a timeout for all the in-progress close operations to complete.

void Close(ushort reasonCode, string reasonText, TimeSpan timeout)

Parameters

reasonCode ushort
reasonText string
timeout TimeSpan

Remarks

The method behaves in the same way as Close(TimeSpan), with the only difference that the connection is closed with the given connection close code and message.

The close code (See under "Reply Codes" in the AMQP 0-9-1 specification).

A message indicating the reason for closing the connection.

Operation timeout.

CreateModel()

Create and return a fresh channel, session, and model.

IModel CreateModel()

Returns

IModel

HandleConnectionBlocked(string)

Handle incoming Connection.Blocked methods.

void HandleConnectionBlocked(string reason)

Parameters

reason string

HandleConnectionUnblocked()

Handle incoming Connection.Unblocked methods.

void HandleConnectionUnblocked()

UpdateSecret(string, string)

This method updates the secret used to authenticate this connection. It is used when secrets have an expiration date and need to be renewed, like OAuth 2 tokens.

void UpdateSecret(string newSecret, string reason)

Parameters

newSecret string

The new secret.

reason string

The reason for the secret update.

Events

CallbackException

Signalled when an exception occurs in a callback invoked by the connection.

event EventHandler<CallbackExceptionEventArgs> CallbackException

Event Type

EventHandler<CallbackExceptionEventArgs>

Remarks

This event is signalled when a ConnectionShutdown handler throws an exception. If, in future, more events appear on IConnection, then this event will be signalled whenever one of those event handlers throws an exception, as well.

ConnectionBlocked

event EventHandler<ConnectionBlockedEventArgs> ConnectionBlocked

Event Type

EventHandler<ConnectionBlockedEventArgs>

ConnectionShutdown

Raised when the connection is destroyed.

event EventHandler<ShutdownEventArgs> ConnectionShutdown

Event Type

EventHandler<ShutdownEventArgs>

Remarks

If the connection is already destroyed at the time an event handler is added to this event, the event handler will be fired immediately.

ConnectionUnblocked

event EventHandler<EventArgs> ConnectionUnblocked

Event Type

EventHandler<EventArgs>