Getting started

Example

The MigratoryData .Net Client API package is hosted on nuget.org.

A simple project for getting started can be created using dotnet tool. Run the following command to create a simple project in a working directory:

dotnet new console -n getting-started-csharp-client-api

Change to the folder of your project and add the API library with:

dotnet add package MigratoryData.Client.DotNet

Open the project in your IDE of choice and copy the snippet of code from bellow into file Program.cs.

using System;
using System.Collections.Generic;
using com.migratorydata.client;
using System.Threading;
namespace example
{
    class Program
    {
        static void Main(string[] args)
        {
            MigratoryDataClient client = new MigratoryDataClient();
            client.SetLogListener(new LogList(), MigratoryDataLogLevel.DEBUG);
            client.SetListener(new Listener());

            //client.SetEncryption(true);
            client.SetEntitlementToken("some-token");
            client.SetServers(new string[] { "127.0.0.1:8800" });

            List<string> subjects = new List<string>();
            subjects.Add("/server/status");
            client.Subscribe(subjects);

            client.Connect();

            // publish a message every 3 seconds
            int count = 1;
            while (count < 1000000)
            {
                client.Publish(new MigratoryDataMessage("/server/status", System.Text.Encoding.ASCII.GetBytes("data - " + count), "id" + count));
                count++;
                Thread.Sleep(3000);
            }
        }
        class Listener : MigratoryDataListener
        {
            public void OnMessage(MigratoryDataMessage message)
            {
                System.Console.WriteLine(message.ToString());
            }
            public void OnStatus(string status, string info)
            {
                System.Console.WriteLine(status + " " + info);
            }
        }
        class LogList : MigratoryDataLogListener
        {
            public void OnLog(string log, MigratoryDataLogLevel level)
            {
                string msg = string.Format("[{0:G}] [{1}] {2}", DateTime.Now, level, log);
                Console.WriteLine(msg);
            }
        }
    }
}

In this example the MigratoryData Client API is set to connect to the MigratoryData server located at address localhost:8800 and subscribe to the subject /server/status. If you don’t have a MigratoryData server installed on your machine but there is docker installed you can run the following command to start MigratoryData server, otherwise you can download and install the latest version for your os from here.

docker pull migratorydata/server:latest
docker run --platform linux/amd64 -d --name my_migratorydata -p 8800:8800 migratorydata/server:latest

Next, build and run the application using commands:

dotnet run

To test the application, connect to the MigratoryData server via browser at http://localhost:8800 and go to Debug Console. Subscribe and publish data to subject /server/status and see if the dotnet application is receiving data. Also you should receive data published by the dotnet application. The application publishes a message every 3 seconds on subject /server/status.

A typical API usage is as follows:

Step 1 - Include the library

Ass the API library to your project using dotnet or nuget tools. An example on how to add the library to your project using dotnet is as follow:

dotnet add package MigratoryData.Client.DotNet

Import in your application the classes of this API as follows:

using com.migratorydata.client;

Also, add this API library migratorydata-client-dotnet.dll, located in the folder lib of this API package, to the references of your .NET application.

Step 2 - Define a listener to get messages and status notifications

The listener should implement the MigratoryDataListener interface.

Use the API call MigratoryDataClient.SetListener() to attach your listener implementation.

Step 3 - Specify where to connect to

Specify a cluster of one or more MigratoryData servers to which the .Net client will connect to using the API method MigratoryDataClient.SetServers(). In fact, the client will connect to only one of the MigratoryData servers in this list. But, defining two or more MigratoryData servers is recommended in order to achieve fail-over. Supposing the MigratoryData server to which the client connected goes down, then the API will automatically reconnect the client to another MigratoryData server in the list.

Step 4 - Connect to the MigratoryData cluster

Use the API method MigratoryDataClient.Connect() to connect to the cluster and start receiving real-time messages from the MigratoryData cluster as well as status notifications.

Step 5 - Subscribe to subjects and publish messages

Use the API method MigratoryDataClient.Subscribe() to specify interest in receiving real-time messages having as subjects the strings provided in the parameter of this API method. You can call the API method MigratoryDataClient.Subscribe() at any time to subscribe to further subjects. To unsubscribe from subscribed subjects, use the API method MigratoryDataClient.Unsubscribe().

Use the API method MigratoryDataClient.Publish() to publish messages.

Step 6 - Handle the real-time messages and status notifications

Handle the messages received for the subscribed subjects as well as the status notifications in your listener implementation defined at Step 2 above.