doc: 更新相关文档说明

Author: ArgoZhang

src/BootstrapBlazor.Server/Components/Samples/SocketFactories.razor

@@ -54,16 +54,15 @@ private async Task CreateClient()
     // 创建 ITcpSocketClient 实例
     var client = TcpSocketFactory.GetOrCreate("localhost", 0);
 
-    // 设置 FixLengthDataPackageHandler 数据处理器处理数据定长 4 的数据
-    client.SetDataHandler(new FixLengthDataPackageHandler(4)
+    // 设置数据适配器 使用 FixLengthDataPackageHandler 数据处理器处理数据定长 4 的数据
+    var adapter = new DataPackageAdapter
     {
-        // 设置接收数据回调方法
-        ReceivedCallBack = buffer =>
-        {
-            // 内部自动处理粘包分包问题，这里参数 buffer 一定是定长为 4 的业务数据
-            receivedBuffer = buffer;
-            return Task.CompletedTask;
-        }
+        DataPackageHandler = new FixLengthDataPackageHandler(4)
+    };
+    client.SetDataPackageAdapter(adapter, buffer =>
+    {
+        // buffer 即是接收到的数据
+        return ValueTask.CompletedTask;
     });
 
     // 连接远端节点 连接成功后自动开始接收数据
@@ -78,8 +77,36 @@ private async Task CreateClient()
     <li><code>DelimiterDataPackageHandler</code> <b>分隔符数据处理器</b> 即通讯包以特定一个或一组字节分割</li>
 </ul>
 
-<p class="code-label">5. 数据适配器（设计中）</p>
+<p class="code-label">5. 数据适配器</p>
 
 <p>在我们实际应用中，接收到数据包后（已经过数据处理器）大多情况下是需要将电文转化为应用中的具体数据类型 <code>Class</code> 或 <code>Struct</code>。将原始数据包转化为类或者结构体的过程由我们的数据适配器来实现</p>
 
 <p>数据适配器设计思路如下</p>
+
+<ol class="ul-demo">
+    <li>使用 <code>SocketDataConverterAttribute</code> 标签约定通讯数据使用那个转换类型进行转换 指定类型需继承 <code>ISocketDataConverter</code>
+        接口
+    </li>
+    <li>使用 <code>SocketDataPropertyAttribute</code> 标签约定如何转换数据类型 （Property） 属性值</li>
+</ol>
+
+<Pre>[SocketDataConverter(Type = typeof(SocketDataConverter&lt;MockEntity&gt;))]
+class MockEntity
+{
+    [SocketDataProperty(Type = typeof(byte[]), Offset = 0, Length = 5)]
+    public byte[]? Header { get; set; }
+
+    [SocketDataProperty(Type = typeof(byte[]), Offset = 5, Length = 2)]
+    public byte[]? Body { get; set; }
+
+    [SocketDataProperty(Type = typeof(Foo), Offset = 7, Length = 1, ConverterType = typeof(FooConverter), ConverterParameters = ["test"])]
+    public string? Value1 { get; set; }
+}</Pre>
+
+<Pre>class FooConverter(string name) : ISocketDataPropertyConverter
+{
+    public object? Convert(ReadOnlyMemory&lt;byte&gt; data)
+    {
+        return new Foo() { Id = data.Span[0], Name = name };
+    }
+}</Pre>

src/BootstrapBlazor.Server/Components/Samples/Sockets/Adapters.razor

@@ -41,8 +41,8 @@
     </ul>
     <p>本示例服务器端模拟了数据分包即响应数据实际是两次写入所以实际接收端是要通过两次接收才能得到一个完整的响应数据包，可通过 <b>数据适配器</b> 来简化接收逻辑。通过切换下方 <b>是否使用数据适配器</b> 控制开关进行测试查看实际数据接收情况。</p>
     <ul class="ul-demo">
-        <li>不使用 <b>数据处理器</b> 要分两次接收才能接收完整</li>
-        <li>使用 <b>数据处理器</b> 一次即可接收完整数据包</li>
+        <li>不使用 <b>数据适配器</b> 要分两次接收才能接收完整</li>
+        <li>使用 <b>数据适配器</b> 一次即可接收完整数据包</li>
     </ul>
     <Pre>private readonly DataPackageAdapter _dataAdapter = new()
 {

src/BootstrapBlazor.Server/Components/Samples/Sockets/Adapters.razor.cs

@@ -48,10 +48,10 @@ protected override void OnInitialized()
         });
         _client.ReceivedCallBack += OnReceivedAsync;
 
-        _dataAdapter.ReceivedCallBack += async Data =>
+        _dataAdapter.ReceivedCallBack += async data =>
         {
             // 直接处理接收的数据
-            await UpdateReceiveLog(Data);
+            await UpdateReceiveLog(data);
         };
     }
 
@@ -104,7 +104,7 @@ private async ValueTask OnReceivedAsync(ReadOnlyMemory<byte> data)
 
     private async Task UpdateReceiveLog(ReadOnlyMemory<byte> data)
     {
-        var payload = System.Text.Encoding.UTF8.GetString(data.Span);
+        var payload = Encoding.UTF8.GetString(data.Span);
         var body = BitConverter.ToString(data.ToArray());
 
         _items.Add(new ConsoleMessageItem

src/BootstrapBlazor.Server/Components/Samples/Sockets/DataEntities.razor

@@ -9,7 +9,7 @@
            Name="Normal" ShowCode="false">
     <p>通过 <code>SocketDataConverterAttribute</code> 类标签与 <code>SocketDataPropertyAttribute</code>
         属性标签可以将通讯数据自动转化为我们系统中需要的业务实体类，示例如下：</p>
-    <Pre>[SocketDataConverter(Type = typeof(MockEntitySocketDataConverter))]
+    <Pre>[SocketDataConverter(Type = typeof(SocketDataConverter&lt;MockEntity&gt;))]
 class MockEntity
 {
     [SocketDataProperty(Type = typeof(byte[]), Offset = 0, Length = 5)]
@@ -26,8 +26,7 @@ class MockEntity
 }</Pre>
     <p class="code-label">1. <code>SocketDataConverter</code> 参数说明：</p>
     <ul class="ul-demo">
-        <li><b>Type</b>: 自定义转换器类型，组件库内置了 <code>SocketDataConverterBase</code> 泛型基类，继承后非常方便扩展出自己的转换器，重载
-            <code>TryConvertTo</code> 方法调用基类的 <code>Parse</code> 基本就完成了 99% 的工作量，也可以完全自己解析通讯电文到实体类的各个属性上
+        <li><b>Type</b>: 自定义转换器类型，组件库内置了 <code>SocketDataConverter</code> 泛型类，建议看一下源码非常方便扩展出自己的转换器
         </li>
     </ul>
     <Pre>class MockEntitySocketDataConverter : SocketDataConverterBase&lt;MockEntity&gt;
@@ -96,7 +95,7 @@ class MockEntity
         <li><code>SocketDataUInt64LittleEndianConverter</code> 转成 ulong 无符号整形小端读取</li>
     </ul>
     <p>自定义数据类型转化器示例</p>
-    <Pre>[SocketDataConverter(Type = typeof(MockEntitySocketDataConverter))]
+    <Pre>[SocketDataConverter(Type = typeof(SocketDataConverter&lt;MockEntity&gt;))]
 class MockEntity
 {
     [SocketDataProperty(Type = typeof(byte[]), Offset = 0, Length = 5)]
@@ -107,9 +106,8 @@ class MockEntity
 
     [SocketDataProperty(Type = typeof(Foo), Offset = 7, Length = 1, ConverterType = typeof(FooConverter), ConverterParameters = ["test"])]
     public string? Value1 { get; set; }
-}
-
-class FooConverter(string name) : ISocketDataPropertyConverter
+}</Pre>
+    <Pre>class FooConverter(string name) : ISocketDataPropertyConverter
 {
     public object? Convert(ReadOnlyMemory&lt;byte&gt; data)
     {

src/BootstrapBlazor.Server/Locales/zh-CN.json

@@ -4839,7 +4839,7 @@
     "SocketComponents": "Socket 服务",
     "SocketAutoReceive": "自动接收数据",
     "SocketManualReceive": "手动接收数据",
-    "DataPackageAdapter": "数据处理器",
+    "DataPackageAdapter": "数据适配器",
     "SocketAutoConnect": "自动重连",
     "SocketDataEntity": "通讯数据转实体类",
     "NetworkMonitor": "网络状态 NetworkMonitor"