SAEA.WebSocket 26.11.16.1

dotnet add package SAEA.WebSocket --version 26.11.16.1
                    
NuGet\Install-Package SAEA.WebSocket -Version 26.11.16.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SAEA.WebSocket" Version="26.11.16.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="SAEA.WebSocket" Version="26.11.16.1" />
                    
Directory.Packages.props
<PackageReference Include="SAEA.WebSocket" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add SAEA.WebSocket --version 26.11.16.1
                    
#r "nuget: SAEA.WebSocket, 26.11.16.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package SAEA.WebSocket@26.11.16.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=SAEA.WebSocket&version=26.11.16.1
                    
Install as a Cake Addin
#tool nuget:?package=SAEA.WebSocket&version=26.11.16.1
                    
Install as a Cake Tool

SAEA.Sockets - 跨平台高性能 Socket 通信框架 🔌

NuGet version License

English Version | 中文版

基于 .NET Standard 2.0 的跨平台 Socket 通信框架。底层异步 IO 机制由 .NET 运行时按操作系统自动选择:Windows 使用 IOCP,Linux 使用 epoll,macOS 使用 kqueue,对外始终是同一套 API。收发路径基于 SAEA.Common 零拷贝(Span/Memory)与内存池化。

快速导航 🧭

章节 内容
⚡ 30秒快速开始 最简单的上手示例
🎯 核心特性 框架的主要功能
🖥️ 平台支持 三平台与底层 IO 机制
📐 架构设计 组件关系与工作流程
💡 应用场景 何时选择 SAEA.Sockets
📊 实现模式对比 两种收发实现与选型
⚠️ 破坏性变更(P0) 本版本必须核对的 11 条公开变化
❓ 常见问题 FAQ 快速解答
🔧 核心类 主要类一览
📝 使用示例 详细代码示例

30秒快速开始 ⚡

最快上手方式,只需3步即可运行 TCP 服务器:

Step 1: 安装 NuGet 包

dotnet add package SAEA.Sockets

Step 2: 创建 TCP 服务器(仅需5行代码)

using SAEA.Sockets;
using SAEA.Sockets.Handler;

// 创建服务器配置
var option = SocketOptionBuilder.Instance
    .SetSocket(SAEASocketType.Tcp)
    .UsePacket()
    .SetPort(39654)
    .Build();

var server = SocketFactory.CreateServerSocket(option);
server.OnServerReceiveSpan += (userToken, data) => server.Send(userToken.ID, data);  // 收到消息立即回复
server.Start();

Step 3: 创建 TCP 客户端连接

var client = SocketFactory.CreateClientSocket(option);
client.OnClientReceiveSpan += (data) => Console.WriteLine(Encoding.UTF8.GetString(data.ToArray()));
client.Connect();
client.SendAsync(new ReadOnlyMemory<byte>(Encoding.UTF8.GetBytes("Hello SAEA!")));

就这么简单! 🎉 你已经实现了一个面向高并发场景的 TCP 通信系统。


核心特性 🎯

特性 说明 优势
🚀 跨平台异步 IO 底层机制由 .NET 运行时在 Windows/Linux/macOS 上自动选择 IOCP / epoll / kqueue 同一套 API 三平台运行,无需条件编译或切换实现
🔒 SSL/TLS 加密 内置 BouncyCastle TLS 1.2/1.3,事件模式与流模式通用 自动证书加载、SNI、双向证书与握手回调,不依赖 SslStream
📡 双协议支持 TCP + UDP 双模式 TCP 可靠传输,UDP 高速广播
🌐 IPv6 支持 完全兼容 IPv6 协议 适应未来网络环境
💾 零拷贝 + 内存池 OnServerReceiveSpan Span 收包、BufferManager、UserTokenPool、MemoryPoolManager 零拷贝解析,减少内存分配,降低 GC 压力
🔄 会话管理 SessionManager 自动管理 超时自动清理,连接状态追踪
🛠️ 自定义协议 ICoder 接口扩展 灵活的协议编解码器
🔗 Builder 配置 链式配置构建器 代码简洁,易于理解

平台支持 🖥️

平台 底层异步 IO 机制
Windows IOCP(I/O Completion Port)
Linux epoll
macOS kqueue

三平台使用同一套 API,无需条件编译,也无需切换实现。底层机制由 .NET 运行时根据当前操作系统自动选择;框架侧只负责收发调度、协议编解码与会话管理。

⚠️ 命名说明:UsePacket() 是历史命名,指框架的 SocketAsyncEventArgs 收发实现,不是 Windows 限定——它在 Linux/macOS 上同样可用,底层分别落到 epoll/kqueue。TCP 只有这一套底层引擎(SaeaServerSocket / SaeaClientSocket)。

UseStream() 不再切换引擎,而是在同一引擎上额外暴露双工 Stream 门面(GetStream() / ChannelInfo.Stream),由该门面独占入站数据;TLS 与事件模式、流模式都能组合使用。配置 UseInputHandler 后入站改由输入处理器独占:GetStream()、ReceiveAsync()、ChannelInfo.Stream 的读取会抛 InvalidOperationException,写方向不受影响。


架构设计 📐

组件架构图

┌─────────────────────────────────────────────────────────────┐
│                     SAEA.Sockets 架构                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────┐      ┌──────────────────┐            │
│  │ SaeaServerSocket │      │ SaeaClientSocket │            │
│  │ (SocketAsyncEvt) │      │ (SocketAsyncEvt) │            │
│  └────────┬─────────┘      └────────┬─────────┘            │
│           │        SaeaConnection (Pipe + TLS)              │
│           └──────────────┬──────────┘                       │
│                          │                                   │
│            ┌───────▼───────┐                                │
│            │  BaseSocket   │                                │
│            │   (基类)      │                                │
│            └───────┬───────┘                                │
│                    │                                         │
│     ┌──────────────┼──────────────┐                        │
│     │              │              │                         │
│  ┌──▼──┐      ┌────▼───┐     ┌───▼────┐                   │
│  │Pool│      │ Session│     │  Coder │                   │
│  │(池)│      │Manager │     │(编解码)│                   │
│  └──┬──┘      └────┬───┘     └───┬────┘                   │
│     │              │              │                         │
│  BufferPool    UserToken      ICoder                      │
│  (内存池)      (用户令牌)    (协议接口)                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

工作流程图

客户端连接流程:

客户端 ──► Connect ──► Server.Accepted
                              │
                              ▼
                    ┌─────────────────┐
                    │  UserTokenPool  │ 分配用户令牌
                    │   获取 Token    │
                    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ SessionManager  │ 注册会话
                    │  添加 Session   │
                    └─────────────────┘
                              │
                              ▼
                    OnAccepted 事件触发

数据接收流程:

网络数据 ──► 异步 IO 完成(IOCP/epoll/kqueue)──► BufferManager 接收
                                │
                                ▼
                      ┌─────────────────┐
                      │ SaeaConnection  │ (可选)TLS 解密
                      └─────────────────┘
                                │
                    ┌───────────┴───────────┐
                    ▼                       ▼
          ┌─────────────────┐     ┌─────────────────┐
          │ 流模式:Pipe    │     │ 事件模式:      │
          │ Stream 门面     │     │ Span 回调       │
          └─────────────────┘     └─────────────────┘
                                │
                                ▼
                      OnServerReceiveSpan 事件触发(事件模式)
                                │
                                ▼
                      ┌─────────────────┐
                      │     Coder       │ 编码响应
                      │   Encode()      │
                      └─────────────────┘
                                │
                                ▼
                      SendAsync(ReadOnlyMemory<byte>) 发送数据

应用场景 💡

✅ 适合使用 SAEA.Sockets 的场景

场景 描述 推荐理由
🎮 游戏服务器 实时对战、状态同步 异步 IO + 会话管理,适合大量长连接
📊 实时数据推送 股票行情、体育比分 高吞吐量,低延迟
🤖 IoT 设备通信 传感器数据上报 支持大量设备并发连接
💬 即时通讯 私聊、群聊、客服系统 会话管理完善,事件驱动
📁 文件传输 大文件分块传输 内存池优化,减少 GC
🔗 RPC 通信 微服务间通信 二进制协议,高效传输

❌ 不适合的场景

场景 推荐替代方案
简单 HTTP API 使用 SAEA.Http 或 ASP.NET
浏览器客户端 使用 SAEA.WebSocket
MQTT 设备 使用 SAEA.MQTT
Redis 缓存 使用 SAEA.RedisSocket

实现模式对比 📊

TCP 只有一套底层引擎,UsePacket() 与 UseStream() 只决定数据如何交付,不再切换实现:

对比项 事件模式(UsePacket()) 流模式(UseStream())
主要类 SaeaServerSocket / SaeaClientSocket 同左(同一引擎)
接收方式 每连接一个 SocketAsyncEventArgs,通过 On*ReceiveSpan 交付 每连接一个 PipeReader,通过 GetStream() / ChannelInfo.Stream 读写
UDP ✅ 支持(UDP 仅支持事件模式) ❌ 不支持
SSL/TLS ✅ 支持(解密后走 Span 回调) ✅ 支持(解密后进入 Pipe)
数据消费 只走 Span 事件 Stream 门面独占入站数据
底层 IO 机制 由 .NET 运行时选择:Windows IOCP / Linux epoll / macOS kqueue 同上

命名说明:UsePacket() 指 SocketAsyncEventArgs 收发实现,与操作系统无关。两种模式互斥,后调用的方法生效。

关于性能数字

本 README 不提供跨框架性能对比数字(与 TouchSocket、DotNetty 等的差异请以自己场景的压测为准)。可复现的实测数据只有零拷贝收发路径:运行 SAEA.P2PTest --bench-iocp(4KB 帧、单机回环),结果见根目录 README。


破坏性变更(P0)⚠️

本版本同时发布 SAEA.Sockets 与 SAEA.Sockets.Pipeline,以下 11 条影响升级,逐条核对:

  1. Pipeline 4 个接口共新增 6 个成员:IChannelHandler.HandlerAdded / HandlerRemoved、IChannelInboundHandler.ChannelActiveAsync / ChannelInactiveAsync、IChannelHandlerContext.CloseAfterWriteAsync、IChannelPipeline.WriteAsync。外部直接实现这些接口会编译失败;继承适配器不受影响。

  2. ctx.WriteAsync 仅在出站回调内合法:回调外调用抛 InvalidOperationException;业务发消息用 ctx.Pipeline.WriteAsync(entity)。

  3. 入站普通异常通知一次后冒泡:不再吞掉,链尾 ExceptionTerminalHandler 记录并决定是否断开。

  4. Start() 后链结构冻结:AddLast / AddFirst / Remove 均抛 InvalidOperationException。

  5. 两个带 owner 的发送重载 void → Task:

    // IServerSocket
    Task SendAsync(string sessionID, ReadOnlyMemory<byte> data, IDisposable owner);
    // IClientSocket
    Task SendAsync(ReadOnlyMemory<byte> data, IDisposable owner);
    

    SaeaServerSocket、SaeaClientSocket、SaeaUdpServerSocket、SaeaUdpClientSocket 四个实现同步变更。await socket.SendAsync(id, data, owner) 能观察真实交接结果;旧代码不 await 仍可编译,但异步失败会被静默丢弃。外部自定义接口实现必须改签名。

  6. owner 释放口径:成功与所有可确认退出的路径恰好释放一次;会话不存在、同步异常由传输层释放;异步失败/取消在确认 socket 操作退出后释放;无法证明内核已退出的发送超时路径放弃回收。调用方不得在拿到 Task 后再 Dispose owner。

  7. ByteToMessageDecoder 不累加半包:只接受泵切好的完整 PooledMessage;FrameSplitterHandler 只用于无泵的纯链式场景,与泵共存会把同一批字节拆两次。

  8. RawFrame 与信封模型互斥:FramePassthroughHandler 原始帧旁路与 Envelope* / Codec* 信封链不能装在同一条链上。

  9. CloseAfterWriteAsync 只保证已提交传输层:不表示对端已收到;DrainTimeout <= 0 在该入口按 5 秒处理。

  10. 内存只承诺两项有界:MaxBufferedBytes 约束输入残余字节,MaxPendingWrites 约束出站待写项数;其余排队帧、在途帧、TLS 复制与 socket 缓冲等没有固定总上界。

  11. 装配位置与限制:OutboundSerializingHandler 必须恰好一个且位于出站前缀最右侧;SwitchableSplitter 每连接一个实例,SwitchTo 是解除 StopAfterCurrent 屏障的唯一方式,切换目标 MaxFrameLength 不得超过创建时固定的上限,SplitterSwitchTimeout 默认 10 秒;TakeAvailableSplitter 以一次读取为消息边界、MaxFrameLength 为单帧硬上界(可用缓冲超出时按上限切块,不抛异常),且不豁免 ChannelPipeline.Create 的缓冲下限校验。


常见问题 ❓

Q1: 这个框架只能在 Windows 上运行吗?

A: 不是。Windows、Linux、macOS 使用同一套 API。底层异步 IO 机制由 .NET 运行时按操作系统自动选择——Windows 是 IOCP,Linux 是 epoll,macOS 是 kqueue——框架的收发调度、编解码和会话管理逻辑完全一致,不需要条件编译。

UsePacket() 中的 "Iocp" 是历史命名,指 SocketAsyncEventArgs 收发实现,不表示 Windows 限定。

Q2: 如何实现自定义协议?

A: 实现 ICoder 接口或继承 BaseCoder:

using System;
using System.Buffers;
using System.Text;
using SAEA.Sockets.Base;

// 自定义编码器:演示「复用 BaseCoder 的帧式编解码 + 按 Type 过滤」。
// 注意 BaseCoder.Encode/Decode 非 virtual,无法 override;EncodeText/Handle 仅为包装示意,
// 框架经 ICoder 调用的是基类的 Encode/Decode。若需自定义线格式,请直接实现 ICoder。
public class MyCoder : BaseCoder
{
    public const byte Text = 1;

    // 编码:把业务数据封装为自定义类型帧后写入 writer
    public void EncodeText(ReadOnlyMemory<byte> payload, IBufferWriter<byte> writer)
    {
        Encode(new BaseSocketProtocal(Text, payload), writer);
    }

    // 解码:传入收到的序列,返回的批次必须 using(帧内存在 Dispose 前有效)
    public void Handle(ReadOnlySequence<byte> data)
    {
        using (var frames = Decode(data))
        {
            foreach (var frame in frames.Frames)
            {
                if (frame.Type == Text)
                    Console.WriteLine($"收到文本帧: {Encoding.UTF8.GetString(frame.Content.ToArray())}");
            }
        }
    }
}

接线方式(UsePacket<T>() 内部构造 BaseContext<T>,把编码器交给框架使用):

using SAEA.Sockets;

var option = SocketOptionBuilder.Instance
    .SetSocket(SAEASocketType.Tcp)
    .UsePacket<MyCoder>()   // 注入自定义编码器
    .SetPort(39654)
    .Build();

Q3: 如何配置 SSL/TLS 加密?

A: 通过 WithSsl(...) 统一入口配置,事件模式与流模式都可以启用:

using System.Security.Authentication;
using System.Security.Cryptography.X509Certificates;
using SAEA.Sockets;
using SAEA.Sockets.Ssl;

// 服务端:自动从 PFX 加载证书,默认启用 TLS 1.2 + TLS 1.3
var serverOption = SocketOptionBuilder.Instance
    .SetSocket(SAEASocketType.Tcp)
    .SetIP("0.0.0.0")
    .SetPort(443)
    .WithSsl(o =>
    {
        o.ServerCertificate = SaeaCertificateLoader.FromPfx("server.pfx", "password");
        o.Protocols = SaeaTlsProtocols.Default;
        o.ServerCertificateSelector = sni => sni switch
        {
            "api.example.com" => apiCertificate,
            _ => defaultCertificate
        };
        o.ClientCertificateRequired = true;            // 双向证书(mTLS)
        o.HandshakeCompleted = context =>
            Console.WriteLine($"TLS 握手完成:{context.NegotiatedProtocol}");
    })
    .Build();

// 客户端:设置 SNI 目标主机与证书校验策略
var clientOption = SocketOptionBuilder.Instance
    .SetSocket(SAEASocketType.Tcp)
    .SetIP("127.0.0.1")                    // 实际连接地址:SetIP 只接受 IP 字面量
    .SetPort(443)
    .WithSsl(o =>
    {
        o.TargetHost = "api.example.com";  // SNI 与证书主机名校验使用
        o.ClientCertificates = new X509Certificate2Collection(clientCertificate);
        o.CertificateValidationCallback = (sender, cert, chain, errors) => errors == SslPolicyErrors.None;
    })
    .Build();

握手成功后才触发 OnAccepted(服务端)或 ConnectAsync 完成(客户端);失败时通过 OnError / SaeaTlsOptions.HandshakeFailed(或 OnTlsHandshake(failed: ...))上报。ChannelInfo.Tls / StreamUserToken.Tls 可读取协商协议、密码套件与对端证书。内置 TLS 基于 BouncyCastle,不使用 SslStream,因此不要求流模式。

开发用证书怎么来

仓库自带命令行工具 Src/SAEA.Sockets.SslTlsTool,一条命令即可产出开发用证书,默认写入当前目录下的 certs/:

# 自签单张证书(SAN 含 localhost 与 127.0.0.1)
dotnet run --project Src/SAEA.Sockets.SslTlsTool -c Release -- --self-signed

# 本地根 CA + 服务端/客户端证书(mTLS)
dotnet run --project Src/SAEA.Sockets.SslTlsTool -c Release -- --ca

两条命令都可追加 --verify,生成后自检 PFX/PEM 读回、证书链、SAN/EKU 与本机回环握手。输出目录用 --out 改;完整参数与退出码(0 有新产物、1 参数错误、2 生成或自检失败、3 文件全部已存在、本次未写入)见工具自身的 --help。

证书生成与格式转换都在 SAEA.Sockets.SslTlsTool 侧完成,它还提供 openssl 兼容子命令(req、x509、pkcs12、pkcs8、pkey、crl2pkcs7、pkcs7、version)。

不带任何参数运行会进入交互模式,逐行输入与命令行相同的参数(例如 --self-signed --verify),help 查看帮助,exit 或 quit 退出;取值含空格时用双引号包住,如 --cn "CN=localhost, O=SAEA"。

产物清单:

模式 文件 说明
--self-signed certs/localhost.pfx / .crt / .key 单张自签证书,基名可用 --name 修改
--ca certs/ca.pfx / .crt / .key 本地根 CA
--ca certs/server.pfx / .crt / .key 服务端证书,SAN 默认是 localhost + 127.0.0.1
--ca certs/client.pfx / .crt / .key 客户端证书,EKU 为 clientAuth,不写 SAN

.pfx 是 PKCS#12,含私钥并带口令,默认口令 saea(可用 --pwd 改);CA 模式下的 server.pfx / client.pfx 里同时带签发它们的 CA 证书,方便 curl、Java、Node 等外部工具直接读取。.crt / .key 是 PEM 文本:.crt 只含单张证书、不含链,.key 是不加密的明文私钥(RSA PRIVATE KEY),没有任何口令保护——--pwd 和默认口令 saea 只保护 PFX,不保护 .key。.key 泄露等同身份泄露,ca.key 泄露更等于签发权泄露,都不要提交到版本库。

用口令读回 PFX 并交给 WithSsl(...):

.WithSsl(o =>
{
    o.ServerCertificate = SaeaCertificateLoader.FromPfx("certs/server.pfx", "saea");
})

FromPfx 只承载叶子证书:服务端握手时下发的证书链由本库从系统信任库补齐。所以CA 没有导入客户端信任库时,客户端默认校验会失败(UntrustedRoot);本机回环自测只是靠“容忍未知根”放行,不能当成链校验成功的证据。验证链只有两种做法:把 CA 装进信任库,或在测试代码里用 CustomRootTrust 显式指定 CA。

nginx、curl 等需要 leaf + CA 拼接的 fullchain 时自行拼接(工具不单独产出链文件):

cat certs/server.crt certs/ca.crt > certs/server.fullchain.crt

把 CA 导入信任库(仅限本机开发,用完请移除):

Windows 当前用户:

Import-Certificate -FilePath certs\ca.crt -CertStoreLocation Cert:\CurrentUser\Root
# 移除(CA 主题为 CN=SAEA Dev Root CA)
Get-ChildItem Cert:\CurrentUser\Root | Where-Object { $_.Subject -eq 'CN=SAEA Dev Root CA' } | Remove-Item

以服务账号运行或需要全机信任时改用 Cert:\LocalMachine\Root(需管理员权限)。

Debian / Ubuntu(curl、OpenSSL、系统浏览器生效):

sudo cp certs/ca.crt /usr/local/share/ca-certificates/saea-dev-ca.crt
sudo update-ca-certificates
# 移除
sudo rm /usr/local/share/ca-certificates/saea-dev-ca.crt && sudo update-ca-certificates --fresh

macOS:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain certs/ca.crt
# 移除
sudo security remove-trusted-cert -d certs/ca.crt

Java 与 Node 不读系统信任库,导入系统库对它们无效,必须单独配置:

# Java
keytool -importcert -cacerts -alias saea-dev-ca -file certs/ca.crt
keytool -delete -cacerts -alias saea-dev-ca    # 移除

# Node
export NODE_EXTRA_CA_CERTS=certs/ca.crt

需要在自己代码里生成时,用 SaeaCertificateFactory / SaeaCertificateAuthority(Save* 方法不会递归创建目录,先确保目标目录存在):

using SAEA.Sockets.Ssl;

// CA 只生成一次并保存:反复新建会换掉 CA,已导入的信任随之作废
using (var ca = SaeaCertificateAuthority.Create(new SaeaCertificateOptions
{
    Subject = "CN=SAEA Dev Root CA"
}))
{
    ca.SavePfx("certs/ca.pfx");
    ca.SaveCertificatePem("certs/ca.crt");

    using (var server = ca.IssueServerCertificate(new SaeaCertificateOptions
    {
        Subject = "CN=localhost"
    }))
    {
        server.SavePfx("certs/server.pfx");
        server.SaveCertificatePem("certs/server.crt");
        server.SavePrivateKeyPem("certs/server.key");
    }
}

⚠️ 这些证书只用于开发与测试,请勿用于生产。

Q4: 内存池的作用是什么?

A: BufferManager 和 UserTokenPool 通过预分配和复用内存:

  • 减少 GC(垃圾回收)压力
  • 避免频繁的内存分配/释放
  • 提升整体性能和稳定性

Q5: TCP 和 UDP 如何选择?

A:

  • TCP: 可靠传输、有序到达、适用游戏、聊天、RPC
  • UDP: 高速传输、无连接、适用视频流、实时广播

SAEA.Sockets 同时支持两种模式,可根据场景灵活选择。

Q6: 支持的最大连接数是多少?

A: MaxConnects 默认 1000,可通过 SetMaxConnects() 调整:

var option = SocketOptionBuilder.Instance
    .SetMaxConnects(10000)  // 设置最大连接数
    .Build();

实际可用连接数还受操作系统约束:Linux/macOS 需要同步调高文件描述符上限(如 ulimit -n),Windows 取决于句柄与内存;最终值以压测结果为准。


核心类 🔧

类名 说明
SaeaServerSocket / SaeaClientSocket TCP 服务器/客户端(统一 IOCP 引擎,支持事件模式、流模式与内置 TLS)
SaeaConnection 每条 TCP 连接的 Pipe + TLS 门面(背压、加解密与握手状态)
SaeaTlsOptions / SaeaTlsProtocols TLS 配置、协议版本与回调
SaeaCertificateLoader PFX/P12、PEM、证书库与目录加载(目录模式支持 SNI 匹配)
ChannelInfo 流模式下的连接信息(Stream、Tls、UserToken)
UdpServerSocket / UdpClientSocket UDP 服务器/客户端
SocketOptionBuilder 链式配置构建器
SocketFactory Socket 工厂类
SessionManager 会话管理器
BaseCoder 默认协议编码器(8字节长度 + 1字节类型 + 内容)
BufferManager 内存缓冲池(复用 byte[] 缓冲区)
UserTokenPool 用户令牌池

使用示例 📝

TCP 服务器(SocketAsyncEventArgs 模式)

using SAEA.Sockets;
using SAEA.Sockets.Handler;

// 使用 Builder 链式配置服务器
var option = SocketOptionBuilder.Instance
    .SetSocket(SAEASocketType.Tcp)  // 设置 Socket 类型为 TCP
    .UsePacket()                       // SocketAsyncEventArgs 模式(跨平台)
    .SetIP("127.0.0.1")              // 监听 IP
    .SetPort(39654)                  // 监听端口
    .SetReadBufferSize(1024 * 64)    // 读缓冲区大小 64KB
    .SetMaxConnects(1000)            // 最大连接数
    .Build();                        // 构建配置

var server = SocketFactory.CreateServerSocket(option);

// 注册事件处理
server.OnAccepted += (obj) => 
    Console.WriteLine($"客户端连接: {((SAEA.Sockets.Interface.IUserToken)obj).ID}");

server.OnServerReceiveSpan += (userToken, data) => 
{
    var message = Encoding.UTF8.GetString(data.ToArray());
    Console.WriteLine($"收到数据: {message}");
    server.Send(userToken.ID, data);  // 回复客户端
};

server.OnDisconnected += (id, ex) => 
    Console.WriteLine($"客户端断开: {id}");

server.Start();
Console.WriteLine("服务器已启动!");

TCP 客户端(SocketAsyncEventArgs 模式)

using SAEA.Sockets;

var option = SocketOptionBuilder.Instance
    .SetSocket(SAEASocketType.Tcp)
    .UsePacket()
    .SetIP("127.0.0.1")
    .SetPort(39654)
    .Build();

var client = SocketFactory.CreateClientSocket(option);

// 注册事件处理
client.OnClientReceiveSpan += (data) => 
    Console.WriteLine($"收到: {Encoding.UTF8.GetString(data.ToArray())}");

client.OnDisconnected += (id, ex) => 
    Console.WriteLine("连接断开");

// 连接服务器
client.Connect();

// 发送数据
client.SendAsync(new ReadOnlyMemory<byte>(Encoding.UTF8.GetBytes("Hello SAEA!")));

UDP 服务器

using SAEA.Sockets;

var option = SocketOptionBuilder.Instance
    .SetSocket(SAEASocketType.Udp)  // UDP 模式
    .SetIP("127.0.0.1")
    .SetPort(39655)
    .Build();

var server = SocketFactory.CreateServerSocket(option);

server.OnServerReceiveSpan += (userToken, data) => 
{
    Console.WriteLine($"收到 UDP 数据");
    server.Send(userToken.ID, data);  // 回发数据
};

server.Start();

SSL/TLS 安全连接

服务端(事件模式,TLS 解密后的明文进入 OnServerReceiveSpan):

using SAEA.Sockets;
using SAEA.Sockets.Core.Tcp;
using SAEA.Sockets.Model;
using SAEA.Sockets.Ssl;

var option = SocketOptionBuilder.Instance
    .SetSocket(SAEASocketType.Tcp)
    .SetIP("127.0.0.1")
    .SetPort(443)
    .WithSsl(o =>
    {
        o.ServerCertificate = SaeaCertificateLoader.FromPfx("server.pfx", "password");
        o.Protocols = SaeaTlsProtocols.Default;
    })
    .Build();

var server = new SAEA.Sockets.Core.Tcp.SaeaServerSocket(option);
server.Start();

流模式(握手成功后通过 ChannelInfo.Stream 读写):

var option = SocketOptionBuilder.Instance
    .UseStream()
    .SetIP("127.0.0.1")
    .SetPort(443)
    .WithSsl(o => o.ServerCertificate = SaeaCertificateLoader.FromPfx("server.pfx", "password"))
    .Build();

var server = new SAEA.Sockets.Core.Tcp.SaeaServerSocket(option);
server.OnAccepted += payload =>
{
    var channel = (ChannelInfo)payload;
    var buffer = new byte[4096];
    var read = channel.Stream.Read(buffer, 0, buffer.Length);
    channel.Stream.Write(buffer, 0, read);
};
server.Start();

客户端:

var option = SocketOptionBuilder.Instance
    .UseStream()                       // 或不调用,使用事件模式
    .SetIP("127.0.0.1")
    .SetPort(443)
    .WithSsl(o =>
    {
        o.TargetHost = "localhost";    // SNI + 证书主机名校验
        o.AllowInvalidCertificates = true;
    })
    .Build();

using (var client = new SaeaClientSocket(option))
{
    using (var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10)))
        await client.ConnectAsync(cts.Token);

    var stream = client.GetStream();   // 流模式下获取双工流
    var payload = Encoding.UTF8.GetBytes("hello");
    await stream.WriteAsync(payload, 0, payload.Length);
}

快捷封装类

using SAEA.Sockets.Shortcut;

// TCP 服务器快捷封装
var tcpServer = new TCPServer(39654);
tcpServer.OnReceive += (sender, userToken, data) => tcpServer.SendAsync(userToken.ID, data);
tcpServer.Start();

// TCP 客户端快捷封装
var tcpClient = new TCPClient("127.0.0.1", 39654);
tcpClient.OnReceive += (sender, data) => Console.WriteLine(Encoding.UTF8.GetString(data.ToArray()));
tcpClient.Connect();
tcpClient.SendAsync("Hello!");

// UDP 快捷封装
var udpServer = new UDPServer(39655);
var udpClient = new UDPClient("127.0.0.1", 39655);

自定义协议编码器

using System;
using System.Buffers;
using System.Text;
using SAEA.Sockets.Base;

// 自定义编码器:演示「复用 BaseCoder 的帧式编解码 + 按 Type 过滤」。
// 注意 BaseCoder.Encode/Decode 非 virtual,无法 override;EncodeText/Handle 仅为包装示意,
// 框架经 ICoder 调用的是基类的 Encode/Decode。若需自定义线格式,请直接实现 ICoder。
public class MyCoder : BaseCoder
{
    public const byte Text = 1;

    // 编码:把业务数据封装为自定义类型帧后写入 writer
    public void EncodeText(ReadOnlyMemory<byte> payload, IBufferWriter<byte> writer)
    {
        Encode(new BaseSocketProtocal(Text, payload), writer);
    }

    // 解码:传入收到的序列,返回的批次必须 using(帧内存在 Dispose 前有效)
    public void Handle(ReadOnlySequence<byte> data)
    {
        using (var frames = Decode(data))
        {
            foreach (var frame in frames.Frames)
            {
                if (frame.Type == Text)
                    Console.WriteLine($"收到文本帧: {Encoding.UTF8.GetString(frame.Content.ToArray())}");
            }
        }
    }
}

接线方式(UsePacket<T>() 内部构造 BaseContext<T>,把编码器交给框架使用):

using SAEA.Sockets;

var option = SocketOptionBuilder.Instance
    .SetSocket(SAEASocketType.Tcp)
    .UsePacket<MyCoder>()   // 注入自定义编码器
    .SetPort(39654)
    .Build();

从 byte[] 迁移 🔄

近期版本移除了 byte[] 公共面,统一改为 Span / Memory。下表列出已删除成员及其替代:

已删除 替代
IClientSocket.OnReceive(OnClientReceiveHandler,byte[]) OnClientReceiveSpan(ReadOnlySpan<byte>,回调内同步消费/复制)
IServerSocket.OnReceive(OnReceiveHandler,(ISession, byte[])) OnServerReceiveSpan((IUserToken, ReadOnlySpan<byte>))
IClientSocket.BeginSend(byte[]) / Send(byte[]) / SendAsync(byte[]) / SendAsync(byte[], int, int, CancellationToken) Send(ReadOnlySpan<byte>) / SendAsync(ReadOnlyMemory<byte>) / SendAsync(ReadOnlyMemory<byte>, CancellationToken);原 offset/count 语义用 data.AsMemory(offset, count) 表达
IClientSocket.ReceiveAsync(byte[], int, int, CancellationToken)(接口成员) 改用 span 事件;具体实现 SaeaClientSocket.ReceiveAsync 保留并从连接 Pipe 读取(无连接门面时抛 KernelException,配置 UseInputHandler 后抛 InvalidOperationException),UdpClientSocket.ReceiveAsync 抛 NotSupportedException
IServerSocket.SendAsync(string, byte[]) / Send(string, byte[]) / End(string, byte[]) / SendAsync(IPEndPoint, byte[]) SendAsync(string, ReadOnlyMemory<byte>) / Send(string, ReadOnlySpan<byte>) / End(string, ReadOnlyMemory<byte>) / SendAsync(IPEndPoint, ReadOnlyMemory<byte>)
IServerSocket.SendAsync(string, ReadOnlyMemory<byte>, IDisposable) / IClientSocket.SendAsync(ReadOnlyMemory<byte>, IDisposable)(原 void) 改为返回 Task;await 才能观察异步失败。SaeaServerSocket / SaeaClientSocket / SaeaUdpServerSocket / SaeaUdpClientSocket 四个实现同步
IocpClientSocket.UserToken 不再公开;按场景改用 Connected 或 ChannelInfo.UserToken / Context.UserToken
IocpServerSocket / IocpClientSocket 重命名为 SaeaServerSocket / SaeaClientSocket(SocketFactory 已返回新类型)
StreamServerSocket / StreamClientSocket 已删除;改用 SaeaServerSocket / SaeaClientSocket 并调用 UseStream(),通过 GetStream() 或 ChannelInfo.Stream 读写
UseSsl() / SetSslCertificate(...) 与 SslStream 直连 统一改为 WithSsl(...) + SaeaTlsOptions;TLS 由 BouncyCastle 实现,事件模式与流模式均可用
ChannelManager.Instance / ChannelManager.GetInstance 每个服务器实例持有自己的 ChannelManager;旧静态入口仅为源码兼容保留并标记 [Obsolete]
快捷封装 TCPClient / TCPServer / UDPClient / UDPServer 的 OnReceive TCPClient / TCPServer.OnReceive 由 byte[] 改为 ReadOnlyMemory<byte>(UDPClient / UDPServer.OnReceive 交付 ISocketProtocal 帧);source/binary breaking,需重新编译

⚠️ 迁移注意

  1. 快捷封装的 OnReceive 为签名级 breaking 变更(byte[] → ReadOnlyMemory<byte>),由版本号 bump 承载,不提供兼容 shim,请重新编译调用方。
  2. 旧 OnReceive 事件已删除,改用 OnClientReceiveSpan / OnServerReceiveSpan 即可。
  3. span 回调参数(data)仅在本次回调期间有效,必须同步消费或在回调内 ToArray() 复制;切勿将 span 保存到字段或跨线程/异步使用,否则为 use-after-free。

默认协议格式

BaseCoder 实现的默认消息协议:

| 8字节长度 | 1字节类型 | N字节内容 |
  • 长度: 数据总长度(用于消息边界识别)
  • 类型: 消息类型标识(可扩展)
  • 内容: 实际消息数据

依赖项

包名 版本 说明
SAEA.Common 26.11.5.1 通用工具类库
BouncyCastle.Cryptography 2.6.2 内置 TLS 1.2/1.3 协议实现
Pipelines.Sockets.Unofficial 2.2.16 Pipeline Socket 扩展
System.IO.Pipelines 10.0.14 高性能 IO 管道

更多资源


许可证

Apache License 2.0

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on SAEA.WebSocket:

Package Downloads
SAEA.MVC

This is a web component based on SAEA.Sockets. It is lightweight, high performance, easy to use and self hosting. 这是一个基于SAEA.Sockets的web组件,轻量高性能,使用简便,自宿主。https://github.com/yswenli/SAEA/tree/master/Src/SAEA.MVCTest。

KissFramework

This is a most simple and stupid server framework commponent include WebSocket/Socket/HTTP/MySQL, base on rule of 'Keep It Simple,Stupid'. All your logic work in A single main thread, you don't need to worry about multi-threading problem. All the heavy work process by framework in background threads. Easy to use database even never hear about SQL. You won't use the SQL knowledge, just need define the struct of database table, and then can use that data and it will automatically synchronize data with client and database. 这是一个最简洁易用的IOCP服务器框架,包含WebSocket/Socket/HTTP/MySQL,基于'Keep It Simple,Stupid'设计原则.用户逻辑单线程,后台数据库多线程,面向对象,操作极简,包含WebSocket/Socket/HTTP/MySQL,你不会用到SQL的,只需定义数据库表结构,即可使用数据且自动和客户端和数据库三者间同步数据.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on SAEA.WebSocket:

Repository Stars
yswenli/WebRedisManager
WebRedis Manager is a simple management to implement Redis using SAEA. RedisSocket, SAEA.MVC and running speed quickly.WebRedisManager是使用的SAEA.RedisSocket、SAEA.MVC等实现Redis的简便管理功能,轻松运行~
Version Downloads Last Updated
26.11.16.1 127 11/16/2026
26.10.8.1 136 10/8/2026
26.4.23.1 212 4/23/2026
26.4.22.1 154 4/21/2026
7.26.4.21 150 4/20/2026
7.26.4.20 140 4/20/2026
7.26.2.2 195 2/2/2026
7.26.1.27 173 1/27/2026
7.26.1.25 177 1/25/2026
7.25.2.19 665 2/19/2025
7.25.2.18 222 2/18/2025
7.25.2.13 248 2/13/2025
7.25.2.11 246 2/11/2025
7.24.8.4 246 8/4/2024
7.23.9.24 391 9/24/2023
7.0.3.19 537 3/19/2023
7.0.0.3 3,595 2/27/2022
7.0.0.2 653 12/5/2021
7.0.0.1 593 11/28/2021
6.2.6.7 708 9/19/2021
Loading failed

This is a websocket server and client component based on SAEA.Socket.
这是基于SAEA.Socket的websocket服务器、客户端组件
https://github.com/yswenli/SAEA