This project is read-only.

 

start-consumer


   

SYNOPSIS


    Starts consumption of messages from a RabbitMQ server.
   

SYNTAX


    start-consumer [-hostname] <String> [-exchange] <String> [-routingkey] <String> [[-queuename] <String>]
       [[-name] <String>] [[-protocol] <String>] [[-exchangetype] <String>] [[-virtualhost] <String>]
       [[-username] <String>] [[-password] <SecureString>] [[-encoding] <String>] [[-action] <ScriptBlock>]
       [<CommonParameters>]
   
   

DESCRIPTION


    The start-consumer cmdlet connects to a RabbitMQ server, declares an
    exchange and queue, binds the queue to a routing key, and instigates
    retreival of messages from the queue.
   
    Processing the messages can be accomplished in several ways.  To
    automatically run a handler in the background when a message arrives,
    assign a script block to the Action parameter.  To retrieve messages
    on-demand, use the receive-consumer cmdlet.  To block your script until
    a message arrives, use the wait-consumer cmdlet.
   
    Once a consumer is started, it will remain running until your session
    ends, or until explicitly stopped using the stop-consumer cmdlet.

PARAMETERS


    -hostname <String>
        Specifies the RabbitMQ server to which to connect.
       
        Required?                    true
        Position?                    1
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -exchange <String>
        The name of the exchange to use for messaging.
       
        Required?                    true
        Position?                    2
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -routingkey <String>
        The routing key to match.
       
        Required?                    true
        Position?                    3
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -queuename <String>
        The name of the queue to use; if unspecified a random queue
        name will be used.
       
        Required?                    false
        Position?                    4
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -name <String>
        The name of the new consumer; if unspecified a
        random name will be used.
       
        Required?                    false
        Position?                    5
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -protocol <String>
        The AMQP protocol support moniker to use when connecting
        to the RabbitMQ server.
       
        Required?                    false
        Position?                    6
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -exchangetype <String>
        Specifies the type of the exchange.  See get-exchangeType
        for a complete list.
       
        Required?                    false
        Position?                    7
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -virtualhost <String>
        The name of the RabbitMQ virtual host to which to connect.
       
        Required?                    false
        Position?                    8
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -username <String>
        The username to use for authenticating the RabbitMQ connection.
       
        Required?                    false
        Position?                    9
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -password <SecureString>
        The password to use for authenticating the RabbitMQ connection.
       
        Required?                    false
        Position?                    10
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -encoding <String>
        The encoding to use when translating the message body into a string.
       
        Required?                    false
        Position?                    11
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    -action <ScriptBlock>
        A script to run for each message received.
       
        Required?                    false
        Position?                    12
        Default value               
        Accept pipeline input?       true (ByPropertyName)
        Accept wildcard characters? 
       
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        "get-help about_commonparameters".
   

INPUTS


    None.
   
   

OUTPUTS


    PoshRabbit.IRabbitConsumer.  An object identifying  the consumer
    and queue. This object can be used with the other consumer-oriented cmdlets
    cmdets in the PoShRabbit module.
   

NOTES


   
   
        The Action ScriptBlock
        ----------------------
       
        The scriptblock is invoked once for each message received. 
        The message is available to the script block as the $_
        automatic variable.  Any values returned from the script
        are discarded, so you must explicitly pipe the message
        information to an output cmdlet if you wish to persist it.
       
        The $_ variable is of the type
        RabbitMQ.Client.Events.BasicDeliverEventArgs defined in the
        RabbitMQ .NET client. 
       
        Any errors that occur during the Action scriptblock are
        caught and published to the event queue of the PowerShell
        session using a source identifier value of
        'PoshRabbit.ActionHandler.Error'.  You can fetch a list
        of the errors that occurred using the get-event cmdlet:
       
        C:\PS>get-event -sourceIdentifier 'PoshRabbit.ActionHandler.Error'
       
        Messages and Encoding
        ---------------------
        When the Encoding parameter is used, an additional note property named
        Message is made available on the BasicDeliverEventArgs.  This property
        contains the binary message body interpreted as a string of the specified
        encoding, if possible.
       
        AMQP Defaults
        -------------
       
        By default connections are made using the AMPQ_8_0
        protocol set.
       
        By default exchanges are declared as topic exchanges. 
        They are also declared non-passive, non-durable,
        non-autodelete, and non-internal. 
       
        By default queues are declared as non-passing,
        non-durable, exclusive, and autodelete.  In addition,
        queues are created to use auto-acknowledge.
   
    -------------------------- EXAMPLE 1 --------------------------
   
    C:\PS>start-consumer -hostname RbtSvr -exchange ps -routingkey 't.?'
   
   
    Queue                      Name                                    IsRunning
    -----                      ----                                    ---------
    amq.gen-p+BKZbTX+7rWa/c... df1d85a3bc4548ef91bb177...                   True
   
    Description
    -----------
    This example starts a consumer using the most basic options.  Messages can
    be retrieved using the receive-consumer or wait-consumer cmdlets.
   
   
   
   
   
    -------------------------- EXAMPLE 2 --------------------------
   
   C:\PS>start-consumer -hostname RbtSvr -exchange ps -routingkey 't.?' -action {$_|write-host}
   
   
    Description
    -----------
    This example demonstrates responding to messages using a script block.  Each
    message received will be piped directly to the write-host cmdlet.
   
   
   
   
   
   

RELATED LINKS


    RabbitMQ general documentation: http://www.rabbitmq.com/documentation.html
    Exchanges: http://www.rabbitmq.com/faq.html#managing-concepts-exchanges
    BasicDeliverEventArgs: http://bit.ly/aQq4yw
    get-protocol
    get-exchangeType
    receive-consumer
    stop-consumer
    wait-consumer
    publish-string

Last edited Nov 22, 2010 at 3:12 AM by beefarino, version 2

Comments

No comments yet.