c# websocket 编程入门

新手应优先使用 microsoft.AspNetCore.SignalR 而非 System.Net.websockets；前者封装 WebSocket 并支持降级、连接管理、组播等，后者仅提供底层帧操作，适用于网关等特殊场景。

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("/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 这类弱类型结构的反序列化。

• 参数必须是可序列化的 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 实例的生命周期边界——这些不在入门范围，但你在加第一个 Clients.Group(...).SendAsync(...) 之前，就得想清楚 Group 名怎么生成、谁负责加入/退出、有没有清理机制。