CSoft.TopPortLib 10.2.2

概述

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（推荐）

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 protocol = new MyProtocol(pigeon);
await protocol.OpenAsync();

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

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

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

await sparrow.StartAsync();

传统方式

以TCP服务器接入为例：

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 包安装

# 核心库
NuGet\Install-Package CSoft.TopPortLib -Version 10.2.2

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

2. 本地源码集成

下载 GitHub项目 源码或将其作为子模块导入。

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

2. .NET平台兼容矩阵

• .NET Framework 4.8 ✅
• .NET Core ✅
• .NET 8, 9, 10 ✅

---

🛠️ 基础用法

多种通讯接口

1. 串口通讯

using Communication.Bus.PhysicalPort;

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

2. TcpClient 通讯

using Communication.Bus.PhysicalPort;

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

3. 命名管道通讯

using Communication.Bus.PhysicalPort;

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

4. 蓝牙通讯

using Communication.Bluetooth;

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

分包方式定制

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

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. 顶层点对点 - 串口（无队列）

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（无队列）

// 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（无队列）

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 多对多（无队列）

// 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 主从队列

// 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 全双工

// 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 单客户端队列

// 为每个 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();
};

连接字符串支持

// 支持连接字符串快速创建
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 接口，即可用自定义协议处理底层字节流。例如：

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

使用条件

协议类只需满足一个条件：提供 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

使用示例

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]，生成器会自动创建事件与注册逻辑：

using TopPortLib;

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

编译器自动生成：

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 方法：

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

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

自动生成的方法签名：

public virtual async Task<(List<decimal> recData, int result)?> ReadValueAsync(
    string addr = "01", CancellationToken cancellationToken = default)

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

using CrowPortProtocolDemo;

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

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

与传统方式对比

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

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

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

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

技术说明

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

测试示例工程

/TestDemo 下包含众多实际协议、分包和通讯测试用例，例如：

• TestNamedPipeClient, TcpServer, TestUdp1, CondorPortProtocolDemo 等， 提供从基础通讯到进阶协议解码的全流程样例。

---

🔧 配置选项

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

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，支持绝大多数主流.NET应用环境。
• 新增协议或通讯方式时，仅需实现标准接口，无需修改核心库。
• 原有分包/设备逻辑如需迁移，仅需替换配置，无需重构业务代码。

---

🕹️ 学习与支持

入门建议

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

社区与维护

• 源码仓库
• 欢迎issue/PR，共同维护完善
• 框架持续维护，适配新协议和.NET新特性

---

总结

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

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