websocket-sharp: RFC 6455 WebSocket Client and Server for .NET and Unity

What websocket-sharp Provides and Who Uses It

WebSocket is a protocol defined in RFC 6455 that provides full-duplex communication over a single TCP connection, initiated by an HTTP upgrade handshake. The .NET ecosystem has had multiple generations of WebSocket support: System.Net.WebSockets arrived with .NET 4.5 for client use and was expanded in later versions, but .NET Framework 3.5 and Mono environments predated it.

websocket-sharp fills the gap. It targets .NET Framework 3.5 and any compatible environment including Mono, provides both client and server in one assembly, and supports RFC 6455 fully. The README lists what it supports: both WebSocket client and server, the per-message compression extension (RFC 7692), secure connections (TLS/SSL), HTTP authentication, query strings, origin headers, cookies, user headers, and HTTP proxy tunneling.

The most common use case beyond standard .NET development is Unity game development. Unity runs on Mono and has limited built-in WebSocket support. The README explicitly documents how to add websocket-sharp.dll to a Unity project (by placing it in Assets/Plugins in the Unity Editor), which indicates this is a well-known use case for the library.

websocket-sharp compiles to a single assembly, websocket-sharp.dll. The build is done with MonoDevelop using websocket-sharp.sln.

WebSocket Client: Events and Connection Lifecycle

The client API centers on the WebSocket class in the WebSocketSharp namespace. You instantiate it with the WebSocket URL, attach event handlers, connect, send data, and close:

using WebSocketSharp;

var ws = new WebSocket ("ws://example.com");
ws.OnMessage += (sender, e) => Console.WriteLine (e.Data);
ws.Connect ();
ws.Send ("BALUS");
ws.Close ();

The WebSocket class implements System.IDisposable, so you can use it in a using statement. When the control flow leaves the using block, the connection closes with status code 1001 (going away).

The four events on the WebSocket class are: OnOpen fires when the connection is established; OnMessage fires when data arrives; OnError fires when an error occurs; OnClose fires when the connection closes. Each passes a typed event arguments object.

For OnMessage, the MessageEventArgs object has IsText and IsBinary properties to distinguish message types, with e.Data returning a string for text messages and e.RawData returning a byte[] for binary messages. To receive ping events through OnMessage, set ws.EmitOnPing = true; then e.IsPing is true for pings.

Sending supports multiple overloads: WebSocket.Send(string), Send(byte[]), Send(System.IO.FileInfo), and Send(System.IO.Stream, int). The async variants are WebSocket.ConnectAsync(), SendAsync(data, completed), and CloseAsync().

Installing websocket-sharp

The simplest installation path is NuGet. The package is available on the NuGet Gallery but is still marked as a prerelease version. Install it from the Package Manager Console:

PM> Install-Package WebSocketSharp -Pre

The -Pre flag is required because the package does not have a stable release version; omitting it will result in the package manager not finding a version to install.

Alternatively, build websocket-sharp from source using MonoDevelop. Open websocket-sharp.sln and run the build for the websocket-sharp project with any of the available configurations, such as Debug. The output is websocket-sharp.dll in the bin/Debug or bin/Release directory.

For Unity projects, add websocket-sharp.dll to any folder in the Assets directory. The README specifically mentions Assets/Plugins as the conventional location. Place it there in the Unity Editor and it becomes available to all C# scripts in the project.

Self-building is also necessary if you need to modify the library, since the NuGet prerelease may not track the latest master branch commits.

WebSocket Server: Behaviors and Service Hosts

The server side uses a behavior class model. You define a class that inherits WebSocketBehavior, override the event methods you care about (OnMessage, OnOpen, OnClose, OnError), and register it with a WebSocketServer or HttpServer.

WebSocketBehavior subclasses are registered at a path. Multiple behaviors can coexist on the same server, each handling a different path. The host manages the connection lifecycle; your behavior class receives events when clients connect, send messages, or disconnect.

The server supports TLS via WebSocketServer or HttpServer with an SSL configuration. HTTP authentication can be added to require clients to authenticate before establishing a WebSocket connection. The query string, Origin header, cookies, and custom user headers are accessible within the behavior if you need to inspect them during the handshake.

The README documents HTTP proxy support for the client side: you can configure a WebSocket client to connect through an HTTP proxy server. This is useful in enterprise environments where outbound WebSocket connections must go through a proxy.

websocket-sharp vs System.Net.WebSockets

System.Net.WebSockets is the WebSocket implementation built into the .NET standard library. On .NET Core 2.1 and later, and on .NET 5 and later, it provides both client (ClientWebSocket) and server-side integration through ASP.NET Core. On .NET Framework, the client class was available from 4.5, but the server side required IIS or HttpListener integration rather than a standalone server class.

websocket-sharp's distinction is its target: .NET Framework 3.5, Mono, and Unity, where System.Net.WebSockets is either unavailable or incomplete. It also provides a standalone WebSocket server that does not depend on IIS or ASP.NET Core, which is relevant for embedded applications, game servers, and other contexts where you want a self-contained WebSocket host without an HTTP framework.

For new projects on .NET 5 or later, System.Net.WebSockets is the natural first choice because it requires no additional dependency. websocket-sharp is the right choice when the runtime target requires .NET Framework 3.5 or Mono compatibility, or when Unity's Mono runtime rules out the standard library option.

Prerelease Status, Branches, and Maintenance

The NuGet package for websocket-sharp is still marked as a prerelease. The README does not document a version number or a roadmap for a stable release. The master branch is designated for production releases. Two other branches exist: hybi-00 for an older draft of the WebSocket protocol (draft-ietf-hybi-thewebsocketprotocol-00) and draft75 for an even older draft (draft-hixie-thewebsocketprotocol-75). Both are marked as no longer maintained.

The repository has no GitHub releases. If you add the NuGet package to a project, pin the version explicitly to avoid picking up unexpected changes when the package is updated.

The last push to the repository was on 2026-09-07. The Example, Example2, and Example3 directories in the repository contain sample projects that demonstrate the client and server APIs.

websocket-sharp is MIT-licensed. The source code is in the websocket-sharp/ directory of the repository, alongside the solution file websocket-sharp.sln.

Editorial conclusion

websocket-sharp is a practical choice for .NET Framework 3.5 and Mono projects that need WebSocket support without taking a newer runtime dependency, and for Unity developers who need to add WebSocket capability to a game. Teams on .NET 5 or later should evaluate System.Net.WebSockets first, since it is part of the standard library and requires no additional dependency. The NuGet package is still marked prerelease, so pin the version explicitly if you add it to a project. The last push to the repository was on 2026-09-07.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. sta/websocket-sharp on GitHub