doc(ITcpSocketClient): update AddDataPackageAdapter documentation (#6686)

* doc: 增加配置示例文档

* doc: 增加本地化资源文件

* doc: 更新示例

* doc: 更新数据适配器文档

* chore: 更新依赖包

* doc: 更新文档

Author: ArgoZhang

src/BootstrapBlazor.Server/BootstrapBlazor.Server.csproj

@@ -68,13 +68,14 @@
     <PackageReference Include="BootstrapBlazor.RDKit" Version="9.0.2" />
     <PackageReference Include="BootstrapBlazor.SignaturePad" Version="9.0.1" />
     <PackageReference Include="BootstrapBlazor.SmilesDrawer" Version="9.0.2" />
+    <PackageReference Include="BootstrapBlazor.Socket" Version="9.0.4" />
     <PackageReference Include="BootstrapBlazor.Sortable" Version="9.0.3" />
     <PackageReference Include="BootstrapBlazor.Splitting" Version="9.0.3" />
     <PackageReference Include="BootstrapBlazor.SvgEditor" Version="9.0.3" />
     <PackageReference Include="BootstrapBlazor.SummerNote" Version="9.0.7" />
     <PackageReference Include="BootstrapBlazor.TableExport" Version="9.2.6" />
     <PackageReference Include="BootstrapBlazor.Tasks.Dashboard" Version="9.0.0" />
-    <PackageReference Include="BootstrapBlazor.TcpSocket" Version="9.0.1" />
+    <PackageReference Include="BootstrapBlazor.TcpSocket" Version="9.0.4" />
     <PackageReference Include="BootstrapBlazor.Topology" Version="9.0.1" />
     <PackageReference Include="BootstrapBlazor.UniverIcon" Version="9.0.1" />
     <PackageReference Include="BootstrapBlazor.UniverSheet" Version="9.0.5" />

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

@@ -61,7 +61,9 @@ private async Task CreateClient()
     {
         DataPackageHandler = new FixLengthDataPackageHandler(4)
     };
-    client.SetDataPackageAdapter(adapter, buffer =>
+
+    // 如果 client 不销毁切记使用 RemoveDataPackageAdapter 移除回调委托防止内存泄露
+    client.AddDataPackageAdapter(adapter, buffer =>
     {
         // buffer 即是接收到的数据
         return ValueTask.CompletedTask;

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

@@ -51,8 +51,9 @@ _dataAdapter.ReceivedCallBack = async Data =>
 {
     // 此处接收到的数据 Data 为完整响应数据
 };</Pre>
-<Pre>// 实战中可以使用 ITcpSocketClient 扩展方法 SetDataPackageAdapter 简化代码
-_client.SetDataPackageAdapter(_dataAdapter, UpdateReceiveLog);</Pre>
+    <Pre>// 实战中可以使用 ITcpSocketClient 扩展方法 AddDataPackageAdapter 简化代码
+// 如果 _client 实例在当前页面不销毁时，切记使用 AddDataPackageAdapter 移除当前页面加载的 UpdateReceiveLog 回调方法避免内存泄露
+_client.AddDataPackageAdapter(_dataAdapter, UpdateReceiveLog);</Pre>
 
     <p>本例中使用的模拟服务端代码如下：</p>
 

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

@@ -49,7 +49,7 @@ protected override void OnInitialized()
         _dataAdapter.ReceivedCallBack = UpdateReceiveLog;
 
         // 实战中可以通过下面一句话设置数据适配器与回调方法
-        // _client.SetDataPackageAdapter(_dataAdapter, UpdateReceiveLog);
+        // _client.AddDataPackageAdapter(_dataAdapter, UpdateReceiveLog);
 
     }
 

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

@@ -63,7 +63,7 @@ class MockEntity
         <li><code>DataUInt64LittleEndianConverter</code> 转成 ulong 无符号整形小端读取</li>
     </ul>
     <p>自定义数据类型转化器示例</p>
-    <Pre>[SocketTypeDataConverter(Type = typeof(DataConverter&lt;MockEntity&gt;))]
+    <Pre>[DataTypeConverter(Type = typeof(DataConverter&lt;MockEntity&gt;))]
 class MockEntity
 {
     [DataPropertyConverter(Type = typeof(byte[]), Offset = 0, Length = 5)]
@@ -84,3 +84,44 @@ class MockEntity
 }</Pre>
     <p>更多技术细节可以参考以上内置提供的转换器源码</p>
 </DemoBlock>
+
+<DemoBlock Title="@Localizer["ConfigTitle"]"
+           Introduction="@Localizer["ConfigIntro"]"
+           Name="Config" ShowCode="false">
+    <p>通过 <code>ConfigureDataConverters</code> 可以配置任意类型（第三方程序集中无源码类型）自定数据转换</p>
+    <Pre>class MockEntity
+{
+    public byte[]? Header { get; set; }
+
+    public byte[]? Body { get; set; }
+}</Pre>
+    <Pre>service.ConfigureDataConverters(options =>
+{
+    // 配置 MockEntity 转换
+    options.AddTypeConverter&lt;MockEntity&gt;();
+
+    // 配置 MockEntity 属性 Header 转换逻辑 从起始位置 0 开始读取 5 个字节
+    options.AddPropertyConverter&lt;MockEntity&gt;(entity => entity.Header, new DataPropertyConverterAttribute()
+    {
+        Offset = 0,
+        Length = 5
+    });
+
+    // 配置 MockEntity 属性 Body 转换逻辑 从起始位置 5 开始读取 2 个字节
+    options.AddPropertyConverter&lt;MockEntity&gt;(entity => entity.Body, new DataPropertyConverterAttribute()
+    {
+        Offset = 5,
+        Length = 2
+    });
+});</Pre>
+    <p>通过调用 <code>ITcpSocketClient</code> 实例泛型扩展方法 <code>AddDataPackageAdapter</code> 在回调方法 <code>OnReceiveAsync</code> 中直接拿到数据实体类</p>
+    <Pre>// 创建一个数据适配器
+var adapter = new DataPackageAdapter(new FixLengthDataPackageHandler(7));
+
+// 设置数据适配器与回调方法
+_client.AddDataPackageAdapter&lt;MockEntity&gt;(adapter, OnReceiveAsync);</Pre>
+    <Pre>private async Task OnReceiveAsync(MockEntity? entity)
+{
+    return Task.CompletedTask;
+}</Pre>
+</DemoBlock>

src/BootstrapBlazor.Server/Locales/en-US.json

@@ -7163,7 +7163,9 @@
     "DataEntityTitle": "Socket Auto Entity",
     "DataEntityDescription": "After receiving the communication data, it is automatically converted into the entity class required by the business",
     "NormalTitle": "Basic usage",
-    "NormalIntro": "Enable automatic data conversion through the <code>DataTypeConverterAttribute</code> attribute"
+    "NormalIntro": "Enable automatic data conversion through the <code>DataTypeConverterAttribute</code> attribute",
+    "ConfigTitle": "DataType Converter",
+    "ConfigIntro": "Use the <code>ConfigureDataConverters</code> method to map the entity class and automatically convert the received data"
   },
   "BootstrapBlazor.Server.Components.Samples.NetworkMonitors": {
     "NetworkMonitorTitle": "NetworkMonitor",

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

@@ -7165,7 +7165,9 @@
     "DataEntityTitle": "Socket 数据转化实体类",
     "DataEntityDescription": "接收到通讯数据后自动转成业务需要的实体类",
     "NormalTitle": "基本用法",
-    "NormalIntro": "通过 <code>DataTypeConverterAttribute</code> 标签开启数据自动转换功能"
+    "NormalIntro": "通过 <code>DataTypeConverterAttribute</code> 标签开启数据自动转换功能",
+    "ConfigTitle": "数据实体类映射配置",
+    "ConfigIntro": "使用 <code>ConfigureDataConverters</code> 方法对实体类进行映射配置将接收到的数据自动转化"
   },
   "BootstrapBlazor.Server.Components.Samples.NetworkMonitors": {
     "NetworkMonitorTitle": "NetworkMonitor 网络状态",