WebSockets in .NET

By the end of this lesson you'll understand how a WebSocket upgrades a one-shot HTTP request into a persistent, two-way channel — and you'll be able to accept a connection in ASP.NET Core, run a receive loop that reads and sends framed messages, close the connection cleanly, and decide when to reach for raw WebSockets instead of SignalR.

1. Full-Duplex & the Upgrade Handshake

Full-duplex means both ends can send at the same moment, like two people on a phone call talking over each other. Plain HTTP is request/response: the client speaks, the server replies, done. A WebSocket starts as a normal HTTP GET carrying an Upgrade: websocket header; the server answers 101 Switching Protocols, and from that point the same TCP connection is a raw two-way pipe. In ASP.NET Core you turn this on with app.UseWebSockets(), then complete the handshake with AcceptWebSocketAsync().

Raw WebSocket and ASP.NET Core code can't run in the in-page editor — there's no web server or browser here — so read these worked examples and run them in a real ASP.NET Core project. The runnable 🎯 Your Turn exercises further down model the same message loop in plain C# that does run here.

using System.Net.WebSockets;
using System.Text;

// Program.cs — turn on WebSocket support, then accept connections.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// 1) UseWebSockets() adds the middleware that understands the HTTP
//    "Upgrade" request a browser sends to start a WebSocket.
app.UseWebSockets(new WebSocketOptions
{
    // Heartbeat: send a ping every 30s so dead connections are noticed.
    KeepAliveInterval = TimeSpan.FromSeconds(30)
});

app.Map("/ws", async (HttpContext context) =>
{
    // 2) Only real WebSocket upgrade requests get accepted.
    //    A normal browser GET is NOT a WebSocket request.
    if (!context.WebSockets.IsWebSocketRequest)
    {
        context.Response.StatusCode = 400;   // Bad Request
        return;
    }

    // 3) AcceptWebSocketAsync completes the upgrade handshake and hands
    //    you a live, full-duplex WebSocket. 'using' disposes it at the end.
    using WebSocket socket = await context.WebSockets.AcceptWebSocketAsync();
    Console.WriteLine("Client connected — channel is now open both ways.");
});

app.Run();

Client connected — channel is now open both ways.

2. Message Framing & the Receive Loop

WebSocket data travels in frames. Each frame is labelled text (WebSocketMessageType.Text, UTF-8) or binary (WebSocketMessageType.Binary, raw bytes — files, images, protobuf). A third type, Close, is a control frame that means "I'm hanging up." Your server runs a receive loop: while the socket is open, ReceiveAsync reads the next frame into a buffer and SendAsync writes one back. A big message can span several frames — result.EndOfMessage tells you when the last chunk has arrived.

app.Map("/ws", async (HttpContext context) =>
{
    if (!context.WebSockets.IsWebSocketRequest) { context.Response.StatusCode = 400; return; }
    using WebSocket socket = await context.WebSockets.AcceptWebSocketAsync();

    // A reusable buffer to read message bytes into. Messages bigger than
    // this arrive in several chunks — you stitch them back together.
    var buffer = new byte[4096];

    // The RECEIVE LOOP: keep reading frames while the socket is open.
    while (socket.State == WebSocketState.Open)
    {
        WebSocketReceiveResult result = await socket.ReceiveAsync(
            new ArraySegment<byte>(buffer), CancellationToken.None);

        // The peer asked to close — run the close handshake and stop.
        if (result.MessageType == WebSocketMessageType.Close)
        {
            await socket.CloseAsync(WebSocketCloseStatus.NormalClosure,
                "Bye", CancellationToken.None);
            break;
        }

        // Decode the text frame, then send the same text straight back.
        string text = Encoding.UTF8.GetString(buffer, 0, result.Count);
        Console.WriteLine($"Received: {text}");

        byte[] reply = Encoding.UTF8.GetBytes($"Echo: {text}");
        await socket.SendAsync(new ArraySegment<byte>(reply),
            WebSocketMessageType.Text,
            endOfMessage: true,        // this frame is a complete message
            CancellationToken.None);
    }

    Console.WriteLine("Loop ended — connection closed.");
});

Client connected — channel is now open both ways.
Received: hello
Received: world
Loop ended — connection closed.

Notice the shape: read a frame → decide what it is → send a response → loop. That single loop is the heart of every WebSocket endpoint. Now model it yourself in code that runs right here.

Your turn. A real server reads frames off the network one at a time; below, a Queue<string> stands in for those incoming frames. Loop over them and echo each one back uppercased, the way SendAsync would push a reply. Fill in the three ___ blanks, then run it.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        // 🎯 YOUR TURN — model the receive loop with a Queue of "frames".
        // A real server reads one frame at a time off the network; here a
        // Queue<string> stands in for the incoming frames, in order.

        Queue<string> incoming = new Queue<string>();
        incoming.Enqueue("hello");
        incoming.Enqueue("world");
        incoming.Enqueue("websockets");

        // 1) Loop w
...

3. The Close Handshake

A WebSocket shouldn't just vanish — both sides agree to hang up. When the peer sends a Close frame, you reply with CloseAsync, passing a close code and a short reason, then break out of the receive loop. The close code is a number that says why the connection ended — 1000 for a normal, expected close, others for errors. Always handle the Close frame; if you don't, the loop reads forever and the connection leaks.

Now handle the close signal yourself. In the queue below, one frame is the literal "close" control message. When you read it, print a closing line and break out of the loop so the frames queued after it are never processed. Fill in the two ___ blanks:

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        // 🎯 YOUR TURN — handle the CLOSE control message.
        // Most frames carry text. One special frame, "close", is a control
        // signal: when you see it, run the close handshake and STOP reading.

        Queue<string> incoming = new Queue<string>();
        incoming.Enqueue("ready");
        incoming.Enqueue("steady");
        incoming.Enqueue("close");      // the close control frame
...

SignalR     = batteries included  (reconnect, groups, fallbacks, serialisation)
Raw WS      = bare metal control  (your protocol, your bytes, your rules)

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        // 🎯 MINI-CHALLENGE: a ping/pong protocol over the receive loop
        // The frames are already queued for you. Write the loop yourself:
        //   1. Read each frame off the queue with Dequeue().
        //   2. If the frame is "ping", reply "pong".
        //   3. If the frame is "bye", print "Goodbye!" and STOP the loop.
        //   4. Any other frame: echo it back unchanged ("Echo: <fr
...