c# websocket 编程入门

来源：这里教程网时间：2026-02-21 17:40:27 作者：

WebSocket 服务端用

Microsoft.AspNetCore.SignalR

还是

System.Net.WebSockets

？

直接说结论：新手别碰

System.Net.WebSockets

原生 API。它只提供底层读写帧的能力，连握手、ping/pong、消息分片、连接状态管理都要自己写。90% 的业务场景该用

Microsoft.AspNetCore.SignalR

—— 它封装了 WebSocket（也支持长轮询降级），自带连接生命周期、组播、客户端调用服务端方法等能力。

SignalR 默认优先协商 WebSocket 协议，只要浏览器和服务端都支持，实际走的就是 WebSocket；你不用管帧格式、掩码、状态码这些细节。

用
System.Net.WebSockets
：适合做协议网关、代理、或需要完全控制帧内容的极少数场景用
Microsoft.AspNetCore.SignalR
：聊天室、实时通知、协同编辑等常规需求 注意 SignalR 的 Hub 是无状态的，不能在 Hub 类里存实例字段来共享数据

如何创建一个最简 SignalR Hub 并让前端连上？

新建 ASP.NET Core Web API 项目后，安装

Microsoft.AspNetCore.SignalR

NuGet 包，然后添加一个继承

Hub

的类：

public class ChatHub : Hub
{
    public async Task SendMessage(string user, string message)
    {
        await Clients.All.SendAsync("ReceiveMessage", user, message);
    }
}

在

Program.cs

中注册服务并映射路由：

builder.Services.AddSignalR();
// ...
app.MapHub<ChatHub>("/chat");

前端 JS 使用官方

@microsoft/signalr

客户端库：

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chat")
    .build();
connection.on("ReceiveMessage", (user, message) => {
    console.log(`${user}: ${message}`);
});
await connection.start(); // 必须显式 start()
connection.invoke("SendMessage", "Alice", "Hello");

路径必须完全匹配
MapHub
的路由（如
/chat
）
connection.start()
是 Promise，不 await 就调
invoke
会报
Cannot invoke methods on a hub before it's started
Hub 方法名在客户端调用时是大小写敏感的字符串，比如
SendMessage
对应
connection.invoke("SendMessage", ...)

为什么客户端收不到消息？常见连接和跨域问题

最常见的失败不是代码写错，而是环境配置没到位：

开发时若前端是
http://localhost:3000
，后端是
https://localhost:5001
，默认跨域会拦截 WebSocket 升级请求 —— 必须在
Program.cs
配置 CORS 支持 WebSocket：

builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAll", policy =>
    {
        policy.AllowAnyOrigin()
              .AllowAnyMethod()
              .AllowAnyHeader()
              .WithExposedHeaders("WWW-Authenticate"); // 关键：允许暴露认证头（如有）
    });
});
// ...
app.UseCors("AllowAll");

SignalR 要求 CORS 策略必须用
AllowAnyOrigin()
或明确列出源，
AllowCredentials()
和
AllowAnyOrigin()
不能共存如果用了 HTTPS 反向代理（如 Nginx），需确保代理透传
Upgrade
和
Connection
头，并开启 WebSocket 支持 Chrome 控制台 Network 标签下，筛选
ws
或
wss
，看连接是否返回 101 Switching Protocols；如果卡在 pending 或直接 404，基本是路由或跨域问题

Hub 方法参数类型限制和序列化陷阱

SignalR 默认用 System.Text.Json 序列化，不支持

DateTimeOffset

的毫秒级精度保留、不支持循环引用、不支持

Dictionary<string object></string>

这类弱类型结构的反序列化。

参数必须是可序列化的 POCO，字段/属性要有 public getter/setter 避免传
dynamic
或
object
，前端传过来的 JSON 对象会被反序列化成
JsonElement
，Hub 方法签名若写
object data
会导致运行时报
InvalidOperationException: Cannot bind parameter 'data' of type 'System.Object'
需要灵活结构时，用
JsonElement
或
JsonDocument
显式接收：

public async Task HandleEvent(JsonElement payload)
{
    var eventType = payload.GetProperty("type").GetString();
    await Clients.All.SendAsync("EventReceived", eventType);
}

前端发送时保持 JSON 结构清晰，例如：
connection.invoke("HandleEvent", { "type": "click", "x": 100 })

真正难的从来不是“怎么连上”，而是连接建立后怎么处理重连、离线消息、用户身份绑定、以及并发调用下 Hub 实例的生命周期边界——这些不在入门范围，但你在加第一个