This project is read-only.

Usage

Prerequisites

Install the Module

You must install the PoShRabbit module before you will be able to use it. For information see Installation.

Install and Configure a RabbitMQ server

You will need the following properties of the RabbitMQ server and messaging configuration to make use of the PoShRabbit module:
  • RabbitMQ Server Hostname
  • Virtual Hostname (if used)
  • Username (if used)
  • Password (if used)
  • Exchange Name
  • Exchange Type (direct, topic, or fanout)
  • Routing Key

Importing the Provider into your PowerShell Session

Once the module is installed, you can pull it into any PowerShell session using the following command:
import-module poshrabbit

You can verify that the module was loaded properly using the get-module cmdlet:
> get-module

ModuleType Name                      ExportedCommands
---------- ----                      ----------------
Script     poshrabbit                {get-consumer, start-consumer, stop-consumer, get-exchangeType...}

Starting a Message Consumer

To begin receiving messages from RabbitMQ, use the start-consumer cmdlet:

$consumer = start-consumer -name 'myconsumer' -hostname RbtMq -exchange 'ps' -routingkey 'pfx.#';

Every consumer is referenced by a name; if you do not provide a value for the -name parameter a name will be generated for your consumer. This name is used to identify and reference the consumer in other cmdlets. Each consumer name must be unique to all other consumers in the current PowerShell session.

Note that start-consumer assumes the following defaults unless you override them with parameter values.
  • the RabbitMQ connection will be initiated with the AMQP08 protocol dialect; you can override this behavior by providing a value in the -protocol parameter.
  • the exchange is declared of exchange type 'topic'; you can override this using the -exchangetype parameter.
  • the queue name is autogenerated by the RabbitMQ server; you can specify an explicit queue name using the -queuename parameter.
  • if your RabbitMQ requires authentication, you can use the -virtualhost, -username, and -password parameters.

At this time, the following properties of queues and exchanges cannot be altered:
  • queues are declared as
  • exchanges are declared as

A Note about Ack

At this time, PoShRabbit consumers are declared to use the auto-ack feature of RabbitMQ. This means that any message received by a consumer is pre-acknowledged with the RabbitMQ server.

This will be optional in the near future, but for the time being you should understand that if you fail to process messages received by the PoShRabbit consumer, the messages will not be requeued in the RabbitMQ exchange.

Receiving Messages

Messages are exposed to PowerShell as instances of http://www.rabbitmq.com/releases/rabbitmq-dotnet-client/v2.1.1/rabbitmq-dotnet-client-2.1.1-client-htmldoc/html/type-RabbitMQ.Client.Events.BasicDeliverEventArgs.html. If you specify a value for the -encoding parameter of start-consumer, the instance will also contain a note property named Message; this property will contain the value of the binary message body interpreted as a string of the specified encoding.

PoShRabbit supports three methods of receiving events: manual polling, blocking until a message arrives, or assigning a scriptblock to process incoming messages.

Manual Polling for Messages

The receive-consumer cmdlet will return any messages received by a specific consumer since the previous call to receive-consumer or wait-consumer:

$consumer | receive-consumer | foreach-object { $_ | out-file 'msgs.txt' -append } ;

The receive-consumer cmdlet returns immediately. If no messages are available the cmdlet returns nothing.

Blocking Until a Message is Available

The wait-consumer cmdlet will block script execution until a message is received by the specified consumer:

$message = $consumer | wait-consumer
$message | out-file 'msgs.txt' -append;

In this example, the $event variable is guaranteed to contain an event.

Wait-event supports an optional -timeout parameter, specified in seconds. When specified the cmdlet will return no value if no message is received in the timeout period.

Assigning a Script Block to Handle Message Automagically

The start-consumer cmdlet accepts an optional -action scriptblock parameter. When specified, the scriptblock is executed in the background once for each message received by the consumer:

$consumer = start-consumer -name 'myconsumer' -hostname RbtMq -exchange 'ps' -routingkey 'pfx.#' -action {$_ | out-file 'msgs.txt' -append };

The message is accessible in the scriptblock as the $_ automatic variable. Note that no default output is taken on the results of the scriptblock; if you need to output anything from the -action handler, you must explicitly pipe it to write-host or another output cmdlet.

Any errors that occur when the scriptblock is executed are captured as events in the current PowerShell session. These events contain the following sourceIdentifier value:
  • PoshRabbit.ActionHandler.Error

You can retrieve these errors using the standard PowerShell get-event cmdlet:

get-event -sourceIdentifier 'PoshRabbit.ActionHandler.Error'

Stopping a Consumer

Once you are done processing messages, use the stop-consumer cmdlet to close the RabbitMQ consumer and release its resources:

$messages = $consumer | stop-consumer;
$consumer = $null;

Stop-consumer returns any pending messages received by the consumer since the last call to wait-consumer or receive-consumer.

Once a consumer is stopped, it should be considered disposed; attempting to use the consumer with any other PoShRabbit cmdlet will result in an error.

For More Information

For more usage information, and for details about using specific cmdlets, please see Examples and Reference.

For information on RabbitMQ please see http://www.rabbitmq.com.

Last edited Nov 22, 2010 at 9:51 PM by beefarino, version 1

Comments

No comments yet.