Muta.ApiExtensions.WebSockets 1.0.0.5

Muta.ApiExtensions.WebSockets 🚀

一个为 ASP.NET Core 量身定制的 WebSocket 扩展包，旨在帮助开发者在几秒钟内为 Web API 项目添加 实时数据推送、可视化监控面板 以及 自动化导航入口。无需配置静态文件，真正实现“开箱即用”。

✨ 核心特性

• ✅ 极简集成：通过一行代码完成 WebSocket 服务与监控页面的部署。
• ✅ 内置监控面板：自带 /ws-viewer 实时主题查看与数据流跟踪页面（无需前端开发）。
• ✅ 智能导航聚合：自动将监控页面、自定义 HTML 路由聚合到统一的导航首页。
• ✅ 灵活的身份验证：支持高度自定义的 WebSocket 连接权限校验逻辑。
• ✅ 零配置部署：内置 Echarts 与 HTML 组件，无需手动维护静态资源文件。

📦 安装

使用 NuGet 包管理器安装：

dotnet add package Muta.ApiExtensions.WebSockets

🚀 快速开始 (The "Magic" Way)

如果你想在现有项目中立即启用 WebSocket 功能和监控页面，只需调用 AddMutaWebSocketWithViewer。

Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMutaHtmlNavigationServices(); // 导航服务, 可选

// 1. 注册你的业务 Hub 实现 (实现 IMutaWebSocketHub 接口)
builder.Services.AddMutaWebSocket(ServiceLifetime.Scoped, typeof(MyCustomHub));

// 2. 注册一个后台服务，定时推送数据到监控页面, 这里以 DashboardStatPushService 为例
builder.Services.AddHostedService<DashboardStatPushService>(); 

// 3. 注册 SignalR 服务 
builder.Services.AddSignalR();

var app = builder.Build();

// 4. 一行代码集成：启用 WebSocket 端点 + 注入监控页面 + 配置导航路由
app.AddMutaWebSocketWithViewer(
    wsPath: "/ws/{topic}",      // WebSocket 连接路径
    wsBasePath: "/ws",          // 基础路径用于监控页
    pagePath: "/ws-viewer",     // 监控页面访问路径
    navTitle: "WebSocket 实时监控" // 导航栏显示的标题
);

// 5.中间件以及路由配置
app.AddMutaWebSocketWithViewer();
app.AddMutaHtmlNavigation();      // 导航首页, 可选

app.Run();

DashboardStatPushService.cs 示例

    public class DashboardStatPushService : BackgroundService
    {
        private readonly IMutaWebSocketBroadcaster _broadcaster; 

        public DashboardStatPushService(IMutaWebSocketBroadcaster broadcaster)
        {
            _broadcaster = broadcaster;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                var stats = _broadcaster.SendDashboardAsync(stoppingToken);
                await Task.Delay(3000, stoppingToken); // 每秒推送一次
            }

        }
    }

🛠️ 进阶配置 (Advanced Usage)

如果你需要更精细的控制（例如自定义认证逻辑或特定的路由映射），可以使用基础 API。

1. 自定义身份验证 (Custom Auth)

你可以通过 UseMutaWebSocket 直接拦截并校验连接参数中的 user 和 pwd。

app.UseMuteWebSocket("/ws/{topic}", 
    credentialResolver: (ctx) => {
        // 从 QueryString 或 Header 中提取凭据
        var user = ctx.Request.Query["user"];
        var pwd = ctx.Request.Query["pwd"];
        return (user, pwd);
    },
    authValidator: async (ctx, user, pwd) => {
        // 实现你的校验逻辑
        return await MyAuthService.ValidateAsync(user, pwd);
    }
);

2. 自定义 Hub 业务逻辑

通过实现 IMutaWebSocketHub 接口，你可以处理连接建立、消息接收和断开时的业务逻辑。

public class MyCustomHub : IMutaWebSocketHub
{
    public async Task OnConnectedAsync(HttpContext context, IWebSocketConnection connection, CancellationToken ct)
    {
        // 处理新连接逻辑...
    }

    public async Task OnMessageAsync(HttpContext context, IWebSocketConnection connection, ReadOnlyMemory<byte> message, WebSocketMessageType type, bool endOfMessage, CancellationToken ct)
    {
        // 处理接收到的消息...
    }

    public async Task OnDisconnectedAsync(HttpContext context, IWebSocketConnection connection, CancellationToken ct)
    {
        // 处理断开连接逻辑...
    }
}

🔍 路由与接口说明

🎯 向指定用户发送消息（点对点推送）

除了主题广播外，还可以精确地向某个用户推送消息，只需调用 SendToUserAsync 方法即可。

1. 接口说明

Task SendToUserAsync(string topic, string user, object data, CancellationToken cancellationToken = default);

• topic：用户所在的主题（与连接时的 topic 保持一致）
• user：用户标识（连接时传入的 user）
• data：要发送的数据对象（会自动序列化为 JSON）
• cancellationToken：可选的取消标记

2. 使用示例

假设要给 topic 为 "chat"，用户名为 "alice" 的用户推送一条消息：

await _broadcaster.SendToUserAsync(
    topic: "chat",
    user: "alice",
    data: new { message = "你好，Alice！", time = DateTime.Now }
);

提示：如果同一个用户在多个终端（如手机和网页）同时在线，所有连接都会收到消息。

3. 典型场景

• 私聊消息推送
• 订单状态变更通知
• 管理员单独下发指令
• 只给特定用户推送专属数据

📝 完整接口一览

💡 使用建议

1. 中间件顺序：请确保 AddMutaWebSocketWithViewer 或 UseMutaWebSocket 在 app.MapControllers() 之前调用。
2. 导航聚合：如果你使用了 AddMutaHtmlNavigation，请务必将监控页面的配置放在导航页注册之后，以确保页面能正确出现在导航列表中。