CodeWF.EventBus.Socket 1.5.0

CodeWF.EventBus.Socket

CodeWF.EventBus.Socket 是一个面向 C# 进程间通信的轻量级 TCP 事件总线库。它基于 Socket 提供发布订阅与 Query 式请求响应能力，让本地多进程或轻量服务之间可以通信，而不必先引入 RabbitMQ、Kafka、Redis 等外部 MQ 基础设施。

仓库规范

• 当前版本：1.4.4.2，版本号统一维护在根目录 Directory.Build.props 的 <Version> 节点。
• NuGet 包项目统一支持 net8.0;net10.0;net11.0；Demo、App、测试与内部应用项目统一使用 net11.0 / net11.0-windows。
• 根目录 logo.svg、logo.png、logo.ico 是唯一图标源，子工程只通过 MSBuild Link 引用，不维护图标副本。
• 运行时帮助、Markdown 示例、内置备忘录、设计说明等业务文档按功能保留；仓库级入口文档使用根目录 README.md 和 UpdateLog.md。

特性

• 基于 CodeWF.NetWrapper 的 TCP Socket 传输
• 支持 Publish/Subscribe 跨进程事件通知
• 支持同一主题下的 Query/Response 交互
• 查询请求按 TaskId 关联，支持同主题并发查询
• 直接复用 CodeWF.NetWrapper 的 TcpSocketServer、TcpSocketClient、实例命令处理器、SocketCommand、Heartbeat
• 不依赖第三方 MQ
• 自带示例工程 src/EventBusDemo

安装

dotnet add package CodeWF.EventBus.Socket

或

Install-Package CodeWF.EventBus.Socket

快速开始

启动服务端

using CodeWF.EventBus.Socket;

IEventServer eventServer = new EventServer();
await eventServer.StartAsync("127.0.0.1", 9100);

连接客户端

using CodeWF.EventBus.Socket;

IEventClient eventClient = new EventClient();
await eventClient.ConnectAsync("127.0.0.1", 9100);

订阅并发布事件

eventClient.Subscribe<NewEmailCommand>("event.email.new", command =>
{
    Console.WriteLine($"收到邮件主题：{command.Subject}");
});

eventClient.Publish("event.email.new", new NewEmailCommand
{
    Subject = "欢迎使用",
    Content = "您的账号已经准备完成",
    SendTime = DateTime.Now
}, out _);

查询与响应

eventClient.Subscribe<EmailQuery>("event.email.query", query =>
{
    var response = new EmailQueryResponse
    {
        Emails = EmailManager.QueryEmail(query.Subject)
    };

    eventClient.Publish("event.email.query", response, out _);
});

var result = await eventClient.QueryAsync<EmailQuery, EmailQueryResponse>(
    "event.email.query",
    new EmailQuery { Subject = "账户" },
    3000);

文档

• 设计文档
• 示例工程

Runtime options

var options = new EventBusOptions
{
    InboundQueueCapacity = 1024,
    OutboundQueueCapacity = 4096,
    MaxSubjectLength = 256,
    MaxMessageSizeBytes = 1024 * 1024,
    AuthenticationToken = "shared-secret"
};

using var eventServer = new EventServer(options);
using var eventClient = new EventClient(options);

• The server binds to 127.0.0.1 when no host is provided. Use an explicit bind address for network deployment.
• AuthenticationToken protects the event-bus handshake with a shared token. It is not a replacement for TLS because the token is transported over the underlying connection.
• Queue and message limits are enforced to prevent unbounded memory growth. A full per-client outbound queue disconnects that client.
• Use ConnectAsync and the cancellation-aware QueryAsync overloads in hosted applications.

断线重连与离线消息补发

针对 issue #1（断线重连/消息是否确认）的行为说明：

• 端口是否重连？ 客户端在 TCP 异常、心跳失败或发送失败后会按 ReconnectInterval 自动重连，重连成功后自动重新订阅全部本地订阅（Disconnect() 主动断开不会触发重连，重新调用 ConnectAsync 即可）。
• 断开的同时有消息发过来怎么办？ 服务端在客户端下线时会把它的订阅转入离线缓冲：断线期间其它端发布到这些主题的广播按序进入有界队列（每客户端每主题上限 OfflineMessageCapacity，超出丢弃最旧），保留 OfflineMessageRetention 后清理。
• 重连后是否还会继续执行之前的消息？ 会。重连握手携带实例级 ClientId，服务端据此识别同一客户端并清理僵尸旧连接；重新订阅成功后立即按原顺序补发缓冲中的离线消息，之后的新消息正常实时投递。
• 语义是"断线窗口内至少一次"：在线期间的实时投递仍为尽力而为（无逐条 ACK），服务端重启后内存缓冲即失效。通过 EnableOfflineMessage = false 可整体关闭该能力；服务端还会按 ClientIdleTimeout 主动下线静默连接（含心跳失效的死连接），需大于客户端心跳间隔。

脚本

• pack.bat：还原、构建并打包 CodeWF.EventBus.Socket 到 artifacts\packages。如果本机存在 ..\CodeWF.NetWeaver\artifacts\packages，脚本会自动作为本地包源使用，方便在兄弟仓库尚未发布新包时完成本地打包验证。

通信协议

数据通过 TCP 进行传输。

说明

• 这个库适合轻量级事件分发和进程间通信场景。
• 底层传输由 CodeWF.NetWrapper 实现，事件总线通过 RegisterCommandHandler 挂接到当前 TCP 客户端/服务端实例，不再通过全局传输事件做命令分发。
• 事件总线层自己的请求、查询和推送协议对象仍保留在本项目中，因为它们承载的是本库特有的语义。
• 当前消息仅保存在内存中，不提供持久化、重试队列或进程重启后的投递保证。
• 如果用于生产环境，请按实际需要补充认证、加密、监控、限流与重试策略。

第三方开源组件审计（2026-05-20）

检查方式：dotnet restore CodeWF.EventBus.Socket.slnx、dotnet list package --include-transitive、NuGet .nuspec、NuGet.org 与源码仓库信息。优先接受 MIT / Apache-2.0 / BSD；其它开源协议在源码与传递依赖均可追溯时单独标注。

整改：

• 解决方案已从 CodeWF.EventBus.Socket.sln 迁移为 CodeWF.EventBus.Socket.slnx。
• 新增 Directory.Packages.props，直接依赖统一走中央包管理。
• Prism.Avalonia / Prism.DryIoc.Avalonia 从 9.x 降到 MIT 的 8.1.97.11073，并继续保留该开源线。
• 移除未使用的 Irihi.Ursa.PrismExtension。
• 示例依赖当前由 Directory.Packages.props 统一维护，包括 Avalonia 12.1.1、Semi.Avalonia 12.1.0.1、Irihi.Ursa 2.2.0、ReactiveUI.Avalonia 12.1.1、CodeWF.NetWrapper 3.0.11、CodeWF.EventBus 3.4.5.16 和 CodeWF.Log.Avalonia 12.1.2.3。
• 移除 Avalonia.Diagnostics，该包目前没有 Avalonia 12 对应包线。
• 旧传递依赖 System.Configuration.ConfigurationManager、System.Drawing.Common、System.Security.Cryptography.ProtectedData 等已 pin 到 10.0.10。

传递依赖检查结论：有效依赖链未发现 Prism 9 预览包或旧 System.Drawing.Common 4.7.0 / System.Configuration.ConfigurationManager 4.7.0 / System.Security.Cryptography.ProtectedData 4.7.0 链路。CodeWF.NetWrapper 已解析到 3.0.11。

包版本维护约定

XML 文件统一使用两个空格缩进。Directory.Packages.props 统一承载 NuGet 中央包管理开关和包版本变量，包括 AvaloniaVersion 等共享版本属性；Directory.Build.props 仅保留项目构建、编译选项和 NuGet 元数据。仓库如引用 VC-LTL、YY-Thunks，这两个兼容旧版操作系统的特殊包必须使用最新预览版。

CI/CD：自动发布 NuGet 包

推送 v* 标签（例如 v1.4.4.3）会触发 .github/workflows/publish-nuget.yml，发布 CodeWF.EventBus.Socket 包（含 snupkg 符号包），完成后自动创建 GitHub Release。

包版本号以 Directory.Build.props 的 <Version> 为准，打标签前先升版本——nuget.org 拒绝重复的版本号；标签与 <Version> 不一致时工作流仅告警不阻断。认证使用 NuGet Trusted Publishing：工作流通过 nuget/login@v1 以 OIDC 令牌换取一次性发布凭据，仓库不保存任何 secret。nuget.org 侧的 API key 需绑定本仓库与工作流文件名 publish-nuget.yml（Scopes 勾选 Push，Glob 建议收窄为 CodeWF.*）；这类 key 创建后 7 天内需成功发布一次才会转永久有效。

手工发布步骤：

# 1. 升版本：修改 Directory.Build.props 的 <Version>（或用 UpdateLog.md 记录变更）并提交
# 2. 打标签并推送，触发发布
git tag -a v1.4.4.4 -m "CodeWF.EventBus.Socket v1.4.4.4"
git push origin v1.4.4.4
# 3. 在 GitHub Actions 观察 publish-nuget 运行，完成后到 nuget.org 核对新版本