Latest code and release package available at GitHub and NuGet.
Introduction
TCP Application Protocol is server/client text message protocol created on top of TCP (Transmission Control Protocol). TCP Application Protocol is a high level communication protocol to provide a common remote interface between applications which can be easily integrated to any application with minimum coding effort from developer on both server and client application.
Why TCP?
Communication between two applications is generally called as IPC (Inter-Process Communication). There are many ways of IPC. TCP/IP is one of them. The advantage of TCP/IP is that the communicating applications can be running on different computers and different locations. Since Internet also works on TCP/IP, remote applications can communicate over the internet. TCP/IP is completely platform independent, standard, and implemented by all operationg systems (and many other devices). (Reference: Code Project - A Complete TCP Server/Client Communication and RMI Framework in C# .NET – Implementation)
Advantage of TCP Application Protocol
TCP Application Protocol is server/client implementation where server application will response to request initiate from client application. With TCP Application Protocol, application specific commands can be easily defined by server application. Each registered command keyword can include with one or more optional or mandatory parameter as needed. Incoming message from client will be verified against registered command set and have defined parameters parse and assigned. Developer can focus on implementation of each of the command.
As human readable text message based protocol, no translation and interpretation of machine code is required on message passed between server and client. Furthermore, registered commands on server application can be easily retrieved by client application without the need to refer to user manual or code.
With TcpAppServerPlugin class, command set for plugin components can be developed and added to host application easily at a later stage without the requirement to rebuild the host application. Moreover, client application may instantiate objects on server application remotely. Number of clients allowed to connect to server at a time can also be configured.
About TCP Application Protocol
Any TCP client including realterm can be use to interact with application which implement TCP Application protocol since the protocol is implemented in human readable text message.
In general, the command between client and server is defined as follows:
TCP Application Server has predefined command set which is created to retrieve information about server application, registered commands and plugins which are intended to ease the integration process between client and server application. Simply send Help command to server will return list of registered commands. Other commands such as FunctionList?, ApplicationName?, ApplicationVersion? are created to return information from server application to connected client.
TCPAppClientTerminal is an example of TCP client implementation. Compiled binary and source is available for download. The screenshot below shows a simple TCP Application Client Terminal in action.
Architecture of TCP Application
TcpAppServer (TCP Application Server) and TcpAppClient (TCP Application Client) are derived from TcpServer and TcpClient respectively which is a general TCP communication object.
Getting Started with TCP Application Server
- Install NuGet Package
CodeArtEng.Tcp to project. - Create an object of
TcpAppServer. - (Optional) Define welcome message which returns to client on connect.
- (Optional) Subscribe to
ClientConnected and ClientDisconnected event. - Start server.
- Server shall be stopped and disposed on application exit to release executing thread.
AppServer = new TcpAppServer(this);
AppServer.WelcomeMessage = "Welcome to TCP Application Server";
AppServer.ClientConnected += AppServer_ClientConnected;
AppServer.ClientDisconnected += AppServer_ClientDisconnected;
AppServer.Start(12000);
AppServer.Stop();
AppServer.Dispose();
Register Application Specific Command
- Command can be registered to server application with
RegisterCommand method. - Optional and Mandatory argument can be added to command as
TcpAppParameter object. - Each command shall associate with a callback function which defined its implementation.
AppServer.RegisterCommand("CustomFunction",
"Dummy Custom Function", customFunctionCallback);
AppServer.RegisterCommand("CustomFunction2", "Dummy Custom Function with Parameter",
customFunction2Callback,
new TcpAppParameter("P1", "Parameter 1"),
new TcpAppParameter("P2", "Parameter 2, optional.", "10"));
Working with Plugin
Plugin provides great extensibility to application where new feature and components can be added at a later stage. TCP Application Protocol is equipped with capability to handle and extend command set in plugin components as well as instantiate object in server application, let’s see how.
Preparation on Plugin Components
- Install NuGet Package
CodeArtEng.Tcp to plugin project. - Implement
ITcpAppServerPlugin interface on plugin class. - Create plugin implementation class with
TcpAppServerPlugin as base class or private object in plugin class. The TcpAppServerPlugin class will interact with TcpAppServer for command registration and execution. - Register commands from plugin components to host application using
TcpAppServerPlugin object. - Make sure
ExecutePluginCommand and ShowHelp methods are calling the corresponding method in TcpAppServerPlugin object.
public class TcpAppServerSamplePlugin : ITcpAppServerPlugin
{
private readonly TcpAppServerPlugin TcpAppPlugin;
public string Name { get; set; }
public string Alias { get => Name; set => Name = value; }
public void ExecutePluginCommand(TcpAppInputCommand sender)
{
TcpAppPlugin.ExecutePluginCommand(sender);
}
public TcpAppServerSamplePlugin()
{
TcpAppPlugin = new TcpAppServerPlugin();
TcpAppPlugin.RegisterCommand("PluginCommand1", "Plugin Command 1",
delegate (TcpAppInputCommand sender)
{
sender.Status = TcpAppCommandStatus.OK;
sender.OutputMessage = "Command 1 Executed!";
});
}
public bool DisposeRequest() { return true; }
public void ShowHelp(TcpAppInputCommand sender)
{
TcpAppPlugin.ShowHelp(sender);
}
}
Add Plugin Component to Server Application
On server application, include plugin component object to TcpAppServer upon created with AddPlugin method. It’s important to ensure the Alias name for each plugin component is unique. This method is designed for object which instantiates by server application.
Alternatively, plugin object can be instantiated by client application. To do so, the allowed plugin type must be first registered with TcpAppServer using RegisterPluginType method. Only ITcpAppServerPlugin object type is allowed to register.
TcpAppServerSamplePlugin SamplePlugin = new TcpAppServerSamplePlugin();
AppServer.RegisterPluginType("SamplePlugin", typeof(TcpAppServerSamplePlugin));
Commands registered with plugin object can be retrieved by sending Help <Alias> command from client to server. To execute command in plugin object, just send Execute <Alias> <Command Keyword> [Parameters].
Managing Connected Clients
If your server applications have no restriction on numbers of client connected at a time, nothing needs to be done. Otherwise, you may use the MaxClients property to limit number of connected clients. Alternatively, we can also subscribe to ClientConnected event to accept or reject an incoming connection.
History
- 8th September, 2019 - First release
