新手应优先使用 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 中注册服务并映射路由：
动态切换AI模型以优化成本与性能。当用户发出“eco mode”、“balanced mode”、“smart mode”或“max mode”等模式指令，或使用“/modes status”查询状态及“/modes setup”配置模式时触发。
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> 这类弱类型结构的反序列化。
- 参数必须是可序列化的 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 名怎么生成、谁负责加入/退出、有没有清理机制。
