Index | Namespace RabbitMQ.Client.MessagePatterns

public class Subscription

implements IDisposable
implements IEnumerable
implements IEnumerator

Summary

Manages a subscription to a queue or exchange.

Remarks

This convenience class abstracts away from much of the detail involved in receiving messages from a queue or an exchange.

Once created, the Subscription consumes from a queue (using a QueueingBasicConsumer). Received deliveries can be retrieved by calling Next(), or by using the Subscription as an IEnumerator in, for example, a foreach loop.

See the documentation for Bind() and for the various overloads of the constructor for the various styles of binding and subscription that are available.

Note that if the "noAck" option is enabled (which it is by default), then received deliveries are automatically acked within the server before they are even transmitted across the network to us. Calling Ack() on received events will always do the right thing: if "noAck" is enabled, nothing is done on an Ack() call, and if "noAck" is disabled, IModel.BasicAck() is called with the correct parameters.

Property Summary

Flags	Type	Name	Summary
public	`IBasicConsumer`	`Consumer` (r)	Retrieve the IBasicConsumer that is receiving the messages from the server for us. Normally, you will not need to access this property - use Next() and friends instead.
public	`string`	`ConsumerTag` (r)	Retrieve the consumer-tag that this subscription is using. Will usually be a server-generated name.
public	`BasicDeliverEventArgs`	`LatestEvent` (r)	Returns the most recent value returned by Next(), or null when either no values have been retrieved yet, or the most recent value has already been Ack()ed. See also the documentation for Ack().
public	`IModel`	`Model` (r)	Retrieve the IModel our subscription is carried by.
public	`bool`	`NoAck` (r)	Returns true if we are in "noAck" mode, where calls to Ack() will be no-ops, and where the server acks messages before they are delivered to us. Returns false if we are in a mode where calls to Ack() are required, and where such calls will actually send an acknowledgement message across the network to the server.
public	`string`	`QueueName` (r)	Retrieve the queue name we have subscribed to. May be a server-generated name, depending on how the Subscription was constructed.
public	`ushort`	`Ticket` (r)	Retrieve the ticket we use for all our server operations.

Constructor Summary

Flags	Name	Summary
public	`Subscription(IModel model, ushort ticket, string queueName)`	Creates a new Subscription in "noAck" mode, consuming from a named queue. If the queueName parameter is null or the empty-string, creates a fresh, autodelete, anonymous queue; otherwise, the queue is declared using IModel.QueueDeclare() before IModel.BasicConsume() is called.
public	`Subscription(IModel model, ushort ticket, string queueName, bool noAck, string exchangeName, string exchangeType, string routingKey)`	Creates a new Subscription, with full control over both "noAck" mode and the name of the queue (which, if null or the empty-string, will be a fresh autodelete queue, as for the other constructor overloads). After declaring the queue and starting the consumer, the queue is bound to the named exchange, using Bind() with the given routingKey bind parameter.
public	`Subscription(IModel model, ushort ticket, string queueName, bool noAck)`	Creates a new Subscription, with full control over both "noAck" mode and the name of the queue (which, if null or the empty-string, will be a fresh autodelete queue, as for the other constructor overloads).
public	`Subscription(IModel model, ushort ticket, string exchangeName, string exchangeType, string routingKey)`	Creates a new Subscription in "noAck" mode, consuming from a fresh, autodelete, anonymous queue. The name of the queue can be retrieved using the QueueName property of the Subscription. After creating the queue, the queue is bound to the named exchange, using Bind() with the given routingKey bind parameter.
public	`Subscription(IModel model, ushort ticket)`	Creates a new Subscription in "noAck" mode, consuming from a fresh, autodelete, anonymous queue. The name of the queue can be retrieved using the QueueName property of the Subscription.
public	`Subscription(IModel model, ushort ticket, string queueName, string exchangeName, string exchangeType, string routingKey)`	Creates a new Subscription in "noAck" mode, consuming from a named queue. If the queueName parameter is null or the empty-string, creates a fresh, autodelete, anonymous queue; otherwise, the queue is declared using IModel.QueueDeclare() before IModel.BasicConsume() is called. After declaring the queue and starting the consumer, the queue is bound to the named exchange, using Bind() with the given routingKey bind parameter.

Method Summary

Flags	Name	Summary
public	`void Ack()`	If LatestEvent is non-null, passes it to Ack(BasicDeliverEventArgs). Causes LatestEvent to become null.
public	`void Ack(BasicDeliverEventArgs evt)`	If we are not in "noAck" mode, calls IModel.BasicAck with the delivery-tag from the passed in event; otherwise, sends nothing to the server. In both cases, if the passed-in event is the same as LatestEvent (by pointer comparison), sets LatestEvent to null.
public	`void Bind(string exchangeName, string exchangeType, string routingKey)`	Causes the queue to which we have subscribed to be bound to an exchange. Uses IModel.ExchangeDeclare and IModel.QueueBind to (a) ensure the exchange exists, and (b) link the exchange to our queue.
public	`void Close()`	Closes this Subscription, cancelling the consumer record in the server. If an anonymous, autodelete queue (i.e., one with a server-generated name) was created during construction of the Subscription, this method also deletes the created queue (which is an optimisation: autodelete queues will be deleted when the IModel closes in any case).
public	`bool Next(int millisecondsTimeout, out BasicDeliverEventArgs result)`	(undocumented)
public	`BasicDeliverEventArgs Next()`	Retrieves the next incoming delivery in our subscription queue.

Property Detail

public IBasicConsumer Consumer (r)

Summary

Retrieve the IBasicConsumer that is receiving the messages from the server for us. Normally, you will not need to access this property - use Next() and friends instead.

public string ConsumerTag (r)

Summary

Retrieve the consumer-tag that this subscription is using. Will usually be a server-generated name.

public BasicDeliverEventArgs LatestEvent (r)

Summary

Returns the most recent value returned by Next(), or null when either no values have been retrieved yet, or the most recent value has already been Ack()ed. See also the documentation for Ack().

public IModel Model (r)

Summary

Retrieve the IModel our subscription is carried by.

public bool NoAck (r)

Summary

Returns true if we are in "noAck" mode, where calls to Ack() will be no-ops, and where the server acks messages before they are delivered to us. Returns false if we are in a mode where calls to Ack() are required, and where such calls will actually send an acknowledgement message across the network to the server.

public string QueueName (r)

Summary

Retrieve the queue name we have subscribed to. May be a server-generated name, depending on how the Subscription was constructed.

public ushort Ticket (r)

Summary

Retrieve the ticket we use for all our server operations.

Constructor Detail

Subscription

public Subscription(IModel model, ushort ticket, string queueName)

Parameters

Name	Type
model	`IModel`
ticket	`ushort`
queueName	`string`

Summary

Subscription

public Subscription(IModel model, ushort ticket, string queueName, bool noAck, string exchangeName, string exchangeType, string routingKey)

Parameters

Name	Type
model	`IModel`
ticket	`ushort`
queueName	`string`
noAck	`bool`
exchangeName	`string`
exchangeType	`string`
routingKey	`string`

Summary

Creates a new Subscription, with full control over both "noAck" mode and the name of the queue (which, if null or the empty-string, will be a fresh autodelete queue, as for the other constructor overloads). After declaring the queue and starting the consumer, the queue is bound to the named exchange, using Bind() with the given routingKey bind parameter.

Subscription

public Subscription(IModel model, ushort ticket, string queueName, bool noAck)

Parameters

Name	Type
model	`IModel`
ticket	`ushort`
queueName	`string`
noAck	`bool`

Summary

Subscription

public Subscription(IModel model, ushort ticket, string exchangeName, string exchangeType, string routingKey)

Parameters

Name	Type
model	`IModel`
ticket	`ushort`
exchangeName	`string`
exchangeType	`string`
routingKey	`string`

Summary

Creates a new Subscription in "noAck" mode, consuming from a fresh, autodelete, anonymous queue. The name of the queue can be retrieved using the QueueName property of the Subscription. After creating the queue, the queue is bound to the named exchange, using Bind() with the given routingKey bind parameter.

Subscription

public Subscription(IModel model, ushort ticket)

Parameters

Name	Type
model	`IModel`
ticket	`ushort`

Summary

Creates a new Subscription in "noAck" mode, consuming from a fresh, autodelete, anonymous queue. The name of the queue can be retrieved using the QueueName property of the Subscription.

Subscription

public Subscription(IModel model, ushort ticket, string queueName, string exchangeName, string exchangeType, string routingKey)

Parameters

Name	Type
model	`IModel`
ticket	`ushort`
queueName	`string`
exchangeName	`string`
exchangeType	`string`
routingKey	`string`

Summary

Creates a new Subscription in "noAck" mode, consuming from a named queue. If the queueName parameter is null or the empty-string, creates a fresh, autodelete, anonymous queue; otherwise, the queue is declared using IModel.QueueDeclare() before IModel.BasicConsume() is called. After declaring the queue and starting the consumer, the queue is bound to the named exchange, using Bind() with the given routingKey bind parameter.

Method Detail

Ack

public void Ack()

Flags	public
Return type	`void`

Summary

If LatestEvent is non-null, passes it to Ack(BasicDeliverEventArgs). Causes LatestEvent to become null.

Ack

public void Ack(BasicDeliverEventArgs evt)

Flags public

Return type void

Parameters

Name	Type
evt	`BasicDeliverEventArgs`

Summary

If we are not in "noAck" mode, calls IModel.BasicAck with the delivery-tag from the passed in event; otherwise, sends nothing to the server. In both cases, if the passed-in event is the same as LatestEvent (by pointer comparison), sets LatestEvent to null.

Remarks

Make sure that this method is only called with events that originated from this Subscription - other usage will have unpredictable results.

Bind

public void Bind(string exchangeName, string exchangeType, string routingKey)

Flags public

Return type void

Parameters

Name	Type
exchangeName	`string`
exchangeType	`string`
routingKey	`string`

Summary

Causes the queue to which we have subscribed to be bound to an exchange. Uses IModel.ExchangeDeclare and IModel.QueueBind to (a) ensure the exchange exists, and (b) link the exchange to our queue.

Remarks

This method is called by some of the overloads of the Subscription constructor.

Calling Bind() multiple times to bind to multiple exchanges, or to bind to a single exchange more than once with a different routingKey, is perfectly acceptable. Calling Bind() twice with exactly the same arguments is permitted and idempotent. For details, see the AMQP specification.

Close

public void Close()

Flags	public
Return type	`void`

Summary

Closes this Subscription, cancelling the consumer record in the server. If an anonymous, autodelete queue (i.e., one with a server-generated name) was created during construction of the Subscription, this method also deletes the created queue (which is an optimisation: autodelete queues will be deleted when the IModel closes in any case).

public bool Next(int millisecondsTimeout, out BasicDeliverEventArgs result)

Flags public

Return type bool

Parameters

Name	Type
millisecondsTimeout	`int`
result	`out` `BasicDeliverEventArgs`

Remarks

Returns false only if the timeout expires before either a delivery appears or the end-of-stream is reached. If false is returned, the out parameter "result" is set to null, but LatestEvent is not updated.

Returns true to indicate a delivery or the end-of-stream.

If a delivery is already waiting in the queue, or one arrives before the timeout expires, it is removed from the queue and placed in the "result" out parameter. If the end-of-stream is detected before the timeout expires, "result" is set to null.

Whenever this method returns true, it updates LatestEvent to the value placed in "result" before returning.

End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection.

This method does not acknowledge any deliveries at all (but in "noAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us).

A timeout of -1 (i.e. System.Threading.Timeout.Infinite) will be interpreted as a command to wait for an indefinitely long period of time for an item or the end of the stream to become available. Usage of such a timeout is equivalent to calling Next() with no arguments (modulo predictable method signature differences).

public BasicDeliverEventArgs Next()

Flags	public
Return type	`BasicDeliverEventArgs`

Summary

Retrieves the next incoming delivery in our subscription queue.

Remarks

Returns null when the end of the stream is reached and on every subsequent call. End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection.

Updates LatestEvent to the value returned.

Does not acknowledge any deliveries at all (but in "noAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us).