API WebSocket trong ASP.NET Core rất nhỏ: một middleware, một method AcceptWebSocketAsync, và hai method ReceiveAsync/SendAsync. Phần khó không nằm ở API — nó nằm ở vòng đời kết nối, backpressure, close handshake và việc mở rộng ngang. Bài này viết một endpoint WebSocket đủ nghiêm túc để chạy production, rồi chỉ ra chỗ nào SignalR rẻ hơn nhiều.
Mục lục
Cập nhật 2026
- Middleware nằm trong shared framework. Project ASP.NET Core 10 không cần
dotnet add package Microsoft.AspNetCore.WebSockets;UseWebSocketsvàWebSocketOptionsđã có sẵn. Package chỉ cần cho thư viện nhắmnetstandard2.0. - Overload
Memory<byte>trả vềValueWebSocketReceiveResultvà nhậnMemory<byte>/ReadOnlyMemory<byte>. Đây là API nên dùng; các overloadArraySegmenttrong bài cũ là dạng cũ. - .NET 10 thêm
WebSocketStream— bọcWebSocketthànhStreamđể dùng các API đọc/ghi theo stream thay vì tự quản lý frame. - SSE hạng nhất trong ASP.NET Core 10 (
TypedResults.ServerSentEvents) — nếu nhu cầu chỉ là đẩy một chiều, đừng viết WebSocket.
Handshake, frame, close: mô hình tối thiểu
Một kết nối WebSocket có ba giai đoạn, và mỗi giai đoạn có lỗi riêng:
- Handshake. Client gửi HTTP GET với
Upgrade: websocket. Server trả101 Switching Protocols. Sau thời điểm này, HTTP không còn tồn tại trên kết nối đó. - Frame. Hai bên trao đổi frame text hoặc binary. Một message logic có thể gồm nhiều frame;
EndOfMessagecho biết frame cuối. Frame điều khiển (ping, pong, close) do tầng protocol xử lý, không phải payload của bạn. - Close. Một bên gửi frame close kèm mã trạng thái; bên kia đóng chiều gửi và chờ. Bỏ qua bước này là nguyên nhân phổ biến của lỗi “connection reset” ở client.
Điểm quan trọng: sau handshake, không có request-scoped gì nữa. Không có HttpContext sống theo kết nối để dựa vào, không có model binding, không có middleware nào chạy lại. Bạn tự quản lý vòng đọc, vòng ghi và việc dọn dẹp.
Endpoint tối thiểu, đúng cách
// File: Program.cs
using System.Net.WebSockets;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<ConnectionRegistry>();
var app = builder.Build();
app.UseWebSockets(new WebSocketOptions
{
KeepAliveInterval = TimeSpan.FromSeconds(30)
});
app.MapGet("/ws", async (HttpContext context, ConnectionRegistry registry) =>
{
if (!context.WebSockets.IsWebSocketRequest)
{
context.Response.StatusCode = StatusCodes.Status400BadRequest;
return;
}
using var socket = await context.WebSockets.AcceptWebSocketAsync();
await registry.RunAsync(context, socket, context.RequestAborted);
});
app.Run();
Hai lựa chọn trong đoạn trên đáng giải thích. app.MapGet("/ws", ...) gắn handler vào đúng path và trả về 400 nếu client gọi bằng HTTP thường — UseWebSockets một mình không làm việc đó. Còn KeepAliveInterval = 30s khiến server gửi ping khi kết nối im lặng; mặc định là 2 phút, quá dài so với timeout của nhiều proxy. Ping/pong ở mức giao thức do implementation xử lý, bạn không phải tự viết.
Không đặt UseWebSockets sau UseAuthentication nếu bạn cần chặn handshake bằng xác thực. Middleware WebSocket phải chạy trước để nó thấy được request upgrade; nhưng nếu bạn muốn trả 401 cho handshake không hợp lệ, hãy kiểm tra context.User.Identity?.IsAuthenticated ngay trong handler trước khi gọi AcceptWebSocketAsync.
Vòng đọc: ghép frame và giới hạn kích thước
// File: Transport/Connection.cs
using System.Net.WebSockets;
using System.Text;
public sealed class Connection
{
private const int MaxMessageBytes = 256 * 1024;
private readonly SemaphoreSlim _sendLock = new(1, 1);
private readonly byte[] _buffer = new byte[4096];
public Connection(Guid id, WebSocket socket)
{
Id = id;
Socket = socket;
}
public Guid Id { get; }
public WebSocket Socket { get; }
public async Task ReceiveLoopAsync(Func<Connection, byte[], Task> onMessage, CancellationToken ct)
{
using var message = new MemoryStream();
while (Socket.State == WebSocketState.Open && !ct.IsCancellationRequested)
{
var result = await Socket.ReceiveAsync(_buffer.AsMemory(), ct);
if (result.MessageType == WebSocketMessageType.Close)
{
await Socket.CloseOutputAsync(WebSocketCloseStatus.NormalClosure, null, ct);
return;
}
if (message.Length + result.Count > MaxMessageBytes)
{
await CloseAsync(WebSocketCloseStatus.MessageTooBig, "message too big", ct);
return;
}
message.Write(_buffer.AsSpan(0, result.Count));
if (!result.EndOfMessage)
continue;
var payload = message.ToArray();
message.SetLength(0);
await onMessage(this, payload);
}
}
public async Task SendAsync(ReadOnlyMemory<byte> payload, CancellationToken ct)
{
await _sendLock.WaitAsync(ct);
try
{
await Socket.SendAsync(payload, WebSocketMessageType.Text, endOfMessage: true, ct);
}
finally
{
_sendLock.Release();
}
}
public Task CloseAsync(WebSocketCloseStatus status, string? description, CancellationToken ct) =>
Socket.State is WebSocketState.Open or WebSocketState.CloseReceived
? Socket.CloseAsync(status, description, ct)
: Task.CompletedTask;
}
Ba chi tiết trong đoạn code này là bài học từ lỗi thật:
- Message có thể lớn hơn buffer.
EndOfMessage == falsenghĩa là còn frame nữa; xử lý payload ngay ở frame đầu là bug chỉ xuất hiện khi dữ liệu lớn. - Giới hạn kích thước phải ở server. Không có giới hạn thì một client gửi 100 MB sẽ khiến
MemoryStreamphình theo.WebSocketCloseStatus.MessageTooBig(1009) là mã đúng cho tình huống này. - Gửi song song trên một socket là không hợp lệ. Nếu hai task cùng gọi
SendAsync, hành vi không xác định.SemaphoreSlimở trên là cách rẻ nhất để tuần tự hoá; một hàng đợi có giới hạn cho mỗi connection thì tốt hơn khi bạn broadcast.
Nếu bạn cần đọc/ghi theo kiểu stream (ví dụ JsonSerializer.DeserializeAsync trên một luồng), WebSocketStream của .NET 10 bọc socket thành Stream và tránh việc tự viết vòng ghép frame. Nó không thay đổi cách bạn xử lý close hay giới hạn kích thước, nhưng làm code ngắn hơn đáng kể.
Close code: dùng đúng mã, đừng dùng 1000 cho mọi thứ
| Mã | Nghĩa | Dùng khi |
|---|---|---|
| 1000 | Normal closure | Client chủ động rời đi, kết thúc bình thường |
| 1001 | Going away | Server shutdown, deploy |
| 1002 | Protocol error | Frame không hợp lệ, sai thứ tự |
| 1007 | Invalid payload | Payload không giải mã được |
| 1008 | Policy violation | Không có quyền, vi phạm giới hạn nghiệp vụ |
| 1011 | Internal error | Lỗi phía server không lộ chi tiết |
Client đọc mã này để quyết định có reconnect hay không: 1000/1008 thì không nên, 1001/1011 thì nên. Nếu bạn luôn đóng bằng 1000, client sẽ không bao giờ thử lại sau khi server restart — một lỗi âm thầm và khó debug.
Xác thực handshake: chỗ dễ bỏ sót nhất
Browser WebSocket API không cho bạn đặt header Authorization. Ba cách xử lý, mỗi cách có một cái giá:
- Token trong query string — dễ nhất, nhưng token rơi vào access log và lịch sử proxy. Nếu chọn cách này, phải redact tham số đó ở log và dùng token ngắn hạn.
- Subprotocol — nhét token vào
Sec-WebSocket-Protocol. Ít lộ hơn, nhưng client phải khai báo đúng và server phải chọn lại protocol trong lúc accept. - First-message auth — chấp nhận kết nối, chờ frame đầu tiên là thông điệp xác thực, đóng bằng 1008 nếu sai hoặc quá hạn. Đây là cách sạch nhất cho protocol riêng, đổi lại bạn phải tự quản lý timeout.
Với xác thực bằng cookie, hãy kiểm tra Origin trước khi accept. Handshake WebSocket không chịu CORS, nên một trang web khác có thể mở kết nối kèm cookie của người dùng — đây là cross-site WebSocket hijacking, và SameSite không bảo vệ đủ. Sau khi accept, lưu danh tính vào record của connection và kiểm tra quyền ở từng message; quyền có thể thay đổi giữa phiên, còn kết nối thì sống lâu.
Backpressure: chỗ WebSocket khác HTTP
HTTP có ranh giới request/response rõ ràng, nên bộ nhớ bị chặn tự nhiên. WebSocket thì không: SendAsync ghi vào buffer của kết nối và trả về khi ghi xong hoặc khi bị chặn bởi transport. Với client đọc chậm, dữ liệu dồn lại; nếu bạn await từng lần gửi trong vòng broadcast, một client chậm sẽ chặn cả vòng lặp. Nếu bạn không await mà dùng Task.Run, bạn mất kiểm soát bộ nhớ.
Mẫu đúng cho broadcast:
- Mỗi connection có một
Channel<byte[]>giới hạn (ví dụ 64 item) và một task ghi duy nhất đọc từ channel đó. - Broadcast chỉ
TryWritevào channel; nếu channel đầy, đóng connection với 1011 thay vì chờ. - Không dùng chung một buffer giữa các connection — mỗi writer cần dữ liệu riêng cho đến khi ghi xong.
Đây chính là phần SignalR đã làm sẵn. Nếu bạn đang viết ba mươi dòng quản lý channel cho mỗi connection, hãy dừng lại và kiểm tra xem SignalR có đáp ứng được yêu cầu không.
Reverse proxy: nơi WebSocket chết lặng
WebSocket đi qua proxy chỉ khi proxy được cấu hình để nâng cấp kết nối. Với nginx, tối thiểu là:
location /ws {
proxy_pass http://api:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
Ba lỗi cấu hình thường gặp: thiếu proxy_http_version 1.1 (HTTP/1.0 không hiểu upgrade), thiếu header Connection, và proxy_read_timeout mặc định 60 giây cắt kết nối im lặng. Quy tắc thực dụng: đặt KeepAliveInterval của server ngắn hơn timeout của proxy ít nhất hai lần, để ping giữ kết nối sống trước khi proxy tính chuyện đóng.
Với IIS, cần bật tính năng WebSocket trong ASP.NET Core Module; với ingress-nginx trên Kubernetes, đặt nginx.ingress.kubernetes.io/proxy-read-timeout theo cùng nguyên tắc. Nếu bạn dùng YARP hoặc một gateway khác, kiểm tra rằng nó forward Upgrade và không buffer response.
Mở rộng ngang: trạng thái nằm trong process
Registry ConcurrentDictionary chỉ đúng khi có một instance. Với ba pod, client nối vào pod A không thể nhận message do pod B phát. Hai cách xử lý:
- Sticky session ở load balancer: giữ client vào cùng instance. Cần thiết vì bản thân kết nối là stateful. Nhược điểm: instance chết thì client mất kết nối, và broadcast vẫn cần cơ chế riêng.
- Backplane pub/sub: mỗi instance publish message lên Redis (hoặc broker khác) và subscribe kênh chung; instance nào giữ connection thì gửi xuống. Redis pub/sub không durable — message gửi lúc instance chết sẽ mất, nên đừng dùng nó như message queue.
Việc tự viết backplane là lý do lớn nhất để chọn SignalR. Nếu bạn cần giữ wire protocol riêng, hãy dùng một broker đã có (Redis, NATS) và viết phần registry mỏng, thay vì tự phát minh cơ chế đồng bộ.
Khi nào không nên dùng raw WebSocket
| Bạn cần | Nên dùng |
|---|---|
| Group, gửi theo user, reconnect, fallback transport | SignalR |
| Server đẩy một chiều, client không gửi | SSE |
| Wire format cố định, client không phải JS/.NET | WebSocket trực tiếp |
| Throughput cao giữa service với nhau | gRPC streaming |
Raw WebSocket thắng khi bạn cần một protocol riêng (binary, length-prefixed, hoặc tương thích với thiết bị có sẵn), khi client là native app đã có implementation, hoặc khi bạn cần kiểm soát chính xác việc ghép frame. Nó thua ở mọi thứ còn lại: nhóm, xác thực lại, reconnect, scale-out, và chi phí bảo trì.
2027
.NET 11 (RC3, GA trong tháng 11/2026) không thay đổi mô hình WebSocket; WebSocketStream và các overload Memory<byte> là hướng API hiện tại. Điều đang dịch chuyển là ranh giới: SSE ngày càng đủ cho dashboard và streaming token từ AI, còn WebSocket trực tiếp thu hẹp vào các giao thức đặc thù. Đó là diễn biến lành mạnh — ít người phải tự viết registry hơn.
Checklist
- Dùng
app.MapGet("/ws", ...), kiểm traIsWebSocketRequestvà trả 400 cho request thường. - Ghép frame đến
EndOfMessage, đặt giới hạn message và đóng bằng 1009 khi vượt. - Tuần tự hoá
SendAsynctrên mỗi socket; dùng channel giới hạn cho broadcast. - Đặt
KeepAliveIntervalngắn hơn timeout của proxy; cấu hình proxy forwardUpgrade. - Chọn sticky session hoặc backplane trước khi chạy nhiều instance.
Đọc tiếp trong series
- Xây dựng ứng dụng web thời gian thực với SignalR Core — lớp trừu tượng giải quyết phần lớn việc ở bài này.
- HTTP và HTTPS từ A-Z — handshake, header và mã trạng thái 101.
- Sử dụng Redis trong ASP.NET Core — pub/sub cho backplane và các mẫu thiết kế liên quan.
- Hiểu về gRPC trong ASP.NET Core — so sánh với streaming hai chiều giữa service.



