Click here to Skip to main content
13,869,161 members
Click here to Skip to main content
Add your own
alternative version


217 bookmarked
Posted 13 Dec 2015
Licenced CPOL

WebSocket Server in C#

, 24 Dec 2017
Rate this:
Please Sign up or sign in to vote.
Web Socket Client and Server implemented in C# for the modern version 13 of the WebSocket protocol

Set WebSocketsCmd as the startup project.


NEW - Complete refactor to target .NetStandard 2.0 (See GitHub link above)

NEW - Better logging for SSL errors

NEW - SSL support added. Secure your connections

NEW - C# client support added. Refactor for a better API

No external libraries. Completely standalone.

A lot of the Web Socket examples out there are for old Web Socket versions and included complicated code (and external libraries) for fall back communication. All modern browsers support at least version 13 of the Web Socket protocol so I'd rather not complicate things with backward compatibility support. This is a bare bones implementation of the web socket protocol in C# with no external libraries involved. You can connect using standard HTML5 JavaScript or the C# client.

This application serves up basic HTML pages as well as handling WebSocket connections. This may seem confusing but it allows you to send the client the HTML they need to make a web socket connection and also allows you to share the same port. However, the HttpConnection is very rudimentary. I'm sure it has some glaring security problems. It was just made to make this demo easier to run. Replace it with your own or don't use it.


There is nothing magical about Web Sockets. The spec is easy to follow and there is no need to use special libraries. At one point, I was even considering somehow communicating with Node.js but that is not necessary. The spec can be a bit fiddly but this was probably done to keep the overheads low. This is my first CodeProject article and I hope you will find it easy to follow. The following links offer some great advice:

Step by step guide:

The official Web Socket spec:

Some useful stuff in C#:

Alternative C# implementations:

Using the Code

When you first run this app, you should get a Windows firewall warning popup message. Just accept the warning and add the automatic firewall rule. Whenever a new app listens on a port (which this app does), you will get this message and it is there to point out nefarious applications potentially sending and receiving unwanted data over your network. All the code is there for you to see so you can trust what's going on in this project.

A good place to put a breakpoint is in the WebServer class in the HandleAsyncConnection function. Note that this is a multithreaded server so you may want to freeze threads if this gets confusing. The console output prints the thread id to make things easier. If you want to skip past all the plumbing, then another good place to start is the Respond function in the WebSocketConnection class. If you are not interested in the inner workings of Web Sockets and just want to use them, then take a look at the OnTextFrame in the ChatWebSocketConnection class. See below.

Implementation of a chat web socket connection is as follows:

internal class ChatWebSocketService : WebSocketService
    private readonly IWebSocketLogger _logger;

    public ChatWebSocketService(NetworkStream networkStream, 
                                TcpClient tcpClient, string header, IWebSocketLogger logger)
        : base(networkStream, tcpClient, header, true, logger)
        _logger = logger;

    protected override void OnTextFrame(string text)
        string response = "ServerABC: " + text;

The factory used to create the connection is as follows:

internal class ServiceFactory : IServiceFactory
    public ServiceFactory(string webRoot, IWebSocketLogger logger)
        _logger = logger;
        _webRoot = webRoot;

    public IService CreateInstance(ConnectionDetails connectionDetails)
        switch (connectionDetails.ConnectionType)
            case ConnectionType.WebSocket:
                // you can support different kinds of web socket connections using a different path
                if (connectionDetails.Path == "/chat")
                    return new ChatWebSocketService(connectionDetails.NetworkStream, 
                       connectionDetails.TcpClient, connectionDetails.Header, _logger);
            case ConnectionType.Http:
                // this path actually refers to the relative location of some html file or image
                return new HttpService(connectionDetails.NetworkStream, 
                                       connectionDetails.Path, _webRoot, _logger);

        return new BadRequestService
                (connectionDetails.NetworkStream, connectionDetails.Header, _logger);

HTML5 JavaScript used to connect:

// open the connection to the Web Socket server
var CONNECTION = new WebSocket('ws://localhost/chat');

// Log messages from the server
CONNECTION.onmessage = function (e) {
CONNECTION.send('Hellow World');

However, you can also write your own test client in C#. There is an example of one in the command line app. Starting the server and the test client from the command line app:

private static void Main(string[] args)
    IWebSocketLogger logger = new WebSocketLogger();
        string webRoot = Settings.Default.WebRoot;
        int port = Settings.Default.Port;

        // used to decide what to do with incoming connections
        ServiceFactory serviceFactory = new ServiceFactory(webRoot, logger);

        using (WebServer server = new WebServer(serviceFactory, logger))
            Thread clientThread = new Thread(new ParameterizedThreadStart(TestClient));
            clientThread.IsBackground = false;
    catch (Exception ex)
        logger.Error(null, ex);

The test client runs a short self test to make sure that everything is fine. Opening and closing handshakes are tested here.

Web Socket Protocol

The first thing to realize about the protocol is that it is, in essence, a basic duplex TCP/IP socket connection. The connection starts off with the client connecting to a remote server and sending HTTP header text to that server. The header text asks the web server to upgrade the connection to a web socket connection. This is done as a handshake where the web server responds with an appropriate HTTP text header and from then onwards, the client and server will talk the Web Socket language.

Server Handshake

Regex webSocketKeyRegex = new Regex("Sec-WebSocket-Key: (.*)");
Regex webSocketVersionRegex = new Regex("Sec-WebSocket-Version: (.*)");

// check the version. Support version 13 and above
const int WebSocketVersion = 13;
int secWebSocketVersion = Convert.ToInt32(webSocketVersionRegex.Match(header).Groups[1].Value.Trim());
if (secWebSocketVersion < WebSocketVersion)
    throw new WebSocketVersionNotSupportedException(string.Format("WebSocket Version {0} not supported.
                Must be {1} or above", secWebSocketVersion, WebSocketVersion));

string secWebSocketKey = webSocketKeyRegex.Match(header).Groups[1].Value.Trim();
string setWebSocketAccept = base.ComputeSocketAcceptString(secWebSocketKey);
string response = ("HTTP/1.1 101 Switching Protocols\r\n"
                    + "Connection: Upgrade\r\n"
                    + "Upgrade: websocket\r\n"
                    + "Sec-WebSocket-Accept: " + setWebSocketAccept);

HttpHelper.WriteHttpHeader(response, networkStream);

NOTE: Don't use Environment.Newline, use \r\n because the HTTP spec is looking for carriage return line feed (two specific ascii characters) and not whatever your environment deems to be equivalent.

This computes the accept string:

/// <summary>
/// Combines the key supplied by the client with a guid and returns the sha1 hash of the combination
/// </summary>
public static string ComputeSocketAcceptString(string secWebSocketKey)
    // this is a guid as per the web socket spec
    const string webSocketGuid = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";

    string concatenated = secWebSocketKey + webSocketGuid;
    byte[] concatenatedAsBytes = Encoding.UTF8.GetBytes(concatenated);
    byte[] sha1Hash = SHA1.Create().ComputeHash(concatenatedAsBytes);
    string secWebSocketAccept = Convert.ToBase64String(sha1Hash);
    return secWebSocketAccept;

Client Handshake

Uri uri = _uri;
WebSocketFrameReader reader = new WebSocketFrameReader();
Random rand = new Random();
byte[] keyAsBytes = new byte[16];
string secWebSocketKey = Convert.ToBase64String(keyAsBytes);

string handshakeHttpRequestTemplate = "GET {0} HTTP/1.1\r\n" +
                                        "Host: {1}:{2}\r\n" +
                                        "Upgrade: websocket\r\n" +
                                        "Connection: Upgrade\r\n" +
                                        "Origin: http://{1}:{2}\r\n" +
                                        "Sec-WebSocket-Key: {3}\r\n" +
                                        "Sec-WebSocket-Version: 13\r\n\r\n";

string handshakeHttpRequest = string.Format(handshakeHttpRequestTemplate, uri.PathAndQuery, uri.Host, uri.Port, secWebSocketKey);
byte[] httpRequest = Encoding.UTF8.GetBytes(handshakeHttpRequest);
networkStream.Write(httpRequest, 0, httpRequest.Length);

Reading and Writing

After the handshake as been performed, the server goes into a read loop. The following two classes convert a stream of bytes to a web socket frame and visa versa: WebSocketFrameReader and WebSocketFrameWriter.

// from WebSocketFrameReader class
public WebSocketFrame Read(Stream stream, Socket socket)
    byte byte1;

        byte1 = (byte) stream.ReadByte();
    catch (IOException)
        if (socket.Connected)
            return null;

    // process first byte
    byte finBitFlag = 0x80;
    byte opCodeFlag = 0x0F;
    bool isFinBitSet = (byte1 & finBitFlag) == finBitFlag;
    WebSocketOpCode opCode = (WebSocketOpCode) (byte1 & opCodeFlag);

    // read and process second byte
    byte byte2 = (byte) stream.ReadByte();
    byte maskFlag = 0x80;
    bool isMaskBitSet = (byte2 & maskFlag) == maskFlag;
    uint len = ReadLength(byte2, stream);
    byte[] payload;

    // use the masking key to decode the data if needed
    if (isMaskBitSet)
        byte[] maskKey = BinaryReaderWriter.ReadExactly(WebSocketFrameCommon.MaskKeyLength, stream);
        payload = BinaryReaderWriter.ReadExactly((int) len, stream);

        // apply the mask key to the payload (which will be mutated)
        WebSocketFrameCommon.ToggleMask(maskKey, payload);
        payload = BinaryReaderWriter.ReadExactly((int) len, stream);

    WebSocketFrame frame = new WebSocketFrame(isFinBitSet, opCode, payload, true);
    return frame;
// from WebSocketFrameWriter class
public void Write(WebSocketOpCode opCode, byte[] payload, bool isLastFrame)
    // best to write everything to a memory stream before we push it onto the wire
    // not really necessary but I like it this way
    using (MemoryStream memoryStream = new MemoryStream())
        byte finBitSetAsByte = isLastFrame ? (byte) 0x80 : (byte) 0x00;
        byte byte1 = (byte) (finBitSetAsByte | (byte) opCode);

        // NB, set the mask flag if we are constructing a client frame
        byte maskBitSetAsByte = _isClient ? (byte)0x80 : (byte)0x00;

        // depending on the size of the length we want to write it as a byte, ushort or ulong
        if (payload.Length < 126)
            byte byte2 = (byte)(maskBitSetAsByte | (byte) payload.Length);
        else if (payload.Length <= ushort.MaxValue)
            byte byte2 = (byte)(maskBitSetAsByte | 126);
            BinaryReaderWriter.WriteUShort((ushort) payload.Length, memoryStream, false);
            byte byte2 = (byte)(maskBitSetAsByte | 127);
            BinaryReaderWriter.WriteULong((ulong) payload.Length, memoryStream, false);

        // if we are creating a client frame then we MUST mack the payload as per the spec
        if (_isClient)
            byte[] maskKey = new byte[WebSocketFrameCommon.MaskKeyLength];
            memoryStream.Write(maskKey, 0, maskKey.Length);

            // mask the payload
            WebSocketFrameCommon.ToggleMask(maskKey, payload);

        memoryStream.Write(payload, 0, payload.Length);
        byte[] buffer = memoryStream.ToArray();
        _stream.Write(buffer, 0, buffer.Length);

NOTE: Client frames MUST contain masked payload data. This is done to prevent primitive proxy servers from caching the data, thinking that it is static HTML. Of course, using SSL gets around the proxy issue but the authors of the protocol chose to enforce it regardless. 

Points of Interest

Problems with Proxy Servers:
Proxy servers which have not been configured to support Web sockets will not work well with them.
I suggest that you use transport layer security (using an SSL certificate) if you want this to work across the wider internet especially from within a corporation.

Using SSL - Secure Web Sockets

To enable ssl in the demo, you need to do these things:

  1. Get a valid signed certificate (usually a .pfx file)
  2. Fill in the CertificateFile and CertificatePassword settings in the application (or better still, modify the GetCertificate function to get your certificate more securely)
  3. Change the port to 443
  4. (for JavaScript client) Change the client.html file to use "wss"instead of "ws" in the web socket URL.
  5. (for command line client) Change the client URL to "wss" instead of "ws".

I suggest that you get the demo chat to work before you attempt to use a JavaScript client since there are many things that can go wrong and the demo exposes more logging information. If you are getting certificate errors (like name mismatch or expiries), then you can always disable the check by making the WebSocketClient.ValidateServerCertificate function always return true.

If you are having trouble creating a certificate, I strongly recommend using LetsEncrypt to get yourself a free certificate that is signed by a proper root authority. You can use this certificate on your localhost (but your browser will give you certificate warnings).


  • Version 1.01 - WebSocket
  • Version 1.02 - Fixed endianness bug with length field
  • Version 1.03 - Major refactor and added support for C# Client
  • Version 1.04 - SSL support added. You can now secure your websocket connections with an SSL certificate
  • Version 1.05 - Bug fixes

What has changed since December 2015

Thanks to all the feedback from the comments below, and after using the protocol in various projects, I have a much better understanding of how it works and have made a more robust version available from nuget - Ninja.WebSockets. Since it targets .NetStandard 2.0 it even works from a cell phone if you use Xamarin! Or linux or OSx. I will continue to monitor this page and please keep the comments coming. However, my main focus will be on the Ninja.WebSockets version which implements a standard WebSocket abstract class (System.Net.WebSockets.WebSocket) that Microsoft has put a lot of thought into. Ninja.WebSockets does a better job at handling errors and closing handshakes. It is also specifically designed to be as lightweight as possible (by being async and using buffer pools) and it will be interesting to see how far it can be pushed on a decent server.


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Dave Haig
Software Developer (Senior)
United Kingdom United Kingdom
Works as a senior software developer in investment banking

You may also be interested in...

Comments and Discussions

QuestionImplementing Basic Authentication on WebSockets Pin
Member 1299735027-Jan-19 23:57
memberMember 1299735027-Jan-19 23:57 
AnswerRe: Implementing Basic Authentication on WebSockets Pin
Dave Haig1-Feb-19 2:22
professionalDave Haig1-Feb-19 2:22 
PraiseRe: Implementing Basic Authentication on WebSockets Pin
Member 129973506-Feb-19 2:11
memberMember 129973506-Feb-19 2:11 
QuestionHow to listen on other than localhost or an ip address? Pin
muharrem10-Sep-18 22:43
membermuharrem10-Sep-18 22:43 
AnswerRe: How to listen on other than localhost or an ip address? Pin
Dave Haig19-Sep-18 4:03
professionalDave Haig19-Sep-18 4:03 
QuestionConnection Pin
Member 129973506-Jul-18 7:02
memberMember 129973506-Jul-18 7:02 
AnswerRe: Connection Pin
Dave Haig9-Aug-18 7:07
professionalDave Haig9-Aug-18 7:07 
AnswerRe: Connection Pin
Member 1299735012-Aug-18 23:41
memberMember 1299735012-Aug-18 23:41 
QuestionPing Pong Disabled Pin
Member 1299735013-Jun-18 2:46
memberMember 1299735013-Jun-18 2:46 
AnswerRe: Ping Pong Disabled Pin
Dave Haig17-Jun-18 15:41
professionalDave Haig17-Jun-18 15:41 
GeneralRe: Ping Pong Disabled Pin
Member 1299735017-Jun-18 22:29
memberMember 1299735017-Jun-18 22:29 
QuestionUse with a Flutter Client Pin
ChrisTitcumb10-Jun-18 17:53
memberChrisTitcumb10-Jun-18 17:53 
AnswerRe: Use with a Flutter Client Pin
Dave Haig17-Jun-18 15:39
professionalDave Haig17-Jun-18 15:39 
Questionsignalr Pin
TrevorWJ28-May-18 13:51
memberTrevorWJ28-May-18 13:51 
AnswerRe: signalr Pin
Dave Haig30-May-18 13:51
professionalDave Haig30-May-18 13:51 
QuestionHow to use SSL certificate for .net core Application Pin
Member 1299735024-May-18 10:32
memberMember 1299735024-May-18 10:32 
AnswerRe: How to use SSL certificate for .net core Application Pin
Dave Haig30-May-18 14:06
professionalDave Haig30-May-18 14:06 
QuestionReally Helpful! Pin
TomcatDowdell9-May-18 8:02
memberTomcatDowdell9-May-18 8:02 
AnswerRe: Really Helpful! Pin
Dave Haig30-May-18 13:41
professionalDave Haig30-May-18 13:41 
QuestionCreating WebAPI over web socket Pin
Member 129973508-May-18 6:41
memberMember 129973508-May-18 6:41 
AnswerRe: Creating WebAPI over web socket Pin
Dave Haig30-May-18 13:56
professionalDave Haig30-May-18 13:56 
QuestionInvoking WebSocket from two different clients Pin
Member 1299735023-Apr-18 0:15
memberMember 1299735023-Apr-18 0:15 
AnswerRe: Invoking WebSocket from two different clients Pin
Dave Haig24-Apr-18 3:33
professionalDave Haig24-Apr-18 3:33 
GeneralRe: Invoking WebSocket from two different clients Pin
Member 1299735025-Apr-18 4:47
memberMember 1299735025-Apr-18 4:47 
QuestionSaving the message in Database Pin
Member 1299735016-Apr-18 2:39
memberMember 1299735016-Apr-18 2:39 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web02 | 2.8.190214.1 | Last Updated 24 Dec 2017
Article Copyright 2015 by Dave Haig
Everything else Copyright © CodeProject, 1999-2019
Layout: fixed | fluid