From 8e42d0c1b7ae36cff2e7c69999117911a4b6f300 Mon Sep 17 00:00:00 2001
From: wanshenmean <cathay_xy@163.com>
Date: 星期四, 26 三月 2026 17:31:06 +0800
Subject: [PATCH] feat(WCS): 完善 WIDESEAWCS_Tasks 模块代码注释
---
Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/SocketServer/TcpSocketServer.cs | 146 +++++++++++++++++++++++++++++++++++++-----------
1 files changed, 111 insertions(+), 35 deletions(-)
diff --git a/Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/SocketServer/TcpSocketServer.cs b/Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/SocketServer/TcpSocketServer.cs
index 4d8789b..e08d58f 100644
--- a/Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/SocketServer/TcpSocketServer.cs
+++ b/Code/WCS/WIDESEAWCS_Server/WIDESEAWCS_Tasks/SocketServer/TcpSocketServer.cs
@@ -11,115 +11,191 @@
namespace WIDESEAWCS_Tasks.SocketServer
{
/// <summary>
- /// TCP Socket服务端（基于行协议，按换行符分割消息）
+ /// TCP Socket 鏈嶅姟鍣� - 鏍稿績绫�
/// </summary>
+ /// <remarks>
+ /// 鏍稿績鑱岃矗锛�
+ /// 1. 鎺ュ彈瀹㈡埛绔� TCP 杩炴帴
+ /// 2. 绠＄悊瀹㈡埛绔繛鎺ョ姸鎬�
+ /// 3. 鎺ユ敹鍜屽彂閫佹秷鎭�
+ /// 4. 澶勭悊璁惧娉ㄥ唽
+ /// 5. 娑堟伅甯цВ鏋愶紙鏀寔澶村熬鏍囪瘑锛�
+ ///
+ /// 鏈嶅姟鍣ㄤ娇鐢ㄤ互涓嬫暟鎹粨鏋勭鐞嗗鎴风锛�
+ /// - _clients: 瀹㈡埛绔� ID 鍒� TcpClient 鐨勬槧灏�
+ /// - _clientLocks: 瀹㈡埛绔� ID 鍒颁俊鍙烽噺鐨勬槧灏勶紙淇濊瘉姣忎釜瀹㈡埛绔殑鍙戦�佷簰鏂ワ級
+ /// - _deviceBindings: 璁惧 ID 鍒板鎴风 ID 鐨勬槧灏�
+ /// - _clientEncodings: 瀹㈡埛绔� ID 鍒扮紪鐮佺殑鏄犲皠锛堟敮鎸佽嚜鍔ㄧ紪鐮佹娴嬶級
+ /// - _clientLastActive: 瀹㈡埛绔� ID 鍒版渶鍚庢椿璺冩椂闂寸殑鏄犲皠
+ /// </remarks>
public partial class TcpSocketServer : IDisposable
{
+ /// <summary>
+ /// 鏈嶅姟鍣ㄩ厤缃�夐」
+ /// </summary>
private readonly SocketServerOptions _options;
/// <summary>
- /// 提供一个可用于同步对包含实例的访问的对象。
+ /// 鍚屾鏍瑰璞★紝鐢ㄤ簬绾跨▼鍚屾
/// </summary>
- /// <remarks>在对实例实现线程安全操作时，可将此对象用作锁定目标。此模式通常用于避免死锁并确保一致的同步。</remarks>
- public readonly object _syncRoot = new();
+ /// <remarks>
+ /// 鍦ㄥ绾跨▼璁块棶鍏变韩鏁版嵁缁撴瀯鏃朵娇鐢ㄦ瀵硅薄杩涜鍚屾銆�
+ /// 閲囩敤淇濆畧绛栫暐锛岀‘淇濈嚎绋嬪畨鍏ㄣ��
+ /// </remarks>
+ public readonly object _syncRoot = new object();
+ /// <summary>
+ /// TCP 鐩戝惉鍣�
+ /// </summary>
private TcpListener? _listener;
/// <summary>
- /// 表示用于发出进行中操作的取消请求的取消令牌源。
+ /// 鍙栨秷浠ょ墝婧�
/// </summary>
- /// <remarks>如果当前没有活动的取消机制，此字段可能为null。使用此令牌源取消支持取消的任务或操作。</remarks>
+ /// <remarks>
+ /// 鐢ㄤ簬璇锋眰鍋滄鏈嶅姟鍣ㄧ殑杩愯銆�
+ /// </remarks>
public CancellationTokenSource? _cts;
/// <summary>
- /// 提供表示活动客户端操作的任务列表。
+ /// 瀹㈡埛绔换鍔″垪琛�
/// </summary>
- /// <remarks>此字段用于内部跟踪异步客户端活动。它是只读的，不应在包含类外部直接修改。</remarks>
+ /// <remarks>
+ /// 璁板綍鎵�鏈夋椿璺冨鎴风鐨勫鐞嗕换鍔°��
+ /// </remarks>
public readonly List<Task> _clientTasks = new();
/// <summary>
- /// 提供从客户端标识符到其关联的TCP客户端连接的映射。
+ /// 瀹㈡埛绔繛鎺ュ瓧鍏�
/// </summary>
- /// <remarks>此字典允许通过唯一字符串标识符访问活动的TCP客户端。在多线程场景中，对集合的修改应小心进行以避免并发问题。</remarks>
+ /// <remarks>
+ /// Key: 瀹㈡埛绔� ID锛堥�氬父鏄� IP:Port锛�
+ /// Value: TcpClient 杩炴帴瀵硅薄
+ /// </remarks>
public readonly Dictionary<string, TcpClient> _clients = new();
/// <summary>
- /// 提供从设备标识符到其对应绑定值的映射。
+ /// 璁惧缁戝畾瀛楀吀
/// </summary>
- /// <remarks>此字段是只读的，用于包含类内部使用。应通过指定的方法或属性对字典进行修改以确保一致性。</remarks>
+ /// <remarks>
+ /// Key: 璁惧 ID
+ /// Value: 瀹㈡埛绔� ID
+ /// 鐢ㄤ簬閫氳繃璁惧 ID 鎵惧埌瀵瑰簲鐨勫鎴风杩炴帴銆�
+ /// </remarks>
public readonly Dictionary<string, string> _deviceBindings = new();
/// <summary>
- /// 提供从客户端标识符到其关联锁的映射，用于同步对客户端特定资源的访问。
+ /// 瀹㈡埛绔攣瀛楀吀
/// </summary>
- /// <remarks>字典中的每个条目将一个唯一的客户端ID与一个<see cref="SemaphoreSlim"/>实例关联，实现每个客户端的线程安全操作。此集合用于内部协调并发访问，不应直接修改。</remarks>
+ /// <remarks>
+ /// 姣忎釜瀹㈡埛绔竴涓� SemaphoreSlim锛岀‘淇濆悓涓�瀹㈡埛绔殑鍙戦�佹搷浣滀簰鏂ャ��
+ /// </remarks>
public readonly Dictionary<string, SemaphoreSlim> _clientLocks = new();
/// <summary>
- /// 提供从客户端标识符到其关联文本编码的映射。
+ /// 瀹㈡埛绔紪鐮佸瓧鍏�
/// </summary>
- /// <remarks>此字典用于内部跟踪已连接客户端的编码偏好。键表示客户端标识符，值指定用于文本操作的对应<see cref="System.Text.Encoding"/>。</remarks>
+ /// <remarks>
+ /// 璁板綍姣忎釜瀹㈡埛绔娇鐢ㄧ殑瀛楃缂栫爜銆�
+ /// 鏀寔鑷姩妫�娴嬶細UTF-8 鎴� GBK銆�
+ /// </remarks>
public readonly Dictionary<string, Encoding> _clientEncodings = new();
/// <summary>
- /// 存储每个客户端最后活动的时间戳，以客户端标识符为键。
+ /// 瀹㈡埛绔渶鍚庢椿璺冩椂闂村瓧鍏�
/// </summary>
- /// <remarks>此字段用于内部跟踪客户端活动。字典将客户端标识符映射到对应的最后活动时间（UTC）。直接修改此集合可能影响客户端会话管理逻辑。</remarks>
+ /// <remarks>
+ /// 璁板綍姣忎釜瀹㈡埛绔渶鍚庝竴娆℃椿鍔ㄧ殑鏃堕棿銆�
+ /// 鐢ㄤ簬绌洪棽瓒呮椂妫�娴嬨��
+ /// </remarks>
public readonly Dictionary<string, DateTime> _clientLastActive = new();
/// <summary>
- /// 指定包含类型中字符数据使用的文本编码。
+ /// 榛樿鏂囨湰缂栫爜
/// </summary>
- /// <remarks>使用此字段确定处理字符数据时如何编码或解码文本。编码影响字节如何被解释为字符，反之亦然。常见的编码包括UTF8、ASCII和Unicode。</remarks>
public readonly Encoding _textEncoding;
/// <summary>
- /// 表示自动检测到的GB2312编码（如果可用）。
+ /// 鑷姩妫�娴嬬殑 GBK 缂栫爜
/// </summary>
- /// <remarks>通常从输入数据确定编码时设置此字段。如果检测失败或未执行检测，值可能为null。</remarks>
public readonly Encoding? _autoDetectedGb2312;
+ /// <summary>
+ /// 鏃ュ織鏂囦欢璺緞
+ /// </summary>
private readonly string _logFile;
+ /// <summary>
+ /// 瀹㈡埛绔洃鎺т换鍔�
+ /// </summary>
private Task? _monitorTask;
/// <summary>
- /// 使用指定的服务器选项初始化 TcpSocketServer 类的新实例。
+ /// 鏈嶅姟鍣ㄦ槸鍚︽鍦ㄨ繍琛�
/// </summary>
- /// <remarks>如果启用了 AutoDetectEncoding 选项，服务器将默认使用 UTF-8 编码，
- /// 并尝试支持 GBK 编码进行自动检测。如果编码检测失败或提供了无效的编码名称，
- /// 将回退使用 UTF-8 编码。日志文件路径由 LogFilePath 选项决定，
- /// 如果未指定，则默认为应用程序基目录下的 'socketserver.log' 文件。</remarks>
- /// <param name="options">套接字服务器的配置选项。不能为 null。提供编码设置、日志文件路径和自动检测行为等配置。</param>
+ public bool IsRunning { get; private set; }
+
+ /// <summary>
+ /// 娑堟伅鎺ユ敹浜嬩欢
+ /// </summary>
+ /// <remarks>
+ /// 褰撴湇鍔″櫒鎺ユ敹鍒版秷鎭椂瑙﹀彂銆�
+ /// 鍙傛暟锛氭秷鎭唴瀹广�佹槸鍚� JSON 鏍煎紡銆乀CP 瀹㈡埛绔�佹満鍣ㄤ汉鐘舵��
+ /// </remarks>
+ public event Func<string, bool, TcpClient, RobotSocketState, Task<string?>>? MessageReceived;
+
+ /// <summary>
+ /// 鏈哄櫒浜鸿繛鎺ユ柇寮�浜嬩欢
+ /// </summary>
+ /// <remarks>
+ /// 褰撴満鍣ㄤ汉瀹㈡埛绔柇寮�杩炴帴鏃惰Е鍙戙��
+ /// 鍙傛暟锛氬鎴风 ID
+ /// </remarks>
+ public event Func<string, Task<string?>>? RobotReceived;
+
+ /// <summary>
+ /// 鏋勯�犲嚱鏁�
+ /// </summary>
+ /// <remarks>
+ /// 浣跨敤鎸囧畾鐨勯厤缃�夐」鍒濆鍖� TcpSocketServer 瀹炰緥銆�
+ /// 閰嶇疆椤瑰寘鎷細绔彛銆佸瓧绗︾紪鐮併�佽嚜鍔ㄧ紪鐮佹娴嬨�佹棩蹇楁枃浠惰矾寰勭瓑銆�
+ /// </remarks>
+ /// <param name="options">Socket 鏈嶅姟鍣ㄩ厤缃�夐」</param>
public TcpSocketServer(IOptions<SocketServerOptions> options)
{
_options = options.Value;
+
+ // 閰嶇疆瀛楃缂栫爜
if (_options.AutoDetectEncoding)
{
+ // 鑷姩妫�娴嬬紪鐮佹ā寮忥細榛樿 UTF-8锛屼篃鏀寔 GBK
_textEncoding = Encoding.UTF8;
try { _autoDetectedGb2312 = Encoding.GetEncoding("GBK"); } catch { _autoDetectedGb2312 = null; }
}
else
{
+ // 鎸囧畾缂栫爜妯″紡
try { _textEncoding = Encoding.GetEncoding(_options.EncodingName ?? "utf-8"); }
catch { _textEncoding = Encoding.UTF8; }
_autoDetectedGb2312 = null;
}
+ // 閰嶇疆鏃ュ織鏂囦欢璺緞
_logFile = Path.Combine(AppContext.BaseDirectory ?? ".", _options.LogFilePath ?? "socketserver.log");
Log($"[{DateTime.Now}] TcpSocketServer starting");
}
- public bool IsRunning { get; private set; }
-
- public event Func<string, bool, TcpClient, RobotSocketState, Task<string?>>? MessageReceived;
-
- public event Func<string, Task<string?>>? RobotReceived;
-
+ /// <summary>
+ /// 璁板綍鏃ュ織
+ /// </summary>
+ /// <remarks>
+ /// 灏嗘秷鎭緭鍑哄埌鎺у埗鍙板苟鍐欏叆鏃ュ織鏂囦欢銆�
+ /// </remarks>
+ /// <param name="message">鏃ュ織娑堟伅</param>
private void Log(string message)
{
Console.WriteLine(message);
try { File.AppendAllText(_logFile, message + Environment.NewLine); } catch { }
}
}
-}
\ No newline at end of file
+}
--
Gitblit v1.9.3