feat: 增加 SetDataPackageAdapter 方法

Author: ArgoZhang

src/BootstrapBlazor/Extensions/ITcpSocketClientExtensions.cs

@@ -74,4 +74,42 @@ public static void SetDataPackageAdapter(this ITcpSocketClient client, IDataPack
         // 设置 DataPackageAdapter 的回调函数
         adapter.ReceivedCallBack = buffer => callback(buffer);
     }
+
+    /// <summary>
+    /// Configures the specified <see cref="ITcpSocketClient"/> to use a custom data package adapter and a callback
+    /// function for processing received data.
+    /// </summary>
+    /// <remarks>This method sets up the <paramref name="client"/> to use the provided <paramref
+    /// name="adapter"/> for handling incoming data. The adapter processes the raw data received by the client and
+    /// attempts to convert it into an instance of <typeparamref name="TEntity"/>. If the conversion is successful, the
+    /// <paramref name="callback"/> is invoked with the converted entity; otherwise, it is invoked with <see
+    /// langword="null"/>.</remarks>
+    /// <typeparam name="TEntity">The type of the entity that the data package adapter will attempt to convert the received data into.</typeparam>
+    /// <param name="client">The <see cref="ITcpSocketClient"/> instance to configure.</param>
+    /// <param name="adapter">The <see cref="IDataPackageAdapter"/> instance responsible for handling and processing incoming data.</param>
+    /// <param name="callback">A callback function to be invoked with the processed data of type <typeparamref name="TEntity"/>.  The callback
+    /// receives <see langword="null"/> if the data cannot be converted to <typeparamref name="TEntity"/>.</param>
+    public static void SetDataPackageAdapter<TEntity>(this ITcpSocketClient client, IDataPackageAdapter adapter, Func<TEntity?, Task> callback)
+    {
+        // 设置 ITcpSocketClient 的回调函数
+        client.ReceivedCallBack = async buffer =>
+        {
+            // 将接收到的数据传递给 DataPackageAdapter 进行数据处理合规数据触发 ReceivedCallBack 回调
+            await adapter.HandlerAsync(buffer);
+        };
+
+        // 设置 DataPackageAdapter 的回调函数
+        adapter.ReceivedCallBack = async buffer =>
+        {
+            TEntity? ret = default;
+            if (adapter.TryConvertTo(buffer, out var t))
+            {
+                if (t is TEntity entity)
+                {
+                    ret = entity;
+                }
+            }
+            await callback(ret);
+        };
+    }
 }

src/BootstrapBlazor/Services/TcpSocket/DataPackage/DataPackageAdapter.cs

@@ -44,6 +44,18 @@ public virtual async ValueTask HandlerAsync(ReadOnlyMemory<byte> data, Cancellat
         }
     }
 
+    /// <summary>
+    /// <inheritdoc/>
+    /// </summary>
+    /// <param name="data"></param>
+    /// <param name="entity"></param>
+    /// <returns></returns>
+    public virtual bool TryConvertTo(ReadOnlyMemory<byte> data, [NotNullWhen(true)] out object? entity)
+    {
+        entity = null;
+        return false;
+    }
+
     /// <summary>
     /// Handles incoming data by invoking a callback method, if one is defined.
     /// </summary>

src/BootstrapBlazor/Services/TcpSocket/DataPackage/DataPackageAdapterOfGeneric.cs

@@ -0,0 +1,24 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License
+// See the LICENSE file in the project root for more information.
+// Maintainer: Argo Zhang(argo@live.ca) Website: https://www.blazor.zone
+
+namespace BootstrapBlazor.Components;
+
+/// <summary>
+/// Provides a base implementation for adapting data packages between different systems or formats.
+/// </summary>
+/// <remarks>This abstract class serves as a foundation for implementing custom data package adapters. It defines
+/// common methods for sending, receiving, and handling data packages, as well as a property for accessing the
+/// associated data package handler. Derived classes should override the virtual methods to provide specific behavior
+/// for handling data packages.</remarks>
+public abstract class DataPackageAdapterBase<TEntity> : DataPackageAdapter
+{
+    /// <summary>
+    /// <inheritdoc/>
+    /// </summary>
+    /// <param name="data"></param>
+    /// <param name="entity"></param>
+    /// <returns></returns>
+    public abstract bool TryConvertTo(ReadOnlyMemory<byte> data, [NotNullWhen(true)] out TEntity? entity);
+}

src/BootstrapBlazor/Services/TcpSocket/DataPackage/IDataPackageAdapter.cs

@@ -39,4 +39,16 @@ public interface IDataPackageAdapter
     /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation. The task completes when the data has been
     /// successfully received and processed.</returns>
     ValueTask HandlerAsync(ReadOnlyMemory<byte> data, CancellationToken token = default);
+
+    /// <summary>
+    /// Attempts to convert the specified binary data into an object representation.
+    /// </summary>
+    /// <remarks>This method does not throw exceptions for invalid input. Instead, it returns <see
+    /// langword="false"/>  if the conversion fails, and <paramref name="entity"/> will be <see
+    /// langword="null"/>.</remarks>
+    /// <param name="data">The binary data to be converted. Must not be empty.</param>
+    /// <param name="entity">When this method returns <see langword="true"/>, contains the converted object.  When this method returns <see
+    /// langword="false"/>, the value is <see langword="null"/>.</param>
+    /// <returns><see langword="true"/> if the conversion was successful; otherwise, <see langword="false"/>.</returns>
+    bool TryConvertTo(ReadOnlyMemory<byte> data, [NotNullWhen(true)] out object? entity);
 }