Home

Awesome

supersimpletcp

SuperSimpleTcp

Simple wrapper for TCP client and server in C# with SSL support

NuGet Version NuGet

SuperSimpleTcp provides simple methods for creating your own TCP-based sockets application, enabling easy integration of connection management, sending, and receiving data.

I would highly encourage you to fully understand what message framing is and why it's important before using this library: https://blog.stephencleary.com/2009/04/message-framing.html

New in v3.0.x

Special Thanks

A special thanks to the community of people that have contributed to or otherwise improved this project!

@tinohager @u1035 @cmeeren @pha3z @opnop @kopkarmecoindo @simonhaines @matt1tk @lukeacat @exergist @maynardsi @sector13371 @loganwoodxyz @jwfxpr @IanPNewson @EGirardi @redrabbit007 @eatyouroats @joreg @CetinOzdil @tautvilis @ATS-CE @TheNybbler @huangjia2107 @zllvm @Energiz0r @Espen-Kalhagen-Element-Logic @MarkBreedveld @QTPah @olifer @KimEoJin @BrandenEK @Somfic

Help or Feedback

Need help or have feedback? Please file an issue here!

Simple Examples

Server Example

using SuperSimpleTcp;

void Main(string[] args)
{
  // instantiate
  SimpleTcpServer server = new SimpleTcpServer("127.0.0.1:9000");

  // set events
  server.Events.ClientConnected += ClientConnected;
  server.Events.ClientDisconnected += ClientDisconnected;
  server.Events.DataReceived += DataReceived;

  // let's go!
  server.Start();

  // once a client has connected...
  server.Send("[ClientIp:Port]", "Hello, world!");
  Console.ReadKey();
}

static void ClientConnected(object sender, ConnectionEventArgs e)
{
  Console.WriteLine($"[{e.IpPort}] client connected");
}

static void ClientDisconnected(object sender, ConnectionEventArgs e)
{
  Console.WriteLine($"[{e.IpPort}] client disconnected: {e.Reason}");
}

static void DataReceived(object sender, DataReceivedEventArgs e)
{
  Console.WriteLine($"[{e.IpPort}]: {Encoding.UTF8.GetString(e.Data.Array, 0, e.Data.Count)}");
}

Client Example

using SuperSimpleTcp;

void Main(string[] args)
{
  // instantiate
  SimpleTcpClient client = new SimpleTcpClient("127.0.0.1:9000");

  // set events
  client.Events.Connected += Connected;
  client.Events.Disconnected += Disconnected;
  client.Events.DataReceived += DataReceived;

  // let's go!
  client.Connect();

  // once connected to the server...
  client.Send("Hello, world!");
  Console.ReadKey();
}

static void Connected(object sender, ConnectionEventArgs e)
{
  Console.WriteLine($"*** Server {e.IpPort} connected");
}

static void Disconnected(object sender, ConnectionEventArgs e)
{
  Console.WriteLine($"*** Server {e.IpPort} disconnected"); 
}

static void DataReceived(object sender, DataReceivedEventArgs e)
{
  Console.WriteLine($"[{e.IpPort}] {Encoding.UTF8.GetString(e.Data.Array, 0, e.Data.Count)}");
}

Connect With Retries

The ConnectWithRetries method on SimpleTcpClient can be used instead of Connect to continually attempt to establish connections with the server for a given period of time. Like Connect, ConnectWithRetries will throw a TimeoutException if it is unable to successfully establish a connection.

client.ConnectWithRetries(10000); // try for up to 10000 milliseconds

Additional Configuration Options

Both SimpleTcpClient and SimpleTcpServer have settable values for:

SimpleTcpServer also has:

Additionally, both SimpleTcpClient and SimpleTcpServer offer a statistics object under SimpleTcpClient.Statistics and SimpleTcpServer.Statistics. These values (other than start time and uptime) can be reset using the Statistics.Reset() API.

Local vs External Connections

IMPORTANT

Testing with SSL

A certificate named simpletcp.pfx is provided for simple testing. It should not expire for a really long time. It's a self-signed certificate and you should NOT use it in production. Its export password is simpletcp.

Disconnection Handling

The project TcpTest (https://github.com/jchristn/TcpTest) was built specifically to provide a reference for SuperSimpleTcp to handle a variety of disconnection scenarios. The disconnection tests for which SimpleTcp is evaluated include:

Test caseDescriptionPass/Fail
Server-side disposeGraceful termination of all client connectionsPASS
Server-side client removalGraceful termination of a single clientPASS
Server-side terminationAbrupt termination due to process abort or CTRL-CPASS
Client-side disposeGraceful termination of a client connectionPASS
Client-side terminationAbrupt termination due to a process abort or CTRL-CPASS
Network interface downNetwork interface disabled or cable removedPartial (see below)

Additionally, as of v2.1.0, support for TCP keepalives has been added to SimpleTcp, primarily to address the issue of a network interface being shut down, the cable unplugged, or the media otherwise becoming unavailable. It is important to note that keepalives are supported in .NET Core and .NET Framework, but NOT .NET Standard. As of this release, .NET Standard provides no facilities for TCP keepalives.

TCP keepalives are disabled by default. To enable them:

server.Keepalive.EnableTcpKeepAlives = true;
server.Keepalive.TcpKeepAliveInterval = 5;      // seconds to wait before sending subsequent keepalive
server.Keepalive.TcpKeepAliveTime = 5;          // seconds to wait before sending a keepalive
server.Keepalive.TcpKeepAliveRetryCount = 5;    // number of failed keepalive probes before terminating connection

Some important notes about TCP keepalives:

Running under Mono

.NET Core is the preferred environment for cross-platform deployment on Windows, Linux, and Mac. For those that use Mono, SimpleTcp should work well in Mono environments. It is recommended that you execute the containing EXE using --server and after using the Mono Ahead-of-Time Compiler (AOT).

mono --aot=nrgctx-trampolines=8096,nimt-trampolines=8096,ntrampolines=4048 --server myapp.exe
mono --server myapp.exe

Version History

Please refer to CHANGELOG.md.