Index | Namespace RabbitMQ.Client.MessagePatterns

public class SimpleRpcClient

implements IDisposable

Summary

Implements a simple RPC client.

Remarks

This class sends requests that can be processed by remote SimpleRpcServer instances.

The basic pattern for accessing a remote service is to determine the exchange name and routing key needed for submissions of service requests, and to construct a SimpleRpcClient instance using that address. Once constructed, the various Call() and Cast() overloads can be used to send requests and receive the corresponding replies.

            	string queueName = "ServiceRequestQueue"; // See also Subscription ctors
            	using (IConnection conn = new ConnectionFactory()
            	                                .CreateConnection(serverAddress)) {
            	    using (IModel ch = conn.CreateModel()) {
            	        ushort ticket = ch.AccessRequest("/data");
            	        SimpleRpcClient client =
            	            new SimpleRpcClient(ch, ticket, queueName);
            	        client.TimeoutMilliseconds = 5000; // optional
            	
            	        /// ... make use of the various Call() overloads
            	    }
            	}

Instances of this class do not themselves declare any resources (exchanges, queues or bindings). The Subscription we use for receiving RPC replies declares its own resources (usually a single queue), but if we are sending to an exchange other than one of the AMQP-standard mandated predefined exchanges, it is the user's responsibility to ensure that the exchange concerned exists (using IModel.ExchangeDeclare) before invoking Call() or Cast().

This class implements only a few basic RPC message formats - to extend it with support for more formats, either subclass, or transcode the messages before transmission using the built-in byte[] format.

See

RabbitMQ.Client.MessagePatterns.SimpleRpcServer

Property Summary

Flags	Type	Name	Summary
public	`PublicationAddress`	`Address` (rw)	Retrieve or modify the address that will be used for the next Call() or Cast().
public	`IModel`	`Model` (r)	Retrieve the IModel this instance uses to communicate.
public	`Subscription`	`Subscription` (r)	Retrieve the Subscription that is used to receive RPC replies corresponding to Call() RPC requests. May be null.
public	`ushort`	`Ticket` (r)	Retrieve the ticket this instance uses to take AMQP actions.
public	`int`	`TimeoutMilliseconds` (rw)	Retrieve or modify the timeout (in milliseconds) that will be used for the next Call().

Event Summary

Type	Name	Summary
`EventHandler`	`Disconnected`	This event is fired whenever Call() detects the disconnection of the underlying Subscription while waiting for a reply from the service.
`EventHandler`	`TimedOut`	This event is fired whenever Call() decides that a timeout has occurred while waiting for a reply from the service.

Constructor Summary

Flags	Name	Summary
public	`SimpleRpcClient(IModel model, ushort ticket, string exchange, string exchangeType, string routingKey)`	Construct an instance that will deliver to the named and typed exchange, with the given routing key.
public	`SimpleRpcClient(IModel model, ushort ticket, PublicationAddress address)`	Construct an instance that will deliver to the given address.
public	`SimpleRpcClient(IModel model, ushort ticket)`	Construct an instance with no configured Address. The Address property must be set before Call() or Cast() are called.
public	`SimpleRpcClient(IModel model, ushort ticket, string queueName)`	Construct an instance that will deliver to the default exchange (""), with routing key equal to the passed in queueName, thereby delivering directly to a named queue on the AMQP server.

Method Summary

Flags	Name	Summary
public virtual	`byte[] Call(byte[] body)`	Sends a simple byte[] message, without any custom headers or properties.
public virtual	`byte[] Call(IBasicProperties requestProperties, byte[] body, out IBasicProperties replyProperties)`	Sends a byte[] message and IBasicProperties header, returning both the body and headers of the received reply.
public virtual	`object[] Call(object[] args)`	Sends a "jms/stream-message"-encoded RPC request, and expects an RPC reply in the same format.
public virtual	`BasicDeliverEventArgs Call(IBasicProperties requestProperties, byte[] body)`	Sends a byte[]/IBasicProperties RPC request, returning full information about the delivered reply as a BasicDeliverEventArgs.
public virtual	`void Cast(IBasicProperties requestProperties, byte[] body)`	Sends an asynchronous/one-way message to the service.
public	`void Close()`	Close the reply subscription associated with this instance, if any.
public virtual	`void OnDisconnected()`	Signals that the Subscription we use for receiving our RPC replies was disconnected while we were waiting.
public virtual	`void OnTimedOut()`	Signals that the configured timeout fired while waiting for an RPC reply.

Property Detail

public PublicationAddress Address (rw)

Summary

Retrieve or modify the address that will be used for the next Call() or Cast().

Remarks

This address represents the service, i.e. the destination service requests should be published to. It can be changed at any time before a Call() or Cast() request is sent - the value at the time of the call is used by Call() and Cast().

public IModel Model (r)

Summary

Retrieve the IModel this instance uses to communicate.

public Subscription Subscription (r)

Summary

Retrieve the Subscription that is used to receive RPC replies corresponding to Call() RPC requests. May be null.

Remarks

Upon construction, this property will be null. It is initialised by the protected virtual method EnsureSubscription upon the first call to Call(). Calls to Cast() do not initialise the subscription, since no replies are expected or possible when using Cast().

public ushort Ticket (r)

Summary

Retrieve the ticket this instance uses to take AMQP actions.

public int TimeoutMilliseconds (rw)

Summary

Retrieve or modify the timeout (in milliseconds) that will be used for the next Call().

Remarks

This property defaults to System.Threading.Timeout.Infinite (i.e. -1). If it is set to any other value, Call() will only wait for the specified amount of time before returning indicating a timeout.

See also TimedOut event and OnTimedOut().

Event Detail

EventHandler Disconnected

Summary

This event is fired whenever Call() detects the disconnection of the underlying Subscription while waiting for a reply from the service.

Remarks

See also OnDisconnected(). Note that the sending of a request may result in OperationInterruptedException before the request is even sent.

EventHandler TimedOut

Summary

This event is fired whenever Call() decides that a timeout has occurred while waiting for a reply from the service.

Remarks

Constructor Detail

SimpleRpcClient

public SimpleRpcClient(IModel model, ushort ticket, string exchange, string exchangeType, string routingKey)

Parameters

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

Summary

Construct an instance that will deliver to the named and typed exchange, with the given routing key.

SimpleRpcClient

public SimpleRpcClient(IModel model, ushort ticket, PublicationAddress address)

Parameters

Name	Type
model	`IModel`
ticket	`ushort`
address	`PublicationAddress`

Summary

Construct an instance that will deliver to the given address.

SimpleRpcClient

public SimpleRpcClient(IModel model, ushort ticket)

Parameters

Name	Type
model	`IModel`
ticket	`ushort`

Summary

Construct an instance with no configured Address. The Address property must be set before Call() or Cast() are called.

SimpleRpcClient

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

Parameters

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

Summary

Construct an instance that will deliver to the default exchange (""), with routing key equal to the passed in queueName, thereby delivering directly to a named queue on the AMQP server.

Method Detail

Call

public virtual byte[] Call(byte[] body)

Flags public virtual

Return type byte[]

Parameters

Name	Type
body	`byte[]`

Summary

Sends a simple byte[] message, without any custom headers or properties.

Remarks

Delegates directly to Call(IBasicProperties, byte[]), and discards the properties of the received reply, returning only the body of the reply.

Calls OnTimedOut() and OnDisconnected() when a timeout or disconnection, respectively, is detected when waiting for our reply.

Returns null if the request timed out or if we were disconnected before a reply arrived.

The reply message, if any, is acknowledged to the AMQP server via Subscription.Ack().

Call

public virtual byte[] Call(IBasicProperties requestProperties, byte[] body, out IBasicProperties replyProperties)

Flags public virtual

Return type byte[]

Parameters

Name	Type
requestProperties	`IBasicProperties`
body	`byte[]`
replyProperties	`out` `IBasicProperties`

Summary

Sends a byte[] message and IBasicProperties header, returning both the body and headers of the received reply.

Remarks

Sets the "replyProperties" outbound parameter to the properties of the received reply, and returns the byte[] body of the reply.

Calls OnTimedOut() and OnDisconnected() when a timeout or disconnection, respectively, is detected when waiting for our reply.

Both sets "replyProperties" to null and returns null when either the request timed out or we were disconnected before a reply arrived.

The reply message, if any, is acknowledged to the AMQP server via Subscription.Ack().

Call

public virtual object[] Call(object[] args)

Flags public virtual

Return type object[]

Parameters

Name	Type
args	`object[]`

Summary

Sends a "jms/stream-message"-encoded RPC request, and expects an RPC reply in the same format.

Remarks

The arguments passed in must be of types that are representable as JMS StreamMessage values, and so must the results returned from the service in its reply message.

Calls OnTimedOut() and OnDisconnected() when a timeout or disconnection, respectively, is detected when waiting for our reply.

Returns null if the request timed out or if we were disconnected before a reply arrived.

The reply message, if any, is acknowledged to the AMQP server via Subscription.Ack().

See

Call

public virtual BasicDeliverEventArgs Call(IBasicProperties requestProperties, byte[] body)

Flags public virtual

Return type BasicDeliverEventArgs

Parameters

Name	Type
requestProperties	`IBasicProperties`
body	`byte[]`

Summary

Sends a byte[]/IBasicProperties RPC request, returning full information about the delivered reply as a BasicDeliverEventArgs.

Remarks

This is the most general/lowest-level Call()-style method on SimpleRpcClient. It sets CorrelationId and ReplyTo on the request message's headers before transmitting the request to the service via the AMQP server. If the reply's CorrelationId does not match the request's CorrelationId, ProtocolViolationException will be thrown.

Calls OnTimedOut() and OnDisconnected() when a timeout or disconnection, respectively, is detected when waiting for our reply.

Returns null if the request timed out or if we were disconnected before a reply arrived.

The reply message, if any, is acknowledged to the AMQP server via Subscription.Ack().

See

System.Net.ProtocolViolationException

Cast

public virtual void Cast(IBasicProperties requestProperties, byte[] body)

Flags public virtual

Return type void

Parameters

Name	Type
requestProperties	`IBasicProperties`
body	`byte[]`

Summary

Sends an asynchronous/one-way message to the service.

Close

public void Close()

Flags	public
Return type	`void`

Summary

Close the reply subscription associated with this instance, if any.

Remarks

Simply delegates to calling Subscription.Close(). Clears the Subscription property, so that subsequent Call()s, if any, will re-initialize it to a fresh Subscription instance.

OnDisconnected

public virtual void OnDisconnected()

Flags	public virtual
Return type	`void`

Summary

Signals that the Subscription we use for receiving our RPC replies was disconnected while we were waiting.

Remarks

Fires the Disconnected event.

OnTimedOut

public virtual void OnTimedOut()

Flags	public virtual
Return type	`void`

Summary

Signals that the configured timeout fired while waiting for an RPC reply.

Remarks

Fires the TimedOut event.