The main solution for the sample application consisting of four projects. There are two projects for WPF Desktop application and the sample console application. Another two projects are additional libraries for WebSocket Client adapter and MarketData WebSocket library.

• The WebSocket client adapter is a library built on top of .NET Core ClientWebSocket class. It is responsible for handling a connection to a WebSocket server and sending or receiving a message from the Real-Time Advanced Distribution Server. The adapter provides a set of callback functions or delegates for handling and raising events to notify the application layer when it received a new message from the server. It also provides events to notify connection status and errors from .NET ClientWebSocket.

• The MarketData WebSocket library is responsible for handling business logic and creating a data model from the MRN JSON data. It also takes responsibility for managing the OMM Login and MRN update message. It has to assemble the MRN fragment and then verifying and decompressing the data to a JSON plain-text. The library also provides an additional interface to convert MRN JSON plain-text to MRN data model class so that the application can access the MRN data model rather than parsing the data from JSON string directly. The library also provides a set of events for delivering an MRN Story data to the application layer and also provide events to notify the application when it has an error inside the library.

How the application works

The following sequence diagram illustrates an overview of application workflow from the user point of view to the WebSocket server layer.

How the application connecting to WebSocket Server

• The user has to input a WebSocket endpoint and the DACS User, AppID, and DACS Position and then click the connect button. Note that if the Real-Time Advanced Distribution Server setup with DACS enabled requires a valid DACS user to connect to the server. After the user click connects, the UI layer has to register to receive events from an event source, which is WebSocketClient and MRNStoryManager class.

• The application then passes input parameters to WebSocketConnectionClient when it creates a new object. MrnStoryManager will use this class to connect to a WebSocket server and send or receive messages. Note that it has to add subprotocol "tr_json2" to the connection option; otherwise, the server will not accept the connection.

How the application receives a message from a WebSocket Connection

• To receive the message, the MrnStoryManager will call method Run() to start a new long-running task that implements a loop for receiving a message from .NET ClientWebSocket. It has to run until the user stops the operation and exit the application. This class's implementation is an asynchronous operation, and below is a snippet of codes for the implementation from the MRN Viewer app.

And below is the implementation of the Run() method. It's an asynchronous method which implements while loop to receive a message from WebSocket connection. 

How the application process messages from WebSocket connection

• After the connection has been established and the MRNStoryManager will send OMM Login request message to the server and wait until it gets a Login Accept and then send a new item request to the server to request data for MRN_STORY RIC from NewsTextAnalytics domain model.

• To process response message from ClientWebSocket, the MRNStoryManager create an internal event for receiving a message event from WebSocketConnectionClient and it will use JSON.NET to converting a raw buffer back to JSON plain-text and then parse the type of message from JSON message before generating specific events and send it back to UI layer or application layer. As stated earlier, the message could be a single JSON message or pack of a message which is a list that contains multiple sets of JSON data therefore that we need to iterate through the list to process the message one by one.

In case of the message is a Ping message from a server, it will send the Pong message back immediately to avoid the disconnection due to ping loss issue. Below is a snippet of codes from the implementation.

• To generate MRN Story events, the MRNStoryManager class has to implement an algorithm to verify whether or not the update message is a complete message and then generate event containing MRN Story data and send it back to the application layer.

• When the message type is update message, it converting the JSON data to MarketPriceUpdateMessage object using method ToObject. It is an extension method which created for converting data using a .NET Reflection. Therefore the name of property inside the class will be the same as field name defined in MRN DATA MODELS GUIDE document.

Below is a snippet of codes from the MRNStoryManager class when it processes the MRN update messages.

Following codes is the implementation of method ProcessFieldData.

• When a data item requires only a single message, then TOT_SIZE will equal the number of bytes in the FRAGMENT and FRAG_NUM will be 1. When multiple messages are required, then the data item can be deemed as fully received once the sum of the number of bytes of each FRAGMENT equals TOT_SUM. The consumer will also observe that all FRAG_NUM range from 1 to the number of a fragment, with no intermediate integers, skipped. In other words, a data item transmitted over three messages will contain FRAG_NUM values of 1, 2 and 3. Above algorithm will check if a message is a complete one, then it will decompressing the data and generate an event to the application layer by calling RaiseMrnMessageEvent.

How application closes a connection

To close a connection the user can click a Disconnect button and the internal codes will set Stop flag to be true. In this situation they will call Abort() and Dispose() to close the connection to the server like the following snippet of codes.

Build and Run Sample applications

There are two sample applications in the Visual Studio solution, MRNViewerApp which is a WPF desktop application, and WebSocketMRNConsumerApp which is a simple console application.

Build and Run WebSocketMRNConsumerApp

The WebSocketMRNConsumerApp is a console application demonstrate how to use the WebSokcetAdapter with the MRNManager to open a WebSocket connection to a WebSocket server, send an item request and handling the response message from the server. The example just prints MRN JSON data that the application receives to console output.

You may follow the following steps to build the application.

1) Run the Windows command line or using the terminal on macOS or Linux. Based on mrnWebSocketviewer repository you download from GitHub, change the folder to WebSocketMRNConsumerApp.

2) Make sure that you are running with .NET Core. Just check by running dotnet --version. We are testing with .NET Core 8.

3) Open folder WebSocketMRNConsumerApp with visual studio codes and then open file Program.cs. Then modify the server info and DACS user from the following codes. 

4) Run dotnet build under WebSocketMRNConsumerApp folder. You should see the following console output and you can find the executable file with requires DLLs under folder "bin\Debug\net8.0.

Note that if you want Self Contained deployment, you can run dotnet publish command as below command where "-c release" is for release build and "release_build" is the name of output folder under WebSocketMRNConsumerApp folder.

You can change win-x64 to another OS and you can find the list from rid-catalog page.

4) Change folder to "bin\Debug\net8.0", you should see WebSocketMRNConsumerConsoleApp.exe or WebSocketMRNConsumerConsoleApp executable file on Linux or macOS.

5) Run WebSocketMRNConsumerConsoleApp executable file and you should see the console output like this.

When the connection between the console application and WebSocket server has gone down, the MRN Manager will close the connection and attempt to make a new connection to the server on behalf of the application. So user should be able to receive the update message when it can establish to the WebSocket server again.

Build and Run MRNViewerApp

The MRNWebSocketViewerApp is a WPF desktop application which supports running on Windows OS only. This project using WPF with .NET 8.0 to create the application so you can deploy the app using Self-Contained Deployment(SCD) like the other .NET application. The benefit of using this approach, you have control of the version of .NET Core that is deployed with your app and the other apps or updates cannot break the behavior. While some of the disadvantages are that the size of your deployment package is relatively large since you have to include .NET Core as well as your app and its third-party dependencies. Anyway, it still easy to copy only the target build directory to share the application.

To build the desktop app, you don't need to open the project in Visual Studio. Instead, you can just run dotnet build or dotnet publish command to build the app. However, if you want to see the UI design view, you need to open a solution file with Visual Studio 2022.

Building the Desktop App

Please follow below steps to build the application.

1) Running command line on Windows and change folder to "MRNViewerApp".

2) Run command dotnet build under folder MRNViewerApp and you should see the following output.

Then you can find MRNWebSocketViewerApp.exe which is WPF application under the folder "bin\Debug\net8.0".

3) If you wish to use Self Contained Deployment you can also run the same command line as the console application to build a .NET app.

Then you can copy mrnviewerapp_release to run on the other Windows 10 and you don't need to install .NET Core before launching the app.

Running the Desktop App

• User has to launch MRNWebSocketViewerApp.exe and then it should show the following main desktop application.

Run the file and shows the following Desktop app.

• User can set DACS Login(User, AppId and change Position) by click Login button and change WebSocket endpoint to your Real-Time Advanced Distribution Server.

• The application shows the Connection status with an additional message via the Desktop Title Bar. The following sample screenshot shows sample messages from the WebSocket adapter in a different situation.

• Server Unavailable or unable to connect to the server.

• The application is making a connection to the server. While it's waiting, the user can cancel the request by click Cancel button.

• The connection to the WebSocket server is closed because the DACS user(user1) does not have permission to access the server. 

• Once the connection has been established and Login accepted by Real-Time Advanced Distribution Server, the application will send MRN_STORY item request to the server and waiting for a Refresh and Update messages back from the server. When the MRN Manager receives a complete MRN update, it will raise a message event back to the application layer and then the application can add the message to the internal list and bind it to DataGridView.

Below is a screenshot when the application receiving MRN Story update. It shows the timestamp application received the message with the Story Headline in the DataGridView. It also shows a whole message size in bytes and the fragment count which is the number of update messages before it assembly to the same story.

Displaying a News Story

To display a full story, the user must double click at specific row containing headline they are interesting on the DataGridView and then the application will pop up a new Dialog containing a full story with additional details such as Topics Code related to the News.

Below is a screenshot when the application receiving MRN Story update. It shows the timestamp application received the message with the Story Headline in the DataGridView. It also shows a whole message size in bytes and the fragment count which is the number of update messages before it assembly to the same story.

• There is an option for the user to copy only the News Story to the clipboard(click Copy Body to Clipboard) or save original MRN_STORY JSON data to file(click JSON data to file).

Please refer to the MRN DATA MODELS GUIDE for the JSON data structure inside the JSON file.

• Please note that the application using .NET Dictionary class to catching the MRN_STORY object inside the application; hence the user may experience the case that memory keeps growing when running the application for a long period of time.

Summary

This article provides example applications to demonstrate WebSocket API usage. It also uses ClientWebSocket class from .NET 8.0 SDK to communicate with the WebSocket server running on Real-Time Advanced Distribution Server. The solution project also provides a sample WebSocket adapter library, which the developer can re-use to build a cross-platform console application and WPF Windows desktop application. The solution project also provides an MRNStoryViewer Desktop application, which users can use to test the WebSocket server and displaying a News Story on the desktop application. It also has an option for a user to save the JSON data to a file. This should help a user to explorer MRN_STORY data from the data feed.

Download

Please download solution projects with source files from Github.

References

• MRN DATA MODELS
• WebSocket API Developer Guide
• .NET Core dotnet command reference
• ClientWebSocket Class .NET Core reference