Websocket.Client 5.0.0

.NET 6.0 .NET Standard 2.1
dotnet add package Websocket.Client --version 5.0.0
NuGet\Install-Package Websocket.Client -Version 5.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Websocket.Client" Version="5.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Websocket.Client --version 5.0.0
#r "nuget: Websocket.Client, 5.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Websocket.Client as a Cake Addin
#addin nuget:?package=Websocket.Client&version=5.0.0

// Install Websocket.Client as a Cake Tool
#tool nuget:?package=Websocket.Client&version=5.0.0

Logo

Websocket .NET client NuGet version Nuget downloads

This is a wrapper over native C# class ClientWebSocket with built-in reconnection and error handling.

Releases and breaking changes

License:

MIT

Features

  • installation via NuGet (Websocket.Client)
  • targeting .NET Standard 2.0 (.NET Core, Linux/MacOS compatible) + Standard 2.1, .NET 5 and .NET 6
  • reactive extensions (Rx.NET)
  • integrated logging abstraction (LibLog)
  • using Channels for high performance sending queue

Usage

var exitEvent = new ManualResetEvent(false);
var url = new Uri("wss://xxx");

using (var client = new WebsocketClient(url))
{
    client.ReconnectTimeout = TimeSpan.FromSeconds(30);
    client.ReconnectionHappened.Subscribe(info =>
        Log.Information($"Reconnection happened, type: {info.Type}"));

    client.MessageReceived.Subscribe(msg => Log.Information($"Message received: {msg}"));
    client.Start();

    Task.Run(() => client.Send("{ message }"));

    exitEvent.WaitOne();
}

More usage examples:

  • integration tests (link)
  • console sample (link)
  • .net framework sample (link)
  • blazor sample (link)

Pull Requests are welcome!

Advanced configuration

To set some advanced configurations, which are available on the native ClientWebSocket class, you have to provide the factory method as a second parameter to WebsocketClient. That factory method will be called on every reconnection to get a new instance of the ClientWebSocket.

var factory = new Func<ClientWebSocket>(() => new ClientWebSocket
{
    Options =
    {
        KeepAliveInterval = TimeSpan.FromSeconds(5),
        Proxy = ...
        ClientCertificates = ...
    }
});

var client = new WebsocketClient(url, factory);
client.Start();

Also, you can access the current native class via client.NativeClient. But use it with caution, on every reconnection there will be a new instance.

Change URL on the fly

It is possible to change the remote server URL dynamically. Example:

client.Url = new Uri("wss://my_new_url");;
await client.Reconnect();

Reconnecting

A built-in reconnection invokes after 1 minute (default) of not receiving any messages from the server. It is possible to configure that timeout via communicator.ReconnectTimeout. In addition, a stream ReconnectionHappened sends information about the type of reconnection. However, if you are subscribed to low-rate channels, you will likely encounter that timeout - higher it to a few minutes or implement ping-pong interaction on your own every few seconds.

In the case of a remote server outage, there is a built-in functionality that slows down reconnection requests (could be configured via client.ErrorReconnectTimeout, the default is 1 minute).

Usually, websocket servers do not keep a persistent connection between reconnections. Every new connection creates a new session. Because of that, you most likely need to resubscribe to channels/groups/topics inside ReconnectionHappened stream.

client.ReconnectionHappened.Subscribe(info => {
    client.Send("{type: subscribe, topic: xyz}")
});

Multi-threading

Observables from Reactive Extensions are single threaded by default. It means that your code inside subscriptions is called synchronously and as soon as the message comes from websocket API. It brings a great advantage of not to worry about synchronization, but if your code takes a longer time to execute it will block the receiving method, buffer the messages and may end up losing messages. For that reason consider to handle messages on the other thread and unblock receiving thread as soon as possible. I've prepared a few examples for you:

Default behavior

Every subscription code is called on a main websocket thread. Every subscription is synchronized together. No parallel execution. It will block the receiving thread.

client
    .MessageReceived
    .Where(msg => msg.Text != null)
    .Where(msg => msg.Text.StartsWith("{"))
    .Subscribe(obj => { code1 });

client
    .MessageReceived
    .Where(msg => msg.Text != null)
    .Where(msg => msg.Text.StartsWith("["))
    .Subscribe(arr => { code2 });

// 'code1' and 'code2' are called in a correct order, according to websocket flow
// ----- code1 ----- code1 ----- ----- code1
// ----- ----- code2 ----- code2 code2 -----
Parallel subscriptions

Every single subscription code is called on a separate thread. Every single subscription is synchronized, but different subscriptions are called in parallel.

client
    .MessageReceived
    .Where(msg => msg.Text != null)
    .Where(msg => msg.Text.StartsWith("{"))
    .ObserveOn(TaskPoolScheduler.Default)
    .Subscribe(obj => { code1 });

client
    .MessageReceived
    .Where(msg => msg.Text != null)
    .Where(msg => msg.Text.StartsWith("["))
    .ObserveOn(TaskPoolScheduler.Default)
    .Subscribe(arr => { code2 });

// 'code1' and 'code2' are called in parallel, do not follow websocket flow
// ----- code1 ----- code1 ----- code1 -----
// ----- code2 code2 ----- code2 code2 code2
Parallel subscriptions with synchronization

In case you want to run your subscription code on the separate thread but still want to follow websocket flow through every subscription, use synchronization with gates:

private static readonly object GATE1 = new object();
client
    .MessageReceived
    .Where(msg => msg.Text != null)
    .Where(msg => msg.Text.StartsWith("{"))
    .ObserveOn(TaskPoolScheduler.Default)
    .Synchronize(GATE1)
    .Subscribe(obj => { code1 });

client
    .MessageReceived
    .Where(msg => msg.Text != null)
    .Where(msg => msg.Text.StartsWith("["))
    .ObserveOn(TaskPoolScheduler.Default)
    .Synchronize(GATE1)
    .Subscribe(arr => { code2 });

// 'code1' and 'code2' are called concurrently and follow websocket flow
// ----- code1 ----- code1 ----- ----- code1
// ----- ----- code2 ----- code2 code2 ----

Async/Await integration

Using async/await in your subscribe methods is a bit tricky. Subscribe from Rx.NET doesn't await tasks, so it won't block stream execution and cause sometimes undesired concurrency. For example:

client
    .MessageReceived
    .Subscribe(async msg => {
        // do smth 1
        await Task.Delay(5000); // waits 5 sec, could be HTTP call or something else
        // do smth 2
    });

That await Task.Delay won't block stream and subscribe method will be called multiple times concurrently. If you want to buffer messages and process them one-by-one, then use this:

client
    .MessageReceived
    .Select(msg => Observable.FromAsync(async () => {
        // do smth 1
        await Task.Delay(5000); // waits 5 sec, could be HTTP call or something else
        // do smth 2
    }))
    .Concat() // executes sequentially
    .Subscribe();

If you want to process them concurrently (avoid synchronization), then use this

client
    .MessageReceived
    .Select(msg => Observable.FromAsync(async () => {
        // do smth 1
        await Task.Delay(5000); // waits 5 sec, could be HTTP call or something else
        // do smth 2
    }))
    .Merge() // executes concurrently
    // .Merge(4) you can limit concurrency with a parameter
    // .Merge(1) is same as .Concat() (sequentially)
    // .Merge(0) is invalid (throws exception)
    .Subscribe();

More info on Github issue.

Don't worry about websocket connection, those sequential execution via .Concat() or .Merge(1) has no effect on receiving messages. It won't affect receiving thread, only buffers messages inside MessageReceived stream.

But beware of producer-consumer problem when the consumer will be too slow. Here is a StackOverflow issue with an example how to ignore/discard buffered messages and always process only the last one.

Available for help

I do consulting, please don't hesitate to contact me if you need a paid help
(web, nostr, m@mkotas.cz)

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (110)

Showing the top 5 NuGet packages that depend on Websocket.Client:

Package Downloads
ZoomNet

ZoomNet is a strongly typed .NET client for Zoom's API.

SlackConnector

SlackConnector initiates an open connection between you and the Slack api servers. SlackConnector uses web-sockets to allow real-time messages to be received and handled within your application.

Hypar.Client

The Hypar client.

Blazor.Ninja.Client.Local The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Blazor.Ninja Local Client Package

Bitfinex.Client.Websocket

Client for Bitfinex and Ethfinex websocket API version 2.0

GitHub repositories (17)

Showing the top 5 popular GitHub repositories that depend on Websocket.Client:

Repository Stars
Richasy/Bili.Uwp
适用于新系统UI的哔哩
openbullet/OpenBullet2
OpenBullet reinvented
LykosAI/StabilityMatrix
Multi-Platform Package Manager for Stable Diffusion
NethermindEth/nethermind
A robust execution client for Ethereum node operators.
LagrangeDev/Lagrange.Core
An Implementation of NTQQ Protocol, with Pure C#, Derived from Konata.Core
Version Downloads Last updated
5.0.0 22,901 9/7/2023
4.7.0 13,645 9/1/2023
4.6.1 263,984 2/23/2023
4.6.0 4,925 2/21/2023
4.5.2 30,272 2/20/2023
4.5.1 253 2/20/2023
4.5.0 367 2/20/2023
4.4.43 708,187 11/21/2021
4.4.42 1,160 11/20/2021
4.4.40 26,668 11/20/2021
4.4.39 672 11/19/2021
4.3.38 175,717 8/31/2021
4.3.36 28,631 8/16/2021
4.3.35 27,736 7/21/2021
4.3.32 47,788 5/24/2021
4.3.30 124,246 2/11/2021
4.3.21 193,661 7/20/2020
4.3.15 71,269 5/13/2020
4.3.14 785 5/12/2020
4.3.12 12,093 4/26/2020
4.2.11 530 4/26/2020
4.2.3 38,483 3/10/2020
4.1.85 17,796 2/14/2020
4.1.83 536 2/14/2020
4.1.82 526 2/14/2020
4.1.81 952 2/14/2020
4.1.79 576 2/14/2020
4.1.78 72,171 1/24/2020
4.1.77 2,829 1/6/2020
4.1.76 7,186 12/18/2019
4.1.75 718 12/14/2019
4.1.74 1,959 12/10/2019
4.1.73 2,342 12/6/2019
4.1.70 600 12/6/2019
4.1.69 587 12/6/2019
4.0.66 1,549 12/5/2019
3.2.61 754 12/4/2019
3.2.59 4,092 11/21/2019
3.2.56 23,503 10/2/2019
3.2.55 522 10/2/2019
3.2.54 514 10/2/2019
3.2.52 617 9/27/2019
3.1.32 988 9/20/2019
3.1.29 1,465 9/19/2019
3.1.28 5,564 8/6/2019
3.1.26 5,094 8/2/2019
3.1.25 5,513 7/24/2019
3.1.24 560 7/24/2019
3.0.23 4,154 6/20/2019
3.0.20 4,358 5/13/2019
3.0.19 1,209 5/2/2019
3.0.18 7,412 3/26/2019
3.0.17 10,685 3/20/2019
3.0.15 1,171 3/12/2019
2.0.10 2,676 2/4/2019
2.0.7 962 2/4/2019
1.0.6 7,534 12/10/2018
1.0.5 1,333 12/7/2018
1.0.4 1,116 12/7/2018
1.0.3 1,182 12/7/2018
1.0.2 957 11/29/2018
1.0.1 1,259 11/29/2018

Enhancements