现场优化7

DeviceCommand/Flexible/FModbusTCP.cs

@@ -8,11 +8,20 @@ using System.Threading.Tasks;
 
 namespace DeviceCommand.Flexible
 {
+    /// <summary>
+    /// 灵活型 Modbus TCP 通信类（免实例化，每次调用临时建立 TCP 连接）。
+    /// 支持保持寄存器与线圈的读写操作，内部使用通信锁保证同一时刻只有一个事务在执行，
+    /// 适用于偶发性、无需保持长连接的 Modbus TCP 设备读写场景。
+    /// </summary>
     [ADPCommand]
     public static class FModbusTCP
     {
+        // 通信锁：保证同一时刻只有一个 Modbus 事务在执行
         private static readonly SemaphoreSlim _commLock = new(1, 1);
 
+        /// <summary>
+        /// 建立 TCP 连接并创建 Modbus TCP 主站。
+        /// </summary>
         private static  async Task<IModbusMaster> ConnectAsync(string ipAddress, int port, int sendTimeout, int receiveTimeout, CancellationToken ct)
         {
             var tcpClient = new TcpClient();
@@ -26,7 +35,19 @@ namespace DeviceCommand.Flexible
 
         #region Holding Registers
 
-        public static async Task<ushort[]> ReadHoldingRegistersAsync(
+        /// <summary>
+        /// 读取保持寄存器（功能码 03），返回指定数量的寄存器值数组。
+        /// </summary>
+        /// <param name="ipAddress">设备 IP 地址</param>
+        /// <param name="port">Modbus TCP 端口号，默认常用 502</param>
+        /// <param name="slaveAddress">Modbus 从站站号（单元标识符）</param>
+        /// <param name="startAddress">起始寄存器地址</param>
+        /// <param name="numberOfPoints">读取的寄存器数量</param>
+        /// <param name="sendTimeout">发送/连接超时时间（毫秒），默认 3000</param>
+        /// <param name="receiveTimeout">接收超时时间（毫秒），默认 3000</param>
+        /// <param name="ct">异步取消令牌</param>
+        /// <returns>读取到的寄存器值数组</returns>
+        public static async Task<ushort[]> 读保持寄存器(
             string ipAddress,
             int port,
             byte slaveAddress,
@@ -51,7 +72,18 @@ namespace DeviceCommand.Flexible
             }
         }
 
-        public static async Task WriteSingleRegisterAsync(
+        /// <summary>
+        /// 写入单个保持寄存器（功能码 06）。
+        /// </summary>
+        /// <param name="ipAddress">设备 IP 地址</param>
+        /// <param name="port">Modbus TCP 端口号，默认常用 502</param>
+        /// <param name="slaveAddress">Modbus 从站站号（单元标识符）</param>
+        /// <param name="registerAddress">要写入的寄存器地址</param>
+        /// <param name="value">要写入的寄存器值 (0-65535)</param>
+        /// <param name="sendTimeout">发送/连接超时时间（毫秒），默认 3000</param>
+        /// <param name="receiveTimeout">接收超时时间（毫秒），默认 3000</param>
+        /// <param name="ct">异步取消令牌</param>
+        public static async Task 写单个寄存器(
             string ipAddress,
             int port,
             byte slaveAddress,
@@ -79,7 +111,19 @@ namespace DeviceCommand.Flexible
 
         #region Coils
 
-        public static async Task<bool[]> ReadCoilsAsync(
+        /// <summary>
+        /// 读取线圈状态（功能码 01），返回指定数量的线圈开关状态数组。
+        /// </summary>
+        /// <param name="ipAddress">设备 IP 地址</param>
+        /// <param name="port">Modbus TCP 端口号，默认常用 502</param>
+        /// <param name="slaveAddress">Modbus 从站站号（单元标识符）</param>
+        /// <param name="startAddress">起始线圈地址</param>
+        /// <param name="numberOfPoints">读取的线圈数量</param>
+        /// <param name="sendTimeout">发送/连接超时时间（毫秒），默认 3000</param>
+        /// <param name="receiveTimeout">接收超时时间（毫秒），默认 3000</param>
+        /// <param name="ct">异步取消令牌</param>
+        /// <returns>线圈状态数组，true 表示吸合/导通</returns>
+        public static async Task<bool[]> 读线圈(
             string ipAddress,
             int port,
             byte slaveAddress,
@@ -104,7 +148,18 @@ namespace DeviceCommand.Flexible
             }
         }
 
-        public static async Task WriteSingleCoilAsync(
+        /// <summary>
+        /// 写入单个线圈（功能码 05），控制单个开关量输出。
+        /// </summary>
+        /// <param name="ipAddress">设备 IP 地址</param>
+        /// <param name="port">Modbus TCP 端口号，默认常用 502</param>
+        /// <param name="slaveAddress">Modbus 从站站号（单元标识符）</param>
+        /// <param name="coilAddress">要写入的线圈地址</param>
+        /// <param name="value">线圈状态（true: 吸合/导通, false: 断开）</param>
+        /// <param name="sendTimeout">发送/连接超时时间（毫秒），默认 3000</param>
+        /// <param name="receiveTimeout">接收超时时间（毫秒），默认 3000</param>
+        /// <param name="ct">异步取消令牌</param>
+        public static async Task 写单个线圈(
             string ipAddress,
             int port,
             byte slaveAddress,