ADP/DeviceCommand/Flexible/FTCP.cs

using Common.Attributes;
using System.Net.Sockets;
using System.Text;

namespace DeviceCommand.Flexible
{
    /// <summary>
    /// 灵活型 TCP 通信类（免实例化，每次调用临时建立 TCP 连接）。
    /// 支持字节/文本发送、定长字节读取、按结束符读取文本行四种操作，
    /// 内部使用通信锁保证同一时刻只有一个 TCP 事务在执行，
    /// 适用于偶发性、无需保持长连接的 TCP 设备通信场景。
    /// </summary>
    [ADPCommand]
    public static class FTCP
    {
        // 通信锁：保证同一时刻只有一个 TCP 事务在执行
        private static readonly SemaphoreSlim _commLock = new(1, 1);

        #region Send

        /// <summary>
        /// 向指定 TCP 端点发送一段字节数据（发送完成后立即断开）。
        /// </summary>
        /// <param name="ipAddress">设备 IP 地址</param>
        /// <param name="port">TCP 端口号</param>
        /// <param name="sendTimeout">发送超时时间（毫秒）</param>
        /// <param name="buffer">要发送的字节数组</param>
        /// <param name="ct">异步取消令牌</param>
        public static async Task 发送字节数据(string ipAddress,int port,int sendTimeout, byte[] buffer, CancellationToken ct = default)
        {
            await _commLock.WaitAsync(ct);
            try
            {
                using var client = new TcpClient();
                client.SendTimeout = sendTimeout;

                await client.ConnectAsync(ipAddress, port, ct);

                using NetworkStream stream = client.GetStream();
                await stream.WriteAsync(buffer, 0, buffer.Length, ct).WaitAsync(TimeSpan.FromMilliseconds(sendTimeout));
            }
            finally
            {
                _commLock.Release();
            }
        }

        /// <summary>
        /// 向指定 TCP 端点发送一段文本（以 UTF8 编码为字节后发送，发送完成后立即断开）。
        /// </summary>
        /// <param name="ipAddress">设备 IP 地址</param>
        /// <param name="port">TCP 端口号</param>
        /// <param name="sendTimeout">发送超时时间（毫秒）</param>
        /// <param name="text">要发送的文本字符串</param>
        /// <param name="ct">异步取消令牌</param>
        public static Task 发送文本数据(string ipAddress, int port,int sendTimeout, string text,CancellationToken ct = default)
        {
            return 发送字节数据( ipAddress, port, sendTimeout, Encoding.UTF8.GetBytes(text),ct);
        }

        #endregion

        #region Read

        /// <summary>
        /// 连接指定 TCP 端点并读取指定长度的字节数据（连接关闭或读满为止）。
        /// </summary>
        /// <param name="ipAddress">设备 IP 地址</param>
        /// <param name="port">TCP 端口号</param>
        /// <param name="receiveTimeout">接收超时时间（毫秒）</param>
        /// <param name="length">要读取的字节长度</param>
        /// <param name="ct">异步取消令牌</param>
        /// <returns>实际读取到的字节数组（对端提前关闭时可能短于请求长度）</returns>
        public static async Task<byte[]> 读取字节数据(string ipAddress,int port,int receiveTimeout,int length,CancellationToken ct = default)
        {
            await _commLock.WaitAsync(ct);
            try
            {
                using var client = new TcpClient();
                client.ReceiveTimeout = receiveTimeout;

                await client.ConnectAsync(ipAddress, port, ct);

                using NetworkStream stream = client.GetStream();
                byte[] buffer = new byte[length];
                int offset = 0;

                using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
                if (receiveTimeout > 0)
                    cts.CancelAfter(receiveTimeout);

                while (offset < length)
                {
                    int read = await stream.ReadAsync(buffer, offset, length - offset, cts.Token);
                    if (read == 0) break;
                    offset += read;
                }

                return buffer[..offset];
            }
            finally
            {
                _commLock.Release();
            }
        }

        /// <summary>
        /// 连接指定 TCP 端点并读取一行文本，读取到结束符为止（返回内容不含结束符）。
        /// </summary>
        /// <param name="ipAddress">设备 IP 地址</param>
        /// <param name="port">TCP 端口号</param>
        /// <param name="receiveTimeout">接收超时时间（毫秒），超时未收到结束符抛出超时异常</param>
        /// <param name="delimiter">文本行结束符，默认换行符 "\n"</param>
        /// <param name="ct">异步取消令牌</param>
        /// <returns>去除结束符并去除首尾空白后的文本行</returns>
        public static async Task<string> 读取文本行( string ipAddress,   int port,   int receiveTimeout,  string delimiter = "\n",CancellationToken ct = default)
        {
            await _commLock.WaitAsync(ct);
            try
            {
                using var client = new TcpClient();
                client.ReceiveTimeout = receiveTimeout;

                await client.ConnectAsync(ipAddress, port, ct);

                using NetworkStream stream = client.GetStream();
                var sb = new StringBuilder();
                byte[] buffer = new byte[1024];

                using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
                if (receiveTimeout > 0)
                    cts.CancelAfter(receiveTimeout);

                while (!cts.Token.IsCancellationRequested)
                {
                    int bytesRead = await stream.ReadAsync(buffer, 0, buffer.Length, cts.Token);
                    if (bytesRead == 0) break;

                    sb.Append(Encoding.UTF8.GetString(buffer, 0, bytesRead));

                    int index = sb.ToString().IndexOf(delimiter, StringComparison.Ordinal);
                    if (index >= 0)
                        return sb.ToString(0, index).Trim();
                }

                throw new TimeoutException("读取超时或对端关闭");
            }
            finally
            {
                _commLock.Release();
            }
        }

        #endregion
    }
}