Your First AMPS Program

In this chapter, we will learn more about the structure and features of the AMPS C# library, and build our first C# program using AMPS.

About the Client Library

The AMPS client is packaged as a single managed assembly, AMPS.Client.dll You can find AMPS.Client.dll in the AMPS/bin directory of your AMPS C# client. Every .NET application you build will need to reference this assembly file, and the assembly must be deployed along with your application in order for your application to function properly.

Connecting to AMPS

Let's begin by writing a simple program that connects to an AMPS server and publishes a single message to a topic:

using System;
using AMPS.Client;
using AMPS.Client.Exceptions;

namespace AMPSBookExamples
{
    class ConnectToAMPS
    {
        static void Main(string[] args)
        {
            using(Client client = new Client("exampleClient"))
            {
                try
                {
                    client.connect("tcp://192.168.1.3:9007/amps");
                    client.logon();
                    client.publish("messages", @"{ ""message"" : ""Hello, World!"" }");
                }
                catch (AMPSException e)
                {
                    Console.Error.WriteLine(e);
                }
            }
        }
    }
}

In the example above, we show the entire program; but future examples will isolate one or more specific portions of the code. The next section describes how to build and run the application and explains the code in further detail.

Build and Run

To build this program, create a new C# command-line project in Visual Studio and add a reference to AMPS.Client.dll using the "Add Reference..." option in Visual Studio. Replace the code in Program.cs with the code in the example above, then modify the client.connect() on line 14 with the address and port of your AMPS server. Now you should be able to compile and execute the code, and if the AMPS server is running, the message Hello world is published to the messages topic. If an error occurs, an exception will be written to the console.

If the message is published successfully, there is no output to the console. We will demonstrate how to create a subscriber to receive messages in the next chapter.

Examining the Code

Let us now revisit the code we listed earlier.

using System;
using AMPS.Client;
using AMPS.Client.Exceptions;

namespace AMPSBookExamples
{
    class ConnectToAMPS
    {
        static void Main(string[] args)
        {

            // This line creates a new Client object. Client encapsulates a single connection
            // to an AMPS server. Methods on Client allow for connecting, disconnecting,
            // publishing, and subscribing to an AMPS server. The argument to the Client
            // constructor, "exampleClient", is a name chosen by the client to identify itself
            // to the server. Errors relating to this connection will be logged with reference
            // to this name, and AMPS uses this name to help detect duplicate messages. AMPS
            // enforces uniqueness for client names when a transaction log is configured, and
            // it is good practice to always use unique client names. The using statement ensures
            // that the connection underlying the client is disposed of before the program exists.
            // Client implements the .NET IDisposable interface, making it easy to ensure that
            // are freed when your Client is no longer in use. There is no need to
            // disconnect the Client when it is protected by a using statement.
            using(Client client = new Client("exampleClient"))
            {

                try
                {

                // At this point, we have a valid AMPS connection and can begin to use it to
                // publish and subscribe to messages.
                client.connect("tcp://192.168.1.3:9007/amps");

                // This version of logon() uses the DefaultAuthenticator, which provides the
                // credentials in the URI (if any are present). To use a different authentication
                // scheme, implement an Authenticator and pass that to this command.
                client.logon()

                // Here, we publish a single message to AMPS on the messages topic, containing the
                // data { "message" : "Hello, world!" }.
                // This JSON message is sent to the server. Upon successful completion of this function,
                // the AMPS client has sent the message to the server, and subscribers to the messages
                // topic will receive this message.
                client.publish("messages", @"{ ""message"" : ""Hello, World!"" }");
                }

                catch (AMPSException e)
                {
                    Console.Error.WriteLine(e);
                }
            }
        }
    }
}