Interface IConnection
Main interface to an AMQP connection.
public interface IConnection : INetworkConnection, IAsyncDisposable, IDisposable- Inherited Members
- Extension Methods
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 and the IAsyncDisposable interface, so that the "using" statement can be used to scope the lifetime of a connection 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
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
IEnumerable<ShutdownReportEntry> ShutdownReport { get; }Property Value
Methods
CloseAsync(ushort, string, TimeSpan, bool, CancellationToken)
Asynchronously close this connection and all its channels and wait with a timeout for all the in-progress close operations to complete.
Task CloseAsync(ushort reasonCode, string reasonText, TimeSpan timeout, bool abort, CancellationToken cancellationToken = default)Parameters
reasonCodeushortThe close code (See under "Reply Codes" in the AMQP 0-9-1 specification).
reasonTextstringA message indicating the reason for closing the connection.
timeoutTimeSpanabortboolWhether or not this close is an abort (ignores certain exceptions).
cancellationTokenCancellationTokenCancellation token
Returns
CreateChannelAsync(CreateChannelOptions?, CancellationToken)
Asynchronously create and return a fresh channel, session, and channel.
Task<IChannel> CreateChannelAsync(CreateChannelOptions? options = null, CancellationToken cancellationToken = default)Parameters
optionsCreateChannelOptionsThe channel creation options.
cancellationTokenCancellationTokenCancellation token
Returns
UpdateSecretAsync(string, string, CancellationToken)
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.
Task UpdateSecretAsync(string newSecret, string reason, CancellationToken cancellationToken = default)Parameters
newSecretstringThe new secret.
reasonstringThe reason for the secret update.
cancellationTokenCancellationTokenCancellation token
Returns
Events
CallbackExceptionAsync
Signalled when an exception occurs in a callback invoked by the connection.
event AsyncEventHandler<CallbackExceptionEventArgs> CallbackExceptionAsyncEvent 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.
ConnectionBlockedAsync
Raised when a connection is blocked by the AMQP broker.
event AsyncEventHandler<ConnectionBlockedEventArgs> ConnectionBlockedAsyncEvent Type
ConnectionRecoveryErrorAsync
Raised when the connection recovery fails, e.g. because reconnection or topology recovery failed.
event AsyncEventHandler<ConnectionRecoveryErrorEventArgs> ConnectionRecoveryErrorAsyncEvent Type
Remarks
This event will never fire for connections that disable automatic recovery.
ConnectionShutdownAsync
Raised when the connection is destroyed.
event AsyncEventHandler<ShutdownEventArgs> ConnectionShutdownAsyncEvent 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.
ConnectionUnblockedAsync
Raised when a connection is unblocked by the AMQP broker.
event AsyncEventHandler<AsyncEventArgs> ConnectionUnblockedAsyncEvent Type
ConsumerTagChangeAfterRecoveryAsync
Raised when the server-generated tag of a consumer registered on this connection changes during connection recovery. This allows applications that need to be aware of server-generated consumer tag values to keep track of the changes.
event AsyncEventHandler<ConsumerTagChangedAfterRecoveryEventArgs> ConsumerTagChangeAfterRecoveryAsyncEvent Type
Remarks
This event will never fire for connections that disable automatic recovery.
QueueNameChangedAfterRecoveryAsync
Raised when the name of a server-named queue declared on this connection changes during connection recovery. This allows applications that need to be aware of server-named queue names to keep track of the changes.
event AsyncEventHandler<QueueNameChangedAfterRecoveryEventArgs> QueueNameChangedAfterRecoveryAsyncEvent Type
Remarks
This event will never fire for connections that disable automatic recovery.
RecoveringConsumerAsync
Raised when a consumer is about to be recovered. This event raises when topology recovery is enabled, and just before the consumer is recovered. This allows applications to update the consumer arguments before the consumer is recovered. It could be particularly useful when consuming from a stream queue, as it allows to update the consumer offset argument just before the consumer is recovered.
event AsyncEventHandler<RecoveringConsumerEventArgs> RecoveringConsumerAsyncEvent Type
Remarks
This event will never fire for connections that disable automatic recovery.
RecoverySucceededAsync
Raised when the connection completes recovery.
event AsyncEventHandler<AsyncEventArgs> RecoverySucceededAsyncEvent Type
Remarks
This event will never fire for connections that disable automatic recovery.