SocketIOClient 4.0.4

Socket.IO-client for .NET

Languages: ｜ English

An elegant socket.io client for .NET, it supports socket.io server v2/v3/v4, and has implemented http polling and websocket.

👁 Build Status
👁 NuGet
👁 NuGet

Table of Contents

• Quick start
  • Options
  • Ack
  • Binary messages
  • Serializer
  • Self-signed certificate
  • Proxy
  • Logging
• Development
• Change log
• Thanks

Quick start

Connect to a Socket.IO server to receive and emit events.

var client = new SocketIO(new Uri("http://localhost:11400"));

client.On("event", ctx =>
{
 // RawText: ["event","Hello World!", 1, {\"Name\":\"Alice\",\"Age\":18}]
 // The first element in the array is the event name,
 // and the subsequent elements are the data carried with the event.
 Console.WriteLine(ctx.RawText);

 // Use index 0 to access the first item in the data payload, which is of type string.
 var message = ctx.GetValue<string>(0)!;
 Console.WriteLine(message); // Hello World!

 // Use index 1 to access the second data item in the payload. The data type is int.
 var id = ctx.GetValue<int>(1);
 Console.WriteLine(id); // 1

 // Use index 2 to access the third data item in the payload. The data type is User.
 var user = ctx.GetValue<User>(2)!;
 Console.WriteLine($"Name: {user.Name}, Age: {user.Age}"); // Name: Alice, Age: 18

 return Task.CompletedTask;
});

Options

An overload is provided here to allow custom configuration of the options.

var client = new SocketIO(new Uri("http://localhost:11400"), new SocketIOOptions
{
 Query = new NameValueCollection
 {
 ["user"] = "Alice"
 },
 // ...
});

Ack

Emit an event with a callback function. After the server finishes processing, it will invoke the client’s callback function and pass back the relevant data.

Client

await client.EmitAsync("hi", ["Hi, I'm Client"], ack =>
{
 Console.WriteLine(ack.RawText);
 // RawText: ["Hi, I'm Client","Hi, I'm Server"]

 var message1 = ack.GetValue<string>(0)!;
 Console.WriteLine(message1); // Hi, I'm Client

 var message2 = ack.GetValue<string>(1)!;
 Console.WriteLine(message2); // Hi, I'm Server

 return Task.CompletedTask;
});

Server

socket.on('hi', (m1, fn) => {
 fn(m1, 'Hi, I\'m Server');
});

Listen for an event that includes a callback function. After the client finishes processing, it will send the relevant data back to the server. Once the server receives the data, it will execute its callback function.

Client

client.On("add", async ctx =>
{
 var a = ctx.GetValue<int>(0);
 var b = ctx.GetValue<int>(1);
 var c = a + b;

 await ctx.SendAckDataAsync([c]);
});

Server

socket.emit('add', 1, 2, c => {
 console.log(c); // 3
});

Binary messages

Send and receive complex data types that include byte[]. By default, System.Text.Json is used for JSON serialization.

class FileDTO
{
 [JsonPropertyName("name")]
 public string Name { get; set; }

 [JsonPropertyName("mimeType")]
 public string MimeType { get; set; }

 [JsonPropertyName("bytes")]
 public byte[] Bytes { get; set; }
}

The above example uses [JsonPropertyName] to customize JSON property names. Global configuration via JsonSerializerOptions is also supported.

await client.EmitAsync("1:emit", [
 new FileDTO
 {
 Name = "template.html",
 MimeType = "text/html",
 Bytes = Encoding.UTF8.GetBytes("<div>test</div>")
 }
]);

client.On("new files", ctx =>
{
 // RawText: ["new files", {"name":"template.html","mimeType":"text/html","bytes":{"_placeholder":true,"num":0}}]
 var result = ctx.GetValue<FileDTO>();
 Console.WriteLine(Encoding.UTF8.GetString(result.Bytes))
});

Serializer

By default, System.Text.Json is used for serialization and deserialization. If you want to configure JsonSerializerOptions:

var client = new SocketIO(new Uri("http://localhost:11400"), services =>
{
 services.AddSystemTextJson(new JsonSerializerOptions
 {
 PropertyNamingPolicy = JsonNamingPolicy.CamelCase
 });
});

Of course, if you prefer to use Newtonsoft.Json, you need to install SocketIOClient.Serializer.NewtonsoftJson.

var client = new SocketIO(new Uri("http://localhost:11400"), services =>
{
 services.AddNewtonsoftJson(new JsonSerializerSettings());
});

Self-signed certificate

If your socket.io server uses a certificate issued by a trusted CA, you should not use these APIs to avoid potential security risks.

However, if your socket.io server uses a self-signed certificate, you may need to customize the certificate validation logic:

Http Polling

var client = new SocketIO(new Uri("http://localhost:11400"), services =>
{
 services.AddSingleton<HttpClient>(_ =>
 {
 var handler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (s, cert, chain, policyError) =>
 {
 var isValid = ...
 return isValid;
 }
 };

 return new HttpClient(handler);
 });
});

WebSocket

var client = new SocketIO(new Uri("http://localhost:11400"), services =>
{
 services.AddSingleton(new WebSocketOptions
 {
 RemoteCertificateValidationCallback = (s, cert, chain, policyError) =>
 {
 var isValid = ...
 return isValid;
 };
 });
});

Notes:

• By default, the client communicates with the server using polling first. If the server supports WebSocket, the connection will be upgraded to a WebSocket channel. In this scenario, you may need to configure CertificateValidationCallback for both transports.
• WebSocketOptions also exists in System.Net.WebSockets (.NET), which does not have a RemoteCertificateValidationCallback property and will cause a compile error. Make sure you're using SocketIOClient.Protocol.WebSocket.WebSocketOptions, either via an explicit using SocketIOClient.Protocol.WebSocket; or by using the fully qualified name.

Proxy

In some network environments, a proxy must be configured in order to communicate with the server. Proxy can also be used for development and debugging purposes to capture and inspect the entire interaction.

Http Polling

var client = new SocketIO(new Uri("http://localhost:11400"), services =>
{
 services.AddSingleton<HttpClient>(_ =>
 {
 var handler = new HttpClientHandler
 {
 Proxy = new WebProxy(proxyUrl),
 UseProxy = true
 };

 return new HttpClient(handler);
 });
});

WebSocket

var client = new SocketIO(new Uri("http://localhost:11400"), services =>
{
 services.AddSingleton(new WebSocketOptions
 {
 Proxy = new WebProxy(proxyUrl)
 });
});

Note: By default, the client communicates with the server using polling first. If the server supports WebSocket, the connection will be upgraded to a WebSocket channel. In this case, you may need to configure a proxy for both transports.

Logging

To further obtain internal logs for observing its internal behavior, you can use the following approach:

var client = new SocketIO(new Uri("http://localhost:11400"), new SocketIOOptions(), services =>
{
 services.AddLogging(builder =>
 {
 builder.SetMinimumLevel(LogLevel.Trace);
 builder.AddConsole();
 });
});

Here, Microsoft.Extensions.Logging.Console is used as the logging provider. For more logging providers, please refer to: Third-party logging providers

Development

This library currently follows the software testing pyramid model, with 95% unit test coverage. You can view the coverage details in the Code Coverage section of the Azure DevOps interface.

If you need to run the integration tests locally:

cd socket.io-client-csharp/tests/socket.io

npm run install-all # Install the dependencies. This only needs to be done once.

npm run start # Start socket.io server for integration testing

Change log

[4.0.4] - 2026-05-22

Bugfix

• Fix the issues with TaskCompletionSource.SetResult()
• Fix the issues with TaskScheduler.UnobservedTaskException

After that, you can run the integration tests.

Thanks

<img src="https://socket.io/images/logo.svg" width=100px/> <img src="https://github.com/darrachequesne.png" width=100px/>

Thank socket.io and darrachequesne for sponsoring the project on Open Collective.

<img src="https://resources.jetbrains.com/storage/products/company/brand/logos/Rider_icon.svg" width=100px/>

We would like to thank JetBrains for supporting the project with free licenses of their fantastic tools.