C# 和 .NET 新增

适用于 .NET 的 C# Modbus TCP 和 RTU 库

通过以太网或 RS-485,用 C# 读写 PLC、驱动器和仪表,或者作为 Modbus 从站提供您自己的数据。

Modbus TCP 和 Modbus RTU
客户端和服务器
任意字序的 Float32、Int32 和字符串
线程安全的阻塞调用

包含在 sgcWebSockets Enterprise(Delphi 和 .NET)和 All-Access 或独立的 sgcIndustrial 软件包中。

用 C# 读写设备 → · Modbus 常见问题 →

C# Modbus TCP 客户端
using esegece.sgcWebSockets;

var modbus = new TsgcModbusTCPClient();
modbus.Host = "192.168.1.50";
modbus.Port = 502;
modbus.Active = true;

ushort[] registers = modbus.ReadHoldingRegisters(0, 10);  // FC 03
float temperature = modbus.ReadFloat32(200);               // 2 registers
modbus.WriteSingleCoil(5, true);                           // FC 05

适用于 .NET 的 Modbus 客户端和服务器

四个组件,TCP 和 RTU 共用一套 API,服务器背后是线程安全的数据模型。

sgcWebSockets .NET 中的 C# Modbus 库位于 esegece.sgcIndustrial 包,命名空间为 esegece.sgcWebSockets。TsgcModbusTCPClient 和 TsgcModbusRTUClient 是轮询设备的 Modbus 主站;TsgcModbusTCPServer 和 TsgcModbusRTUServer 是 Modbus 从站,基于 TsgcModbusDataModel 应答 SCADA 系统、HMI 和其他主站。串行线路是同一个包中的 TsgcSerialPort,基于 System.IO.Ports 构建。

两个客户端共用 TsgcModbusClient_Base,因此通过以太网读取寄存器的方法同样可以通过 RS-485 读取。每次调用都会阻塞,直到收到应答或 Timeout 到期,返回普通的 .NET 数组(寄存器为 ushort[],线圈为 bool[]),设备报告错误时抛出类型明确的异常。该包面向 .NET 8、.NET 9、.NET 10 和 .NET Standard 2.0。

功能码

01 到 08、15、16、22、23 和 43/14,每个功能码对应一个方法。

类型化数值

ReadFloat32、ReadInt32、ReadUInt32、ReadString 及对应的写入方法,通过 WordOrder 支持四种寄存器布局。

Modbus TCP

默认端口 502,可选 TLS、HTTP 或 SOCKS 代理以及自动重连。

Modbus RTU

RS-232 和 RS-485,支持 3.5 字符帧间隔、CRC 校验和广播写入。

C# 中的 Modbus,分步说明

引用 esegece.sgcIndustrial 包,然后选择传输方式。本页的每个示例都可以针对 .NET 8 编译。

using esegece.sgcWebSockets;

var modbus = new TsgcModbusTCPClient();
modbus.Host = "192.168.1.50";
modbus.Port = 502;
modbus.UnitId = 1;
modbus.Timeout = 2000;            // ms per attempt
modbus.Retries = 2;               // extra attempts after a timeout
modbus.WatchDog.Enabled = true;   // reconnect after a network drop
modbus.OnError += (sender, error) => Console.WriteLine("#error: " + error);
modbus.Active = true;

ushort[] registers = modbus.ReadHoldingRegisters(0, 10);       // FC 03
bool[] coils = modbus.ReadCoils(0, 8);                         // FC 01
Console.WriteLine("HR0 = " + registers[0] + ", coil 0 = " + coils[0]);

modbus.WriteSingleRegister(100, 1234);                         // FC 06
modbus.WriteMultipleRegisters(110, new ushort[] { 1, 2, 3 });  // FC 16
modbus.WriteSingleCoil(5, true);                               // FC 05
modbus.WordOrder = TsgcModbusWordOrder.mwoCDAB;   // low word first
float temperature = modbus.ReadFloat32(200);       // 2 holding registers
int counter = modbus.ReadInt32(202);
string name = modbus.ReadString(300, 8);           // 8 registers, 16 characters
Console.WriteLine($"{name}: {temperature:F1} C, {counter} cycles");

modbus.WriteFloat32(210, 21.5f);
modbus.WriteUInt32(212, 3000000000);

// explicit unit id, for a gateway with several devices behind it
float flow = modbus.ReadInputFloat32(7, 0);        // unit 7, FC 04
Console.WriteLine("flow = " + flow);

try
{
    modbus.ReadHoldingRegisters(9000, 4);
}
catch (EsgcModbusException e)   // the device answered with an exception
{
    Console.WriteLine($"exception {e.ExceptionCode}, function {e.FunctionCode}");
}
catch (EsgcModbusTimeout e)     // no answer after Retries + 1 attempts
{
    Console.WriteLine(e.Message);
}
using esegece.sgcWebSockets;

var port = new TsgcSerialPort();
port.Port = "COM3";                              // "/dev/ttyUSB0" on Linux
port.BaudRate = 19200;
port.Parity = TsgcSerialParity.spEven;           // 8E1, the Modbus RTU default
port.Open();

var rtu = new TsgcModbusRTUClient();
rtu.SerialPort = port;
rtu.UnitId = 17;                                 // slave address
rtu.Timeout = 500;
rtu.Retries = 1;

ushort[] values = rtu.ReadInputRegisters(0, 4);  // FC 04
byte status = rtu.ReadExceptionStatus();         // FC 07
Console.WriteLine($"IR0 = {values[0]}, status = {status}");

rtu.WriteSingleRegister(0, 10, 500);             // unit 0: broadcast, no reply
using esegece.sgcWebSockets;

var server = new TsgcModbusTCPServer();
server.Port = 502;
server.UnitId = 0;                                  // answer every unit id
server.DataModel.HoldingRegisterCount = 1000;
server.DataModel.SetHoldingRegister(0, 42);
server.DataModel.SetCoil(0, true);
server.DataModel.VendorName = "My Company";         // FC 43/14 identification
server.DataModel.ProductCode = "GW-100";

var random = new Random();

// runs on the connection thread, before the table is read
server.OnReadRequest += (object sender, byte unitId, byte functionCode,
    ushort address, ushort count, ref byte exceptionCode) =>
{
    if (functionCode == sgcModbus_Classes.CS_MODBUS_FC_READ_INPUT_REGISTERS)
        server.DataModel.SetInputRegister(0, (ushort)random.Next(1000));
};

// registers 0..9 are read only
server.OnWriteRequest += (object sender, byte unitId, byte functionCode,
    ushort address, ushort count, ref bool[] bits, ref ushort[] registers,
    ref byte exceptionCode) =>
{
    if (registers.Length > 0 && address < 10)
        exceptionCode = sgcModbus_Classes.CS_MODBUS_EX_ILLEGAL_DATA_ADDRESS;
};

server.Active = true;
Console.ReadLine();

这些调用是同步的。在 WinForms、WPF 或 ASP.NET 应用程序中,请在工作线程或 Task.Run 内运行轮询循环;客户端是线程安全的,因此多个任务可以共用一个连接。

支持的 Modbus 功能码

客户端会在发送任何数据之前根据规范检查数量;服务器会应答此表中的每个功能码。

FC功能C# 方法
01Read CoilsReadCoils
02Read Discrete InputsReadDiscreteInputs
03Read Holding RegistersReadHoldingRegisters, ReadInt32, ReadUInt32, ReadFloat32, ReadString
04Read Input RegistersReadInputRegisters, ReadInputInt32, ReadInputUInt32, ReadInputFloat32
05Write Single CoilWriteSingleCoil
06Write Single RegisterWriteSingleRegister
07Read Exception Status(串行线路)RTU 客户端上的 ReadExceptionStatus
08Diagnostics(串行线路)RTU 客户端上的 Diagnostics
15Write Multiple CoilsWriteMultipleCoils
16Write Multiple RegistersWriteMultipleRegisters, WriteInt32, WriteUInt32, WriteFloat32, WriteString
22Mask Write RegisterMaskWriteRegister
23Read/Write Multiple RegistersReadWriteMultipleRegisters
43/14Read Device IdentificationReadDeviceIdentification,配合 TsgcModbusDeviceIdCode 的 basic、regular、extended 或 specific

为生产环境打造的 Modbus 主站

字序

TsgcModbusWordOrder.mwoABCD 为大端,是 Modbus 的默认值。mwoCDAB 把低位字放在前面,mwoBADC 交换每个寄存器内的字节,mwoDCBA 则完全为小端。字符串每个寄存器打包两个字符。

线程安全

每个客户端同一时间只运行一个事务,由覆盖其所有重试的锁保护。在 TCP 上,应答由接收线程匹配并交给等待的调用,因此从 UI 线程调用不会发生死锁。

超时和重试

Timeout 是每次尝试的等待时间,Retries 是额外的尝试次数。TCP 重试使用新的事务 ID,过期或重复的应答会被丢弃。

类型化异常

EsgcModbusException 携带 ExceptionCode 和 FunctionCode,EsgcModbusTimeout 报告未收到应答,EsgcModbusError 涵盖连接关闭、端口问题和 RTU CRC 错误。

网关和单元 ID

每个方法都有一个带前置 byte aUnitId 的重载,因此到网关的一个 TCP 连接就可以访问其后的每台设备。

TLS、代理和重连

TLS、TLSOptions、Proxy 和 WatchDog 会传递给底层的 sgcWebSockets TCP 客户端,因此 Modbus TCP 与库中的其他部分一样拥有相同的 TLS 栈、代理支持和自动重连。

RTU 帧

RTU 客户端在发送前等待 3.5 个字符的静默时间,按预期长度读取应答,检查每一帧的 CRC,并忽略来自其他从站地址的帧。单元 ID 0 发送广播写入,并等待 TurnaroundDelay 而不是应答。

RS-485 方向

使用 RtsControl = TsgcSerialRtsControl.srcToggle 时,串口会在每次写入时拉高 RTS,并在输出缓冲区排空后拉低。在 .NET 中这是由软件计时的,因此如果对总线时序要求严格,建议使用带自动方向控制的适配器。

事件

OnConnect、OnDisconnect 和 OnError 通过 NotifyEvents 按发生顺序触发。连接失败时不会抛出异常,而是触发 OnError,Active 保持为 false。

C# 中的 Modbus TCP 和 RTU 服务器

可以构建把数据库或云端的值提供给 SCADA 系统的网关,无需硬件即可测试 HMI 画面的模拟器,或者您自己设备的 Modbus 接口。每个服务器拥有一个 TsgcModbusDataModel,包含四张表(线圈、离散输入、保持寄存器和输入寄存器,默认各 10,000 项,最多 65,536 项)、FC 43/14 的标识字符串以及 FC 07 的异常状态。数据模型的每个成员都是线程安全的。

OnReadRequest 在读取表之前运行,因此可以刷新数值或以异常码应答。OnWriteRequest 在值存储之前接收它们,可以修改或拒绝写入,使表保持不变。两者都在处理请求的服务器线程(TCP 连接或 RTU 帧读取器)中运行,且不持有任何锁。

TsgcModbusTCPServer

支持大量并发连接,请求按到达顺序应答,拆分的请求会被重新组装,格式错误的报文头会关闭连接并触发 OnError。UnitId = 0 应答任意单元 ID。Bindings 选择端点,Port = 0 选取空闲端口,OnClientConnect 和 OnClientDisconnect 报告对端。

TsgcModbusRTUServer

在 TsgcSerialPort 上以从站 UnitId(1 到 247)应答,按长度和 3.5 字符静默时间对请求分帧,忽略错误的 CRC 和其他地址,并执行广播写入而不回复。

双向测试

.NET 客户端和服务器与 pymodbus(通过 TCP)以及 sgcWebSockets Delphi Modbus 组件通过了相同的互操作性检查,每个方向均为 35 项全部通过。

属于 sgcWebSockets Enterprise

Modbus 和串口组件包含在 sgcWebSockets Enterprise(Delphi 和 .NET)和 All-Access 中,作为 esegece.sgcIndustrial 包,与其他 sgcWebSockets .NET 包放在一起。可在定价页面(.NET 标签)或 .NET 功能矩阵中比较各版本。

C# Modbus 常见问题

创建 TsgcModbusTCPClient,设置 Host、Port 和 UnitId,设置 Active = true,然后调用 ReadHoldingRegisters(address, count)。它返回 ushort[],每个寄存器对应一个值。地址从零开始,与线路上传输的一致。

对保持寄存器调用 ReadFloat32(address),对输入寄存器调用 ReadInputFloat32(address)。如果数值看起来不对,说明设备以另一种顺序存储这两个寄存器:请把 WordOrder 设置为 mwoCDAB、mwoBADC 或 mwoDCBA。

支持。在 RS-485 适配器上打开 TsgcSerialPort,并把它赋给 TsgcModbusRTUClient.SerialPort 或 TsgcModbusRTUServer.SerialPort。使用带自动方向控制的适配器,或者对由 RTS 切换的适配器把 RtsControl 设置为 srcToggle。

可以。创建 TsgcModbusTCPServer,用 SetHoldingRegister、SetCoil 和其他设置方法填充 DataModel,然后设置 Active = true。处理 OnReadRequest 和 OnWriteRequest,即可按需计算数值,或用 Modbus 异常码拒绝写入。

没有,客户端方法是同步且线程安全的。请从工作线程调用,或用 Task.Run 包装;多个线程或任务可以共用一个客户端,每次调用都会等待自己的应答。

esegece.sgcIndustrial 包面向 .NET 8、.NET 9、.NET 10 和 .NET Standard 2.0。串口使用 System.IO.Ports,因此 Modbus RTU 需要该包能够打开串口的平台。

Modbus 和串口组件包含在 sgcWebSockets Enterprise(Delphi 和 .NET)和 All-Access 或独立的 sgcIndustrial 软件包中。

更多 sgcWebSockets .NET 内容

工业组件

串口、Modbus 和 OPC UA,附完整的组件参考。

C# OPC UA 客户端

在同一个 .NET 应用程序中读取、写入和订阅 OPC UA 服务器,与 Modbus 设备并用。

C# MQTT 客户端

在同一个应用程序中把 Modbus 读数发布到 MQTT 代理。

C# WebSocket 库

WebSocket 客户端和服务器,用于显示实时设备数据的仪表板。

也适用于 Delphi 和 C++Builder

相同的 Modbus 组件,类名和方法也相同,适用于 Delphi 7 到 Delphi 13。

超值之选:All-AccesseSeGeCe 全部产品,含高级支持,每年 €1,059 起。
查看 All-Access 价格

用 C# 读取您的第一个 Modbus 寄存器

包含在 sgcWebSockets Enterprise(Delphi 和 .NET)和 All-Access 或独立的 sgcIndustrial 软件包中。