# Communication

**Repository Path**: caoyiliang/Communication

## Basic Information

- **Project Name**: Communication
- **Description**: 通讯库
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-04-14
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 概述



# Communication c# 通讯库

专为.NET环境设计的高性能、灵活且高度可扩展的通讯库。支持多种通讯口协议、分包方式和自动重连机制，能有效降低通讯代码开发成本，帮助开发者将更多精力投入业务逻辑实现。

---

## 🚀 为什么选择 Communication 通讯库

- **多通讯协议集成**：支持串口 (SerialPort)、Tcp Client/Server、UDP、蓝牙、命名管道等多种通讯方式。
- **分包算法灵活可定制**：内置多种主流分包方式，支持头尾、头长、定时分包等，并可通过实现接口自定义协议分包。
- **同步/异步全支持**：异步API设计，不卡UI，适用于复杂人机交互与后台服务场景。
- **自动重连与通讯队列**：强健的网络自动重连机制，内置通讯队列管理，显著提升稳定性。
- **跨平台广泛兼容**：支持 .NET Framework 4.8, .NET Core, .NET 8/9/10，易于在各类项目中集成。
- **低代码、易集成**：简明配置，极低上手门槛，开箱即用，即插即扩展。
- **扩展友好**：遵循接口设计，易于扩展通讯协议与处理流程。

---

## ⚡️ 30秒快速体验

### 使用 Fluent Builder API（推荐）

```csharp
using CommBuilder;

// ==================== 顶层通讯口（无队列） ====================

// 1. 顶层点对点 - 串口
var port = Comm.Top()
    .UseSerial("COM3", 9600)
    .WithHeadFootParser([0xAA], [0x55])
    .OnReceived(data => Console.WriteLine(BitConverter.ToString(data)))
    .Build();

await port.OpenAsync();
await port.SendAsync([0x01, 0x02, 0x03]);

// 2. 顶层点对点 - TCP 客户端
var tcp = Comm.Top()
    .UseTcp("192.168.1.100", 9000)
    .WithHeadLengthParser([0xAA], data => data[2])
    .AutoReconnect()
    .Build();

await tcp.OpenAsync();

// 3. 顶层服务端 - TCP Server
var server = Comm.TopServer()
    .UseTcpServer("0.0.0.0", 9000)
    .WithHeadFootParser([0xAA], [0x55])
    .OnClientConnected(id => Console.WriteLine($"客户端连接: {id}"))
    .OnReceived((id, data) => Handle(data, id))
    .Build();

await server.OpenAsync();

// 4. 顶层服务端 - UDP 多对多
var udp = Comm.TopServer()
    .UseUdp("0.0.0.0", 9000)
    .WithTimeParser(50)
    .Build();

// ==================== 队列版本 ====================

// 乌鸦场景 - RS485 主从通讯（请求-响应队列）
// 解析器由协议层提供，外层只负责组装
var crow = Comm.Crow()
    .UseSerial("COM3", 9600)
    .WithParser(MyProtocol.CreateParser())
    .Timeout(5000)
    .SendInterval(20)
    .Build();

var protocol = new MyProtocol(crow);
await protocol.OpenAsync();
var response = await protocol.ReadValueAsync();

// 鸽子场景 - TCP 全双工（支持主动推送）
var pigeon = Comm.Pigeon()
    .UseTcp("192.168.1.100", 9000)
    .WithParser(MyProtocol.CreateParser())
    .Timeout(3000)
    .Build();

var pigeonProtocol = new MyProtocol(pigeon);
await pigeonProtocol.OpenAsync();

// 老鹰场景 - TCP Server（队列版本，多客户端管理）
var eagle = Comm.Eagle()
    .UseTcpServer("0.0.0.0", 9000)
    .WithParserFactory(MyProtocol.CreateParser)   // 每个客户端独立解析器
    .Build();

var eagleProtocol = new MyProtocol(eagle);
await eagleProtocol.OpenAsync();

// 麻雀场景 - UDP 多对多（队列版本）
var sparrow = Comm.Sparrow()
    .UseUdp("0.0.0.0", 9000)
    .WithTimeParser(50)
    .Build();

await sparrow.StartAsync();
```

### 传统方式

以TCP服务器接入为例：

```csharp
using Communication.Bus;
using Communication.Interfaces;

// 1. 创建TcpServer，配置端口
IBusPort tcpServer = new TcpServer("127.0.0.1", 9000);

// 2. 注册事件与回调
tcpServer.OnReceived += (sender, args) => {
    // 处理收到的数据包
};

// 3. 启动服务
tcpServer.StartAsync();
```

如需接入自定义协议，直接实现 `IParser` 即可无缝接入分包处理。

---

## 📦 安装方式

### 1. NuGet 包安装

```shell
# 核心库
NuGet\Install-Package CSoft.TopPortLib -Version 10.4.6

# Fluent Builder API（推荐）
NuGet\Install-Package CSoft.Communication.Builder -Version 10.4.6
```

### 2. 本地源码集成

下载 [GitHub项目](https://github.com/caoyiliang/Communication) 源码或将其作为子模块导入。

将 `/Communication`、`/TopPortLib`、`/Crow`、`/Parser`、`/CommBuilder` 等核心目录作为项目引用即可。

### 2. .NET平台兼容矩阵

- **.NET Framework 4.8** ✅
- **.NET Core** ✅
- **.NET 8, 9, 10** ✅

---

## 🛠️ 基础用法

### 多种通讯接口

#### 1. 串口通讯

```csharp
using Communication.Bus.PhysicalPort;

var serialPort = new SerialPort("COM1", 9600);
// 配置与启动
serialPort.OpenAsync();
```

#### 2. TcpClient 通讯

```csharp
using Communication.Bus.PhysicalPort;

var tcpClient = new TcpClient("127.0.0.1", 9000);
tcpClient.OpenAsync();
```

#### 3. 命名管道通讯

```csharp
using Communication.Bus.PhysicalPort;

var pipeClient = new NamedPipeClient("PipeName");
pipeClient.OpenAsync();
```

#### 4. 蓝牙通讯

```csharp
using Communication.Bluetooth;

var bluetooth = new BluetoothClassic("设备MAC地址");
bluetooth.ConnectAsync();
```

### 分包方式定制

实现 `IParser`，支持任意自定义协议：

```csharp
public class MyParser : IParser
{
    public IEnumerable<byte[]> Parse(byte[] buffer)
    {
        // 自定义分包算法...
    }
}
```

---

## 📚 API 参考

### 主要接口与类

#### 物理通讯口

- `IPhysicalPort`：物理口基接口（串口/TCP/蓝牙/命名管道等）
- `SerialPort, TcpClient, NamedPipeClient, BluetoothClassic`：各类物理口实现类
- `OpenAsync()/CloseAsync()`：开启/关闭通讯
- `SendAsync(byte[] data)`：发送数据

#### 逻辑通讯总线

- `IBusPort`：总线抽象层（数据包收发）
- `TcpServer, Udp, NamedPipeServer`：各类服务端实现
- `StartAsync()/StopAsync()`：启动/停止服务
- `OnReceived`：数据包接收事件

#### 分包处理

- `IParser`：数据包分割接口
- `BaseParser, HeadFootParser, HeadLengthParser, TimeParser`：内建协议分割实现
- 可自定义实现Protocol Parser，提升适用性

#### 异常处理

- `ConnectFailedException, NotConnectedException, SendException`（Communication/Exceptions）
- `RequestParameterToBytesFailedException, ResponseCreateFailedException`（TopPortLib/Exceptions）

#### 高阶抽象

- `TopPort, CondorPort, CrowPort, PigeonPort, CrowPort_Server`（TopPortLib）
    - 针对典型工业设备/协议接入的高阶抽象
    - 提供更丰富的命令控制与响应处理接口
    - 协议层只接收端口实例，不创建物理端口，实现完全解耦

---

## 🎯 进阶用法

### 使用 Fluent Builder API

CommBuilder 提供了简洁的 Fluent API，大幅降低入门门槛：

#### 如何选择？

- 需要管理多个客户端？
  - **是** → 服务端模式
    - 简单收发（无队列）→ `TopServer()`
      - TCP Server → `ITopPort_Server`
      - UDP M2M → `ITopPort_M2M`
    - 请求-响应队列 → `Eagle()` / `Sparrow()`
      - `Eagle()` → `ICondorPort`
      - `Sparrow()` → `ISparrowPort`
  - **否** → 点对点模式
    - 简单收发（无队列）→ `Top()`
      - 串口 / TCP / 管道 → `ITopPort`
    - 请求-响应队列 → `Crow()` / `Pigeon()`
      - `Crow()` → `ICrowPort`
      - `Pigeon()` → `IPigeonPort`

#### 六种场景

| 场景 | 适用协议 | 特点 | 返回类型 |
|------|----------|------|----------|
| **顶层 (Top)** | 串口/TCP客户端/管道 | 无队列，直接收发，最简单 | `ITopPort` |
| **顶层服务端 (TopServer)** | TCP Server/UDP | 无队列，服务端模式 | `ITopPort_Server` / `ITopPort_M2M` |
| **乌鸦 (Crow)** | RS485/串口/TCP | 主从队列，请求-响应模式 | `ICrowPort` |
| **鸽子 (Pigeon)** | TCP 全双工 | 支持被动推送，实时通讯 | `IPigeonPort` |
| **老鹰 (Eagle)** | TCP Server | 服务端多客户端管理 | `ICondorPort` |
| **乌鸦服务端 (Crow Server)** | TCP Server | 单客户端队列（为每个连接创建独立队列） | `ICrowPort` |
| **麻雀 (Sparrow)** | UDP | 多对多广播通讯 | `ISparrowPort` |

#### 无队列 vs 有队列

| 特性 | 无队列 (Top/TopServer) | 有队列 (Crow/Pigeon/Eagle/Sparrow) |
|------|------------------------|-----------------------------------|
| 发送方式 | `SendAsync(data)` 直接发送 | `RequestAsync<TReq, TRsp>(req)` 请求-响应 |
| 队列管理 | ❌ 无 | ✅ 自动排队，防止数据冲突 |
| 超时重试 | ❌ 无 | ✅ 请求超时自动重试 |
| 响应匹配 | ❌ 手动处理 | ✅ 自动通过 Response 类型匹配 |
| 适用场景 | 简单收发、自定义协议 | 工业设备、Modbus 等主从协议 |

#### 完整示例代码

##### 1. 顶层点对点 - 串口（无队列）

```csharp
using CommBuilder;

// 串口 + 头尾分包
var port = Comm.Top()
    .UseSerial("COM3", 9600)
    .WithHeadFootParser([0xAA], [0x55])
    .OnReceived(data => Console.WriteLine(BitConverter.ToString(data)))
    .OnConnected(() => Console.WriteLine("已连接"))
    .OnDisconnected(() => Console.WriteLine("已断开"))
    .Build();

await port.OpenAsync();

// 发送数据
await port.SendAsync([0x01, 0x02, 0x03]);
```

##### 2. 顶层点对点 - TCP（无队列）

```csharp
// TCP + 头长度分包 + 自动重连
var tcp = Comm.Top()
    .UseTcp("192.168.1.100", 9000)
    .WithHeadLengthParser([0xAA, 0x55], data => data[2])  // 帧头 + 长度字段
    .AutoReconnect()  // 断线自动重连
    .OnReceived(data => Handle(data))
    .Build();

await tcp.OpenAsync();
```

##### 3. 顶层服务端 - TCP Server（无队列）

```csharp
using CommBuilder;

// TCP Server，每个客户端独立分包器
var server = Comm.TopServer()
    .UseTcpServer("0.0.0.0", 9000)
    .WithHeadFootParser([0xAA], [0x55])
    .OnClientConnected(clientId => Console.WriteLine($"客户端连接: {clientId}"))
    .OnClientDisconnected(clientId => Console.WriteLine($"客户端断开: {clientId}"))
    .OnReceived((clientId, data) =>
    {
        Console.WriteLine($"收到来自 {clientId}: {BitConverter.ToString(data)}");
        // 处理数据后回复
        await server.SendAsync(clientId, [0x01, 0x02]);
    })
    .Build();

await server.OpenAsync();
```

##### 4. 顶层服务端 - UDP 多对多（无队列）

```csharp
// UDP 多对多
var udp = Comm.TopServer()
    .UseUdp("0.0.0.0", 9000)
    .WithTimeParser(50)  // 定时分包
    .OnReceived((clientId, data) => Handle(data))
    .Build();

await udp.OpenAsync();

// 添加目标客户端
var clientId = await udp.AddClientAsync("192.168.1.101", 9001);

// 向指定客户端发送
await udp.SendAsync(clientId, [0x01, 0x02, 0x03]);
```

##### 5. 乌鸦 - RS485 / TCP 主从队列

```csharp
// RS485 主从通讯，自动队列
// 协议层不创建端口，只接收端口；解析器也由协议层暴露
var crow = Comm.Crow()
    .UseSerial("COM3", 9600)
    .WithParser(MyProtocol.CreateParser())   // 协议层决定用什么解析器
    .Timeout(5000)
    .SendInterval(20)
    .Build();

var protocol = new MyProtocol(crow);   // 注入端口
await protocol.OpenAsync();
var response = await protocol.ReadValueAsync();
```

##### 6. 鸽子 - TCP 全双工

```csharp
// TCP 全双工，支持主动推送
var pigeon = Comm.Pigeon()
    .UseTcp("192.168.1.100", 9000)
    .WithParser(MyProtocol.CreateParser())
    .Timeout(3000)
    .Build();

var protocol = new MyProtocol(pigeon);
await protocol.OpenAsync();

// 请求-响应
var response = await protocol.ReadSignalValueAsync();
```

##### 7. 乌鸦服务端 - TCP Server 单客户端队列

```csharp
// 为每个 TCP 连接创建独立的 Crow 队列
var server = Comm.TopServer()
    .UseTcpServer("0.0.0.0", 9000)
    .WithParserFactory(MyProtocol.CreateParser)   // 每个客户端独立解析器
    .Build();

await server.OpenAsync();

server.OnClientConnect += async clientId =>
{
    var crowServer = new CrowPort_Server(server, clientId);
    var protocol = new MyProtocol(crowServer);   // 协议层支持 ICrowPort
    await protocol.OpenAsync();
};
```

#### 连接字符串支持

```csharp
// 支持连接字符串快速创建
var crow = Comm.Crow()
    .FromConnectionString("serial://COM3:9600:N:8:1")
    .WithHeadFootParser([0xAA], [0x55])
    .Build();

var pigeon = Comm.Pigeon()
    .FromConnectionString("tcp://192.168.1.100:9000")
    .WithHeadLengthParser([0xAA], data => data[2])
    .Build();
```

连接字符串格式：
- 串口: `serial://COM3:9600` 或 `serial://COM3:9600:N:8:1`
- TCP: `tcp://192.168.1.100:9000`
- 命名管道: `pipe://PipeName`

### 自定义分包协议接入

只需实现 `IParser` 接口，即可用自定义协议处理底层字节流。例如：

```csharp
public class CustomParser : IParser { ... }
ITopPort port = new TopPort(new TcpClient("127.0.0.1", 9000), new CustomParser());
```

### 上层协议栈封装

`TopPortLib` 提供了对工业协议常用模式的抽象，可灵活叠加堆栈组合业务逻辑，如异步M2M、设备逻辑拆分等。

### 协议层自动 Builder 生成（Source Generator）

每次新增一个协议类，都需要手写大量重复的 Builder 包装代码（物理口选择、解析器注入、配置转发等）。

本库内置了 `TopPortLib.SourceGenerators`，只需给协议类加上一个 Attribute，编译器会自动生成对应的 Fluent Builder 静态方法。

#### 支持的场景

| Attribute | 对应场景 | 生成的入口方法 | 配置方法 |
|-----------|----------|---------------|----------|
| `[AutoCrowPortBuilder]` | 乌鸦 (Crow) | `UseTcp` / `UseSerial` / `UseNamedPipe` / `FromConnectionString` | `Timeout` / `SendInterval` / `OnReceived` / `OnConnected` / `OnDisconnected` |
| `[AutoPigeonPortBuilder]` | 鸽子 (Pigeon) | `UseTcp` / `UseSerial` / `UseNamedPipe` / `FromConnectionString` | `Timeout` / `SendInterval` / `WithCheck` |
| `[AutoCondorPortBuilder]` | 老鹰 (Eagle/Condor) | `UseTcpServer` | `Timeout` / `OnClientConnected` / `OnClientDisconnected` / `OnReceived` / `OnSent` |
| `[AutoSparrowPortBuilder]` | 麻雀 (Sparrow) | `UseUdp` | `Timeout` / `OnClientDisconnected` / `OnSent` |

#### 使用条件

协议类只需满足一个条件：提供 **`public static IParser CreateParser()`** 方法（供生成器自动注入解析器）。

其余全部由 Source Generator 在编译期自动生成：
- **业务接口**（`ICrowPortProtocol` 等，自动从 Request/Response 配对推断方法签名）
- **业务方法**（根据命名约定 `ReadValueReq` + `ReadValueRsp` → `ReadValueAsync()`，自动传播 Request 构造参数及默认值）
- **主动推送事件**（在 Response 类上标记 `[ActivelyPushResponse]` 即可自动生成 `On{Event}` 事件与注册逻辑）
- **基类**（`CrowPortProtocolBase`，包含 `_port`、状态、事件、日志）
- **接口实现声明**（`I{className}` 由生成器自动附加到 `partial class`）
- **构造函数**（端口赋值、Response 注册、主动推送注册、日志事件订阅）
- **Fluent Builder 入口**（`UseTcp` / `UseSerial` 等静态方法）
- **连接状态**（`IsConnect` / `IsListened`）
- **发送/接收 Trace 日志**（自动输出到 `ILogger`，无需手写）
- **OpenAsync / CloseAsync / StartAsync**

#### 使用示例

```csharp
using TopPortLib;
using Parser.Interfaces;
using Parser.Parsers;

namespace CrowPortProtocolDemo
{
    [AutoCrowPortBuilder]   // ← 加这一行即可
    public partial class CrowPortProtocol
    {
        public static IParser CreateParser() => new FootParser([0x0d]);

        // 只需写业务方法，其他全部自动生成
        public async Task<List<decimal>?> ReadValueAsync() { /* ... */ }
    }
}
```

#### 主动推送（自动事件生成）

只需在 Response 类上标记 `[ActivelyPushResponse]`，生成器会自动创建事件与注册逻辑：

```csharp
using TopPortLib;

namespace PigeonPortProtocolDemo
{
    [ActivelyPushResponse]  // ← 标记这一行
    public partial class ReadValueRsp : IAsyncResponse<(List<decimal> recData, int result)>
    {
        // ... 解析逻辑
    }
}
```

编译器自动生成：
```csharp
public event ActivelyPushDataEventHandler<(List<decimal> recData, int result)>? OnReadValue;
private async Task ReadValueRspEvent((List<decimal> recData, int result) value)
    => OnReadValue?.Invoke(value);
```

#### 业务方法自动生成

只要按约定命名 `ReadValueReq` + `ReadValueRsp`，生成器会自动推断并生成 `ReadValueAsync` 方法。

> Crow 模式（一问一答）下无需任何特性标注，命名约定即可自动配对。Req 和 Rsp 可分别放在 `Request` / `Response` 子命名空间下，只要去掉后缀后的名称一致即可配对。

```csharp
// Request（构造参数会自动传播到生成的方法签名）
public partial class ReadValueReq(string addr = "01") : IAsyncRequest { ... }

// Response
public partial class ReadValueRsp : IAsyncResponse<(List<decimal> recData, int result)> { ... }
```

自动生成的方法签名：
```csharp
public virtual async Task<(List<decimal> recData, int result)?> ReadValueAsync(
    string addr = "01", CancellationToken cancellationToken = default)
```

外部使用时，无需再手动组装 `Comm.Crow()` 和 `WithParser()`：

```csharp
using CrowPortProtocolDemo;

// 解析器已自动注入，外部只关心物理口
var protocol = CrowPortProtocol.UseTcp("127.0.0.1", 2756)
    .Timeout(5000)
    .Build();

await protocol.OpenAsync();
var value = await protocol.ReadValueAsync();
```

**Sparrow（UDP 多对多）示例**：

```csharp
using TopPortLib;
using Parser.Interfaces;
using Parser.Parsers;

namespace SparrowPortProtocolDemo
{
    [AutoSparrowPortBuilder]   // ← 麻雀模式
    public partial class SparrowPortProtocol
    {
        public static IParser CreateParser() => new FootParser([0x0d]);
    }
}

// 使用
using SparrowPortProtocolDemo;

var protocol = SparrowPortProtocol.UseUdp("0.0.0.0", 2757)
    .Timeout(5000)
    .Build();

await protocol.StartAsync();

// UDP 需主动添加客户端
var clientId = await protocol.AddClientAsync("192.168.1.100", 2758);
var value = await protocol.ReadValueAsync(clientId);
```

#### 与传统方式对比

**传统方式**（需要手写 80+ 行 Boilerplate）：

```csharp
var crow = Comm.Crow()
    .UseTcp("127.0.0.1", 2756)
    .WithParser(MyProtocol.CreateParser())   // 手动注入
    .Timeout(5000)
    .Build();
var protocol = new MyProtocol(crow);
```

**自动生成方式**（零重复代码）：

```csharp
var protocol = MyProtocol.UseTcp("127.0.0.1", 2756)
    .Timeout(5000)
    .Build();   // CreateParser() 自动注入，一步到位
```

#### 技术说明

- 生成器在编译期运行，不增加运行时开销。
- 生成的代码与手写代码完全等价，享有相同的 IntelliSense 和类型安全。
- 如需查看生成结果，可在项目文件中开启 `<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>`，生成文件将输出到 `obj/generated/` 目录。

### 测试示例工程

`/TestDemo` 下包含众多实际协议、分包和通讯测试用例，例如：
- `TestNamedPipeClient`, `TcpServer`, `TestUdp1`, `CondorPortProtocolDemo` 等，
提供从基础通讯到进阶协议解码的全流程样例。

---

## 🔧 配置选项

支持自定义通讯参数，如串口波特率、网络端口、协议分包超时时间等，大多通过构造函数或属性设置即可。

```csharp
var serial = new SerialPort(portName: "COM2", baudRate: 9600, parity: Parity.None);
```

对于高级需求，参见各类接口提供的扩展属性（详见源码与examples）。

---

## 🧩 主要集成与扩展方式

### 框架支持

- 原生支持WPF、WinForms、控制台等任何.NET工程类型。
- 作为通讯层可与业务中间件、工业协议栈、SCADA系统无缝集成。

### 扩展插件机制

- 任意新增通讯协议，仅需实现对应接口 (`IPhysicalPort`, `IParser`)。
- 可叠加应用层协议，伴随队列、重连、缓存、事件驱动等机制。

---

## 📊 性能与质量

- **异步架构，高并发友好**：所有通讯操作异步实现，不卡UI。
- **内存优化**：分包算法避免无效字节流淤积，内建安全防护。
- **稳定性保障**：自愈通讯机制，断线自动重连，错误有效上报。

---

## 🔗 兼容性与升级指南

- **兼容 .NET Framework 4.8, .NET Core, .NET 8/9/10**，支持绝大多数主流.NET应用环境。
- 新增协议或通讯方式时，仅需实现标准接口，无需修改核心库。
- 原有分包/设备逻辑如需迁移，仅需替换配置，无需重构业务代码。

---

## 🕹️ 学习与支持

### 入门建议

1. 从TestDemo工程实际运行示例开始理解调用方式与数据流转。
2. 仔细阅读各接口源文件与内建Parser算法实现，理解协议扩展机制。
3. 如有业务特殊需求，优先选择继承/实现相关接口适配扩展。

### 社区与维护

- [源码仓库](https://github.com/caoyiliang/Communication)
- 欢迎issue/PR，共同维护完善
- 框架持续维护，适配新协议和.NET新特性

---

## 更新日志

### v10.4.6

- **依赖包升级**：
  - `CSoft.Utils` 10.0.4 → 10.0.5
  - `System.IO.Ports` / `System.IO.Pipelines` / `System.Threading.Channels` 10.0.7 → 10.0.8
  - `CSoft.LogInterface` 1.0.0 → 10.0.0（Crow 项目版本修正）
  - `MSTest` 4.2.2 → 4.2.3（测试项目）

### v10.4.5

- **TimeParser 稳定性修复**：
  - 移除基于 `TimeInterval` 的定时器超时轮询机制，改为直接调用 `reader.ReadAsync`，简化流程并避免超时竞争。
  - `Dispose` 时先释放定时器、等待后台 `HandleDataAsync` 任务完成，再取消 CTS 和释放信号量，避免任务泄漏与资源竞争。
  - 正确处理 `OperationCanceledException` 和 `IOException`，遇到时直接退出解析循环。
- **StreamPipeReader 健壮性增强**：
  - 新增对 `IOException`（`InnerException` 为 `SocketException` 且 `NativeErrorCode: 995`，即操作已取消）的捕获，避免 socket 异常关闭时抛未处理异常。

### v10.4.3

- **TcpServer/TcpClient 稳定性修复**：
  - 修复 `TcpServer.SendDataAsync` 前置 `Connected` 检查导致的非原子性问题，改为直接写入、异常时清理，避免误判连接状态。
  - 修复 `TcpClient.IsOpen` 中 `Poll(1)` 超时太短（1 微秒）导致的漏判问题，简化为直接检查 `Connected`。
  - 修复 `TcpClient.CloseAsync` 重复 Dispose `NetworkStream` 的顺序问题，避免资源关闭混乱。
  - 修复 `TcpClient` 同步 `Dispose` 中阻塞等待异步 `CloseAsync` 的潜在死锁风险。
  - 修复 `TcpServer.StopAsync` 未清理 `CancellationTokenSource` 和 `PipeReader` 的问题，使用 `ToArray()` 避免遍历时字典被修改。
- **BusPort 发送失败处理**：
  - `BusPort.SendAsync` 发送失败时主动触发断开流程，避免依赖轮询检测延迟发现断连。
- **测试增强**：
  - 新增 `TcpServer` 集成测试，验证客户端断开后服务端发送异常并正确清理字典。
  - 新增 `TcpServer.StopAsync` 测试，验证多客户端场景下资源完整释放。

### v10.4.1

- **StreamPipeReader 关键修复**：
  - 修复 `AdvanceTo(consumed, examined)` 双参数重载未正确处理 `examined` 位置，导致 `_consumed` 可能回退的问题。
  - 修复 Parser 部分消费数据后，`ReadAsync` 重复返回已消费数据的问题。
  - 修复 Parser 检查到缓冲区末尾但找不到完整帧时无法触发新数据读取的问题（新增 `_examinedToEnd` 标志）。
  - `StreamPipeReader` 使用 `ReadOnlySequence<byte>` 新构造函数优化内存布局。
- **测试增强**：
  - 新增 Crow 模式端到端集成测试（`CrowEndToEndTests`），覆盖请求发送-响应注入-帧拆分完整链路。
  - 新增 `StreamPipeReader` 边界条件单元测试，验证部分消费、多次 Advance、examined-to-end 等场景。

### v10.4.0

- **Parser 全面重构，支持 PipeReader 零拷贝数据流**：
  - `IParser` 新增 `ReceiveOriginalDataAsync(ReadOnlyMemory<byte>)` 非零拷贝路径（测试/简单场景）。
  - 新增 `StreamPipeReader` 统一流管道读取器，消除各物理口重复代码。
  - `BaseParser` 重构为基于 `ParseSequenceAsync` 虚方法，`RunAsync` 改为虚方法，所有内置 Parser 全面适配。
- **通讯层与解析层彻底解耦**：
  - `IPhysicalPort.Input` 重命名为 `PipeReader`，职责更清晰。
  - `BusPort` 移除 `Parser` 属性，解析职责完全上浮至 `TopPortLib`。
  - 所有物理口（SerialPort/TcpClient/NamedPipeClient/BluetoothClassic）统一改用 `StreamPipeReader` 封装。
- **TopPortLib 适配新架构**：所有端口（TopPort/TopPort_Server/TopPort_M2M/CrowPort/PigeonPort/CondorPort/SparrowPort）改为独立启动 Parser 任务。
- **ResponseRegistry 性能优化**：新增 `TryMatchClient` / `TryMatchServer`，使用缓存 Check 实例避免重复创建对象。
- **Bug 修复**：
  - 修复 BusPort 重连空转（`_closeCts` 重建逻辑）。
  - 修复 SendDataAsync 中使用同步 Write 阻塞线程池。
  - 修复 SerialPort Dispose 递归 StackOverflow。
  - 修复 Udp 空包导致整个接收循环终止。
  - 修复 Udp ConcurrentDictionary 竞态条件（SemaphoreSlim 保护）。
  - 修复 TcpServer/NamedPipeServer/BluetoothClassic_Server 客户端断开未清理。
  - 修复 PigeonPort/CondorPort/SparrowPort 事件回调中 throw 会中断 Parser 事件链。
  - 修复 PigeonPort/CondorPort 多响应竞态条件（lock + Interlocked.Exchange）。
  - 修复 TilesLayer / TilesLayer_Server 事件订阅泄漏。
  - 修复 CrowLayer 竞态条件。
  - 修复 TopPort/TopPort_Server/CrowPort Dispose 死锁风险。

### v10.3.1

- **源生成器新增 Sparrow（麻雀）模式支持**：`[AutoSparrowPortBuilder]` 完整支持 Builder / 接口 / 业务方法 / 主动推送事件自动生成，与 Crow / Pigeon / Condor 保持一致。
- **源生成器为全模式自动添加 `OnSentData` / `OnReceivedData` 事件转发**：Crow / Pigeon / Condor / Sparrow 四种模式均已支持，无需手写日志订阅。
- **Sparrow 接口自动生成 `AddClientAsync` / `RemoveClientAsync`**：UDP 多对多场景需主动管理客户端，生成器已自动暴露到协议接口。

### v10.3.0

- **Crow 模式移除 `[CrowResponse]` 特性依赖**，改为按命名约定自动配对（`XxxReq` + `XxxRsp`）。
- **源生成器支持全模式自动生成**：Crow / Pigeon / Condor 三种场景均支持自动生成业务接口、业务方法、主动推送事件、构造函数、连接状态、日志订阅、`OpenAsync` / `CloseAsync`。
- **接口生成器修复**：跳过无泛型返回的 Response，避免 `CS0050`。
- **Crow 模式生成器修复**：跳过无 `Result` 属性的 Response，避免 `CS0050`。
- **全面补全 XML 文档注释**：所有公共 API 均已补充中文 XML 注释，提升 IntelliSense 体验。

### v10.2.x

- 支持源生成器全自动生成（CrowResponse 特性自动配对）。
- 重构命名空间以统一 Protocol 和 Protocol.Model。
- 新增 `ActivelyPushResponse` 特性，支持主动推送事件自动生成。

## 总结

Communication 通讯库是 .NET 下通用高扩展性的通讯中间件，开箱即用，易于扩展，可显著提升上位机通讯开发效率，减少代码出错概率并提升系统健壮性。适合各类工控、物联网、业务信息系统场景。

**立即集成，专注业务，高效通讯！**