Interface IConnection
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
ClientProperties
A copy of the client properties that has been sent to the server.
IDictionary<string, object> ClientProperties { get; }
Property Value
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
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
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
FrameMax
The maximum frame size this connection supports (0 if unlimited).
uint FrameMax { get; }
Property Value
Heartbeat
The current heartbeat setting for this connection (System.TimeSpan.Zero for disabled).
TimeSpan Heartbeat { get; }
Property Value
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
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
Protocol
The IProtocol this connection is using to communicate with its peer.
IProtocol Protocol { get; }
Property Value
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
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
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
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
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
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
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
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
Events
CallbackException
Signalled when an exception occurs in a callback invoked by the connection.
event EventHandler<CallbackExceptionEventArgs> CallbackException
Event Type
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
ConnectionShutdown
Raised when the connection is destroyed.
event EventHandler<ShutdownEventArgs> ConnectionShutdown
Event Type
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