= AmqpNetLite C# Examples =

This directory contains example C# programs for AmqpNetLite. They are
based on the 1.0 version of the AMQP specification (see www.amqp.org for
details). The following examples are available:

* HelloWorld-simple Minimal send-receive through brokered topic.

* HelloWorld-robust Send-receive with more features.

* Interop.Drain, Interop.Spout - Interoperate with Apache Qpid
   using simple send and receive.

* Interop.Client, Interop.Server - Interoperate with Apache Qpid
   C++ Messaging using request and response.

* PeertoPeer - Client and Server programs illustrate using the
  Amqpnetlite library to create peer-to-peer connections without
  using an intermediate broker system.

* Receive Selector - Receive messages matching filter criteria

* Anonymous Relay - Like Interop.Client but detects and uses
  peer ANONYMOUS-RELAY capability for sending all messages over
  a single link, regardless of destination address.

== Running the Examples ==

Each example may be run most easily from within Visual Studio 2012
using the amqp.sln file.

== Hello World ==
-- HelloWorld_simple.cs --

HelloWorld_simple is a simple example that creates a Sender and a
Receiver for the same address, sends a message to the address, reads
a message from the address, and prints the result:

 $ HelloWorld_simple
 Hello world!

By default, this program connects to a broker running on
localhost:5672. You can specify a host and port, and the 
AMQP endpoint address explicitly on the command line:

 $ HelloWorld_simple amqp://localhost:5672 amq.topic

By default, this program addresses its messages to "amq.topic". In
Amqp brokers amq.topic is a predefined endpoint address and is 
immediately available with no broker configuration.

-- HelloWorld_robust.cs --

HelloWorld_robust shares all the features of the simple example with
additional options and processing.

 $ HelloWorld_robust
 Broker: amqp://localhost:5672, Address: amq.topic, Payload: Hello World!
 body:Hello World!

HelloWorld_robust allows the user to specfy a payload string and to 
enable trace protocol logging.

 $ HelloWorld_robust amqp://localhost:5672 amq.topic "My Hello" loggingOn

HelloWorld_robust also demonstrates:

 * Accessing message properties beyond the simple payload:
   - Header
   - DeliveryAnnotations
   - MessageAnnotations
   - Properties
   - ApplicationProperties
   - BodySection
   - Footer
 * Connection shutdown sequence


== Interop.Drain.cs, Interop.Spout.cs (drain, spout) ==

drain and spout provide many features for sending or receiving
messages. Use --help to see all available options.
These examples interoperate with the drain and spout example
code in Apache Qpid C++ Messaging.

In the simplest form you can send a message to endpoint 'hello-world'
with spout:

 $ Interop.Spout hello-world

Now you can read the message from this queue using drain:

 $ Interop.Drain.exe --address hello-world
 Message(
   Properties=properties(message-id:12c1cb72-e068-48c5-a904-0eefa8e14c4a:0), 
   ApplicationProperties=, Body=
   Message(properties={spout-id:c877e622-d57b-4df2-bf3e-6014c68da0ea:0}, content='')

Both drain and spout offer options to control message count, to control 
console output, and to exercise message processing.


== Request/Response ==
-- Interop.Client, Interop.Server --

This example shows a simple server that will accept strings from a client,
convert them to upper case, and send them back to the client. This example
has two components.

 1. client
    This sends lines of poetry to the server and prints responses.

 2. server
    A simple service that will convert incoming strings to upper case
    and return them to the requester.

In this example the server and client share a service endpoint 'service_queue'.
The server listens for messages at the service endpoint. Clients create
temporary dynamic ReplyTo queues, embed the temporary name in the requests,
and send the requests to the server. After receiving and processing each 
request the server sends the reply to the client's temporary ReplyTo address.

In order to run this example,

 $ Interop.Server.exe amqp://guest:guest@localhost:5672
 $ Interop.Client.exe amqp://guest:guest@localhost:5672


== Peer-to-Peer ==

PeerToPeer.Client and PeerToPeer.Server illustrate how two AMQP programs
can exchange messages without using any intermediary such as a broker.

The Server opens a network port and listens for both one way messages and
for round trip requests that must receive responses. The Server 
differentiates the message type based on the address of the endpoint
being served. The Server also uses a ContainerHost object to simplify
the server processing.

The Client sends a batch of messages that the server consumes and it sends
a batch of requests to which the server responds.

== Message Filters ==
-- Receive Selector --

The ReceiveSelector.cs example demonstrates how to set up filters 
on the receiver connection to the broker.

The ReceiverLink is created with a filter map of selector filters.
In this example a filter named 'f1' filters on the string property
'colour = 'green''. Messages must have a property named 'colour' 
whose value is 'green' before the message is passed to this receiver.

== Anonymous Relay ==

The AnonymousRelay.cs example uses a special feature of AMQP brokers and
routing intermediaries called ANONYMOUS-RELAY. An anonymous relay
is capable of sending messages to any endpoint through a single
connection and sender link.

The example code is similar to the Server discussed previously
as it performs an UPPERCASE service. In addition, AnonymousRelay.cs
examines the offered capabilities of the peer when a connection 
is established. If AnonymousRelay.cs detects an anonymous relay then it
creates only a single sender link for all of its service replies
regardless of the client ReplyTo address.

Sending all messages over a single SenderLink is much more efficient
than creating a SenderLink, sending a message, and destroying the link
on a per-message basis.
