AMQPClassic Class

Properties   Methods   Events   Configuration Settings   Errors  

An easy-to-use AMQP 0.9.1 client implementation, with support for RabbitMQ extensions.

Syntax

class ipworksiot.AMQPClassic

Remarks

The AMQPClassic class provides an easy-to-use AMQP 0.9.1 client implementation, and it also supports certain RabbitMQ extensions to the AMQP 0.9.1 specification. The class supports both plaintext and TLS-enabled connections over TCP.

Connecting

The AMQP 0.9.1 transport protocol has two layers: an overall connection between the client and server, and one or more channels running over that connection.

The class implements both layers, so the first step is to initiate the overall connection. Set the auth_scheme, user, password, ssl_enabled, and virtual_host properties if necessary, then call the connect method, passing it the server's hostname and port number. (If the server in question is not running RabbitMQ, disabling the RabbitMQCompatible configuration setting before connecting is also recommended.)

The next step is to create at least one channel, which can be accomplished by using the create_channel method. The class allows creating any number of channels, up to the limit specified by the MaxChannelCount configuration setting.

Connecting and Creating a Channel

// The examples in this documentation use a RabbitMQ server, which requires SASL Plain auth.
amqpc1.AuthScheme = AmqpclassicAuthSchemes.smSASLPlain;
amqpc1.User = "guest";
amqpc1.Password = "guest";
amqpc1.SSLEnabled = true;
amqpc1.Connect("amqpclassic.test-server.com", 5671);
amqpc1.CreateChannel("channel");

Once the class has connected to the server, and one or more channels have been opened, the class can begin manipulating exchanges and queues, publishing messages, and creating consumers.

Note that most AMQP 0.9.1 operations can themselves vary in their complexity. The examples below are intentionally simple for the sake of clarity and brevity, but links are provided for many other parts of the class's API where more detail can be found.

Declaring Exchanges

The declare_exchange method is used to declare (i.e., create, or verify the existence of) exchanges on the server. While all AMQP servers provide a default, direct-type exchange that all queues are bound to automatically (using their name as the routing key), more complex use-cases will often require creating additional exchanges of varying types.

Declaring an Exchange

// Declare a direct-type exchange.
amqpc1.DeclareExchange("channel", "MyExchange", "direct", false, false, false, false);

Exchanges can also be deleted using the delete_exchange method.

Declaring Queues

The declare_queue method is used to declare (i.e., create, or verify the existence of) queues on the server. Unlike with exchanges, the server does not provide any queues by default, so declaring a queue is always necessary (unless one has already been created by another client, or configured ahead-of-time on the server itself).

Declaring a Queue

// Declare a queue.
amqpc1.DeclareQueue("channel", "MyQueue", false, false, false, false, false);

Queues may also be deleted or purged using the delete_queue and purge_queue methods.

Binding Queues to Exchanges

The bind_queue method is used to bind a queue to an exchange. Exchanges use the information held by their queue bindings to determine which messages to forward to which queues.

Note that all AMQP 0.9.1 servers automatically bind all queues to their default exchange (which is always a direct exchange with no name) using each queue's name as the binding's routing key. This makes it easy to send a message to a specific queue without having to declare bindings; just call publish_message, pass empty string for ExchangeName, and the name of the desired queue for RoutingKey.

Binding a Queue to an Exchange

// Bind a queue to an exchange. Messages will only be delivered to the queue if their routing key is "MyRoutingKey".
amqpc1.BindQueue("channel", "MyQueue", "MyExchange", "MyRoutingKey", false);

Queues can also be unbound from exchanges using the unbind_queue method.

Publishing Messages

To publish a message, populate the Message* properties, and then call the publish_message method.

Publishing a Message

amqpc1.Message.Body = "Hello, world!";

// Publish a message to the server's default (no-name) exchange, using the name of a specific queue as the routing key.
amqpc1.PublishMessage("channel", "", "MyQueue", false, false);

// Publish a message to the "MyExchange" exchange, using the routing key "MyRoutingKey".
amqpc1.PublishMessage("channel", "MyExchange", "MyRoutingKey", false, false);

Note that outgoing messages may be handled differently by the server if the channel they are sent over is in transaction or (for RabbitMQ only) "publish confirmations" mode. Refer to the enable_transaction_mode and enable_publish_confirms methods for more information.

Receiving Messages

There are two possible ways for the class to receive a message:

• Messages can be asynchronously pushed to the class from the server. At any point in time, the server may push a message to the class from a queue that the consume method has been used to attach a consumer to.
• Messages can be synchronously pulled from the server by the class. The fetch_message method is used to attempt to pull (or "fetch") messages from a specific queue.

Regardless of how they are received, all incoming messages cause the ReceivedMessage* properties to be populated and the on_message_in event to fire.

Receiving a Message

// MessageIn event handler.
amqpc1.OnMessageIn += (s, e) => {
  if (e.MessageCount == -1) {
    // The server pushed a message to us asynchronously due to a consumer we created.
    Console.WriteLine("The server pushed this message to us via consumer '" + e.ConsumerTag + "':");
    Console.WriteLine(amqpc1.ReceivedMessage.Body);
  } else if (e.DeliveryTag > 0) {
    // We pulled a message from a queue with the FetchMessage() method.
    Console.WriteLine("Message successfully pulled:");
    Console.WriteLine(amqpc1.ReceivedMessage.Body);
    Console.WriteLine(e.MessageCount + " messages are still available to pull.");
  } else {
    // We tried to pull a message, but there were none available to pull.
    Console.WriteLine("No messages available to pull.");
  }
};

// Attach a consumer to "MyQueue".
amqpc1.Consume("channel", "MyQueue", "consumerTag", false, true, false, false);

// Or, try to fetch a message from "MyQueue".
amqpc1.FetchMessage("channel", "MyQueue", true);

Note that the on_message_in event always fires if fetch_message is called successfully, even if there were no messages available to fetch; refer to on_message_in for more information.