{"id":13730899,"url":"https://github.com/Marfusios/websocket-client","last_synced_at":"2025-05-08T03:32:10.584Z","repository":{"id":37484655,"uuid":"159722346","full_name":"Marfusios/websocket-client","owner":"Marfusios","description":"🔧 .NET/C# websocket client library","archived":false,"fork":false,"pushed_at":"2024-06-19T14:14:39.000Z","size":563,"stargazers_count":692,"open_issues_count":60,"forks_count":127,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-11-02T16:39:23.452Z","etag":null,"topics":["client","dotnet-core","dotnet-standard","websocket","websocket-client","websockets","websockets-client"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Marfusios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-11-29T20:18:43.000Z","updated_at":"2024-11-02T12:13:04.000Z","dependencies_parsed_at":"2024-01-09T11:17:27.338Z","dependency_job_id":null,"html_url":"https://github.com/Marfusios/websocket-client","commit_stats":{"total_commits":81,"total_committers":16,"mean_commits":5.0625,"dds":0.2098765432098766,"last_synced_commit":"638cf7fc080cbe48fbb975be9c9b5fa746ab068f"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marfusios%2Fwebsocket-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marfusios%2Fwebsocket-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marfusios%2Fwebsocket-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marfusios%2Fwebsocket-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Marfusios","download_url":"https://codeload.github.com/Marfusios/websocket-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224695777,"owners_count":17354478,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","dotnet-core","dotnet-standard","websocket","websocket-client","websockets","websockets-client"],"created_at":"2024-08-03T02:01:21.140Z","updated_at":"2024-11-14T21:31:46.753Z","avatar_url":"https://github.com/Marfusios.png","language":"C#","readme":"![Logo](https://raw.githubusercontent.com/Marfusios/websocket-client/master/websocket-logo-modern.png)\n# Websocket .NET client [![NuGet version](https://badge.fury.io/nu/Websocket.Client.svg)](https://www.nuget.org/packages/Websocket.Client) [![Nuget downloads](https://img.shields.io/nuget/dt/Websocket.Client)](https://www.nuget.org/packages/Websocket.Client)\n\nThis is a wrapper over native C# class `ClientWebSocket` with built-in reconnection and error handling. \n\n[Releases and breaking changes](https://github.com/Marfusios/websocket-client/releases)\n\n### License: \n    MIT\n\n### Features\n\n* installation via NuGet ([Websocket.Client](https://www.nuget.org/packages/Websocket.Client))\n* targeting .NET Standard 2.0 (.NET Core, Linux/MacOS compatible) + Standard 2.1, .NET 5 and .NET 6\n* reactive extensions ([Rx.NET](https://github.com/Reactive-Extensions/Rx.NET))\n* integrated logging abstraction ([LibLog](https://github.com/damianh/LibLog))\n* using Channels for high performance sending queue\n\n### Usage\n\n```csharp\nvar exitEvent = new ManualResetEvent(false);\nvar url = new Uri(\"wss://xxx\");\n\nusing (var client = new WebsocketClient(url))\n{\n    client.ReconnectTimeout = TimeSpan.FromSeconds(30);\n    client.ReconnectionHappened.Subscribe(info =\u003e\n        Log.Information($\"Reconnection happened, type: {info.Type}\"));\n\n    client.MessageReceived.Subscribe(msg =\u003e Log.Information($\"Message received: {msg}\"));\n    client.Start();\n\n    Task.Run(() =\u003e client.Send(\"{ message }\"));\n\n    exitEvent.WaitOne();\n}\n```\n\nMore usage examples:\n* integration tests ([link](test_integration/Websocket.Client.Tests.Integration))\n* console sample ([link](test_integration/Websocket.Client.Sample/Program.cs))\n* .net framework sample ([link](test_integration/Websocket.Client.Sample.NetFramework))\n* blazor sample ([link](test_integration/Websocket.Client.Sample.Blazor))\n\n\n**Pull Requests are welcome!**\n\n### Advanced configuration\n\nTo set some advanced configurations, which are available on the native `ClientWebSocket` class, \nyou have to provide the factory method as a second parameter to WebsocketClient. \nThat factory method will be called on every reconnection to get a new instance of the `ClientWebSocket`. \n\n```csharp\nvar factory = new Func\u003cClientWebSocket\u003e(() =\u003e new ClientWebSocket\n{\n    Options =\n    {\n        KeepAliveInterval = TimeSpan.FromSeconds(5),\n        Proxy = ...\n        ClientCertificates = ...\n    }\n});\n\nvar client = new WebsocketClient(url, factory);\nclient.Start();\n```\n\nAlso, you can access the current native class via `client.NativeClient`. \nBut use it with caution, on every reconnection there will be a new instance.\n\n#### Change URL on the fly\n\nIt is possible to change the remote server URL dynamically. Example: \n\n```csharp\nclient.Url = new Uri(\"wss://my_new_url\");;\nawait client.Reconnect();\n```\n\n\n### Reconnecting\n\nA built-in reconnection invokes after 1 minute (default) of not receiving any messages from the server. \nIt is possible to configure that timeout via `communicator.ReconnectTimeout`. \nIn addition, a stream `ReconnectionHappened` sends information about the type of reconnection. \nHowever, 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. \n\nIn the case of a remote server outage, there is a built-in functionality that slows down reconnection requests \n(could be configured via `client.ErrorReconnectTimeout`, the default is 1 minute).\n\nUsually, websocket servers do not keep a persistent connection between reconnections. Every new connection creates a new session. \nBecause of that, you most likely **need to resubscribe to channels/groups/topics** inside `ReconnectionHappened` stream. \n\n```csharp\nclient.ReconnectionHappened.Subscribe(info =\u003e {\n    client.Send(\"{type: subscribe, topic: xyz}\")\n});\n```\n\n\n### Multi-threading\n\nObservables 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: \n\n#### Default behavior\n\nEvery subscription code is called on a main websocket thread. Every subscription is synchronized together. No parallel execution. It will block the receiving thread. \n\n```csharp\nclient\n    .MessageReceived\n    .Where(msg =\u003e msg.Text != null)\n    .Where(msg =\u003e msg.Text.StartsWith(\"{\"))\n    .Subscribe(obj =\u003e { code1 });\n\nclient\n    .MessageReceived\n    .Where(msg =\u003e msg.Text != null)\n    .Where(msg =\u003e msg.Text.StartsWith(\"[\"))\n    .Subscribe(arr =\u003e { code2 });\n\n// 'code1' and 'code2' are called in a correct order, according to websocket flow\n// ----- code1 ----- code1 ----- ----- code1\n// ----- ----- code2 ----- code2 code2 -----\n```\n\n#### Parallel subscriptions \n\nEvery single subscription code is called on a separate thread. Every single subscription is synchronized, but different subscriptions are called in parallel. \n\n```csharp\nclient\n    .MessageReceived\n    .Where(msg =\u003e msg.Text != null)\n    .Where(msg =\u003e msg.Text.StartsWith(\"{\"))\n    .ObserveOn(TaskPoolScheduler.Default)\n    .Subscribe(obj =\u003e { code1 });\n\nclient\n    .MessageReceived\n    .Where(msg =\u003e msg.Text != null)\n    .Where(msg =\u003e msg.Text.StartsWith(\"[\"))\n    .ObserveOn(TaskPoolScheduler.Default)\n    .Subscribe(arr =\u003e { code2 });\n\n// 'code1' and 'code2' are called in parallel, do not follow websocket flow\n// ----- code1 ----- code1 ----- code1 -----\n// ----- code2 code2 ----- code2 code2 code2\n```\n\n #### Parallel subscriptions with synchronization\n\nIn 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: \n\n```csharp\nprivate static readonly object GATE1 = new object();\nclient\n    .MessageReceived\n    .Where(msg =\u003e msg.Text != null)\n    .Where(msg =\u003e msg.Text.StartsWith(\"{\"))\n    .ObserveOn(TaskPoolScheduler.Default)\n    .Synchronize(GATE1)\n    .Subscribe(obj =\u003e { code1 });\n\nclient\n    .MessageReceived\n    .Where(msg =\u003e msg.Text != null)\n    .Where(msg =\u003e msg.Text.StartsWith(\"[\"))\n    .ObserveOn(TaskPoolScheduler.Default)\n    .Synchronize(GATE1)\n    .Subscribe(arr =\u003e { code2 });\n\n// 'code1' and 'code2' are called concurrently and follow websocket flow\n// ----- code1 ----- code1 ----- ----- code1\n// ----- ----- code2 ----- code2 code2 ----\n```\n\n### Async/Await integration\n\nUsing `async/await` in your subscribe methods is a bit tricky. Subscribe from Rx.NET doesn't `await` tasks, \nso it won't block stream execution and cause sometimes undesired concurrency. For example: \n\n```csharp\nclient\n    .MessageReceived\n    .Subscribe(async msg =\u003e {\n        // do smth 1\n        await Task.Delay(5000); // waits 5 sec, could be HTTP call or something else\n        // do smth 2\n    });\n```\n\nThat `await Task.Delay` won't block stream and subscribe method will be called multiple times concurrently. \nIf you want to buffer messages and process them one-by-one, then use this: \n\n```csharp\nclient\n    .MessageReceived\n    .Select(msg =\u003e Observable.FromAsync(async () =\u003e {\n        // do smth 1\n        await Task.Delay(5000); // waits 5 sec, could be HTTP call or something else\n        // do smth 2\n    }))\n    .Concat() // executes sequentially\n    .Subscribe();\n```\n\nIf you want to process them concurrently (avoid synchronization), then use this\n\n```csharp\nclient\n    .MessageReceived\n    .Select(msg =\u003e Observable.FromAsync(async () =\u003e {\n        // do smth 1\n        await Task.Delay(5000); // waits 5 sec, could be HTTP call or something else\n        // do smth 2\n    }))\n    .Merge() // executes concurrently\n    // .Merge(4) you can limit concurrency with a parameter\n    // .Merge(1) is same as .Concat() (sequentially)\n    // .Merge(0) is invalid (throws exception)\n    .Subscribe();\n```\n\nMore info on [Github issue](https://github.com/dotnet/reactive/issues/459).\n\nDon't worry about websocket connection, those sequential execution via `.Concat()` or `.Merge(1)` has no effect on receiving messages. \nIt won't affect receiving thread, only buffers messages inside `MessageReceived` stream. \n\nBut beware of [producer-consumer problem](https://en.wikipedia.org/wiki/Producer%E2%80%93consumer_problem) when the consumer will be too slow. Here is a [StackOverflow issue](https://stackoverflow.com/questions/11010602/with-rx-how-do-i-ignore-all-except-the-latest-value-when-my-subscribe-method-is/15876519#15876519) \nwith an example how to ignore/discard buffered messages and always process only the last one. \n\n\n### Available for help\nI do consulting, please don't hesitate to contact me if you need a paid help  \n([web](http://mkotas.cz/), [nostr](https://snort.social/p/npub1dd668dyr9un9nzf9fjjkpdcqmge584c86gceu7j97nsp4lj2pscs0xk075), \u003cm@mkotas.cz\u003e)\n","funding_links":[],"categories":["C#","WebSocket","NET Conf"],"sub_categories":["GUI - other"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarfusios%2Fwebsocket-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMarfusios%2Fwebsocket-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMarfusios%2Fwebsocket-client/lists"}