TcpSocket 使用说明（TcpServerEx / TcpClientEx）

这是一个 轻量、稳定、单 TCP 连接 的 C# Socket 通信封装，
特点是：

• ✅ 单连接 / 多客户端 Server
• ✅ 同步 + 异步 Send 统一实现（线程安全）
• ✅ 明确的 帧结束符协议
• ✅ 无 Session / 无复杂队列
• ✅ 适合 工控 / 设备通信 / WPF 后台服务

一、通信协议说明（非常重要）

1️⃣ 帧结束符（End Of Frame）

public class Global
{
    public static byte[] EndOfByte = { 0x03, 0x04 };
}

每一条完整消息 = 数据内容 + EndOfByte

Server / Client 都必须使用同一 EndOfByte

内部使用 KMP 算法解析粘包 / 拆包

二、基础类型说明

IPHost

public class IPHost
{
    public string Address { get; }
    public int Port { get; }

    public IPHost(string address, int port = 0)
    {
        Address = address;
        Port = port;
    }

    public override string ToString()
        => $"{Address}:{Port}";
}

三、TcpServerEx 使用方法

1️⃣ 创建并启动 Server

var server = new TcpServerEx("127.0.0.1:9000");

server.ListenClientEvent += (client, clientId) =>
{
    Console.WriteLine($"Client Accepted: {clientId}");
};

server.ConnectingEvent += (sender, clientId) =>
{
    Console.WriteLine($"Client Connecting: {clientId}");
};

server.DataReceivedEvent += (clientId, data) =>
{
    Console.WriteLine($"[{clientId}] {data}");
};

server.DisconnectedEvent += (sender, clientId) =>
{
    Console.WriteLine($"Client Disconnected: {clientId}");
};

server.Start();

2️⃣ 发送数据（Server → Client）

同步发送
server.Send(clientId, "HELLO CLIENT");
异步发送（推荐）
await server.SendAsync(clientId, "HELLO CLIENT");   
广播
server.SendAll("BROADCAST MESSAGE");
await server.SendAllAsync("ASYNC BROADCAST");
⚠️ 同步 / 异步 共用 SemaphoreSlim

3️⃣ 停止 Server

server.Stop();

自动关闭 Listener
自动断开所有 Client
自动释放 SemaphoreSlim

四、TcpClientEx 使用方法

1️⃣ 创建并连接 Client

var client = new TcpClientEx("127.0.0.1:9000");

client.ConnectedEvent += (sender, id) =>
{
    Console.WriteLine("Connected to server");
};

client.DataReceivedEvent += (id, data) =>
{
    Console.WriteLine($"Server says: {data}");
};

await client.ConnectAsync();

2️⃣ 发送数据（Client → Server）

同步
client.Send("HELLO SERVER");
异步（推荐） 
await client.SendAsync("HELLO SERVER");

3️⃣ 断开连接

client.Disconnect();

五、事件一览（Server / Client 通用）

事件说明

ListenClientEvent	Server 接收到新客户端
ConnectingEvent	客户端开始处理
ConnectedEvent	Client 连接成功
DataReceivedEvent	接收到完整帧数据
DisconnectedEvent	连接断开

六、线程安全 & 设计说明

✔ 发送安全 每个 Client 独立 SemaphoreSlim

同步 / 异步 Send 统一入口

不会出现粘包 / 并发写异常

✔ 接收安全 单独 Receive Loop

KMP 算法解析 EndOfByte

自动处理粘包 / 拆包

✔ 停止安全

CancellationToken 控制

Listener.Stop() + Dispose

不残留后台线程

七、适用场景

✔ 工控设备通信 ✔ 上位机 / 下位机 ✔ WPF 后台 Socket 服务 ✔ 长连接指令 / 响应模型

❌ 不适合：

HTTP / WebSocket

高吞吐 IM（建议用 Pipe / Kestrel）

八、注意事项（必看）

Client / Server 的 EndOfByte 必须一致

消息体中不要主动包含 0x03 0x04

UI 线程请使用 SendAsync

不要在外部直接操作 NetworkStream