public class Subscription

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, the end of the subscription has been reached, 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.

Constructor Summary

Flags Name Summary
public Subscription(IModel model, 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, exclusive, autodelete, anonymous queue; otherwise, the queue is declared using IModel.QueueDeclare() before IModel.BasicConsume() is called.

public Subscription(IModel model, 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, exclusive, autodelete, anonymous 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, 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, exclusive, autodelete, anonymous queue, as for the other constructor overloads).

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

Creates a new Subscription in "noAck" mode, consuming from a fresh, exclusive, 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)

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

public Subscription(IModel model, 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, exclusive, 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(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 Ack()

If LatestEvent is non-null, passes it to Ack(BasicDeliverEventArgs). Causes LatestEvent to become 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, exclusive, 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)

Retrieves the next incoming delivery in our subscription queue, or times out after a specified number of milliseconds.

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, the end of the subscription has been reached, 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.

Constructor Detail

Subscription

public Subscription(IModel model, string queueName)

Parameters
Name Type
model IModel
queueName 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, exclusive, autodelete, anonymous queue; otherwise, the queue is declared using IModel.QueueDeclare() before IModel.BasicConsume() is called.

Subscription

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

Parameters
Name Type
model IModel
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, exclusive, autodelete, anonymous 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, string queueName, bool noAck)

Parameters
Name Type
model IModel
queueName string
noAck bool

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, exclusive, autodelete, anonymous queue, as for the other constructor overloads).

Subscription

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

Parameters
Name Type
model IModel
exchangeName string
exchangeType string
routingKey string

Summary

Creates a new Subscription in "noAck" mode, consuming from a fresh, exclusive, 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)

Parameters
Name Type
model IModel

Summary

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

Subscription

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

Parameters
Name Type
model IModel
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, exclusive, 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(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.

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.

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, exclusive, 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).

Next

public bool Next(int millisecondsTimeout, out BasicDeliverEventArgs result)

Flags public
Return type bool
Parameters
Name Type
millisecondsTimeout int
result out BasicDeliverEventArgs

Summary

Retrieves the next incoming delivery in our subscription queue, or times out after a specified number of milliseconds.

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

Next

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