doc: 增加数据适配器文档

Author: ArgoZhang

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

@@ -0,0 +1,40 @@
+@page "/socket/adapter"
+@inject IStringLocalizer<Adapters> Localizer
+
+<h3>@Localizer["AdaptersTitle"]</h3>
+<h4>@Localizer["AdaptersDescription"]</h4>
+
+<Notice></Notice>
+
+<DemoBlock Title="@Localizer["NormalTitle"]"
+           Introduction="@Localizer["NormalIntro"]"
+           Name="Normal" ShowCode="false">
+    <p>本例中连接一个模拟自定义协议服务，每次接收到客户端发来的特定数据后，返回业务数据。这类应用在我们实际应用中非常常见</p>
+    <p>通过 <code>SocketClientOptions</code> 配置类关闭自动接收数据功能 <code>IsAutoReceive="false"</code></p>
+    <Pre>_client = TcpSocketFactory.GetOrCreate("demo-adapter", options =>
+{
+    options.IsAutoReceive = false;
+    options.LocalEndPoint = new IPEndPoint(IPAddress.Loopback, 0);
+});</Pre>
+    <ul class="ul-demo">
+        <li>点击 <b>连接</b> 按钮后通过 <code>ITcpSocketFactory</code> 服务实例创建的 <code>ITcpSocketClient</code> 对象连接到网站模拟 <code>TcpServer</code></li>
+        <li>点击 <b>断开</b> 按钮调用 <code>CloseAsync</code> 方法断开 Socket 连接</li>
+        <li>点击 <b>发送</b> 按钮调用 <code>SendAsync</code> 方法发送请求数据</li>
+    </ul>
+    <p>本例中已关闭自动接收功能，调用 <code>ReceivedAsync</code> 方法主动接收服务端返回数据</p>
+
+    <div class="row form-inline g-3">
+        <div class="col-12 col-sm-6">
+            <Button Text="连接" Icon="fa-solid fa-play"
+                    OnClick="OnConnectAsync" IsDisabled="@_client.IsConnected"></Button>
+            <Button Text="断开" Icon="fa-solid fa-stop" class="ms-2"
+                    OnClick="OnCloseAsync" IsDisabled="@(!_client.IsConnected)"></Button>
+            <Button Text="发送" Icon="fa-solid fa-paper-plane" class="ms-2" IsAsync="true"
+                    OnClick="OnSendAsync" IsDisabled="@(!_client.IsConnected)"></Button>
+        </div>
+        <div class="col-12">
+            <Console Items="@_items" Height="496" HeaderText="接收数据（间隔 10 秒）"
+                     ShowAutoScroll="true" OnClear="@OnClear"></Console>
+        </div>
+    </div>
+</DemoBlock>

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

@@ -0,0 +1,110 @@
+// 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([email protected]) Website: https://www.blazor.zone
+
+using System.Net;
+
+namespace BootstrapBlazor.Server.Components.Samples.Sockets;
+
+/// <summary>
+/// 数据适配器示例
+/// </summary>
+public partial class Adapters : IDisposable
+{
+    [Inject, NotNull]
+    private ITcpSocketFactory? TcpSocketFactory { get; set; }
+
+    private ITcpSocketClient _client = null!;
+
+    private List<ConsoleMessageItem> _items = [];
+
+    private readonly IPEndPoint _serverEndPoint = new(IPAddress.Loopback, 8900);
+
+    private CancellationTokenSource _connectTokenSource = new();
+    private CancellationTokenSource _sendTokenSource = new();
+
+    /// <summary>
+    /// <inheritdoc/>
+    /// </summary>
+    protected override void OnInitialized()
+    {
+        base.OnInitialized();
+
+        // 从服务中获取 Socket 实例
+        _client = TcpSocketFactory.GetOrCreate("demo-adapter", options =>
+        {
+            options.IsAutoReceive = false;
+            options.LocalEndPoint = new IPEndPoint(IPAddress.Loopback, 0);
+        });
+    }
+
+    private async Task OnConnectAsync()
+    {
+        if (_client is { IsConnected: false })
+        {
+            await _client.ConnectAsync(_serverEndPoint, _connectTokenSource.Token);
+        }
+    }
+
+    private async Task SendAsync()
+    {
+        if (_client is { IsConnected: false })
+        {
+            // 准备通讯数据
+            var data = new byte[1024];
+            await _client.SendAsync(data, _sendTokenSource.Token);
+        }
+    }
+
+    private async Task OnCloseAsync()
+    {
+        if (_client is { IsConnected: true })
+        {
+            await _client.CloseAsync();
+        }
+    }
+
+    private Task OnClear()
+    {
+        _items = [];
+        return Task.CompletedTask;
+    }
+
+    private async ValueTask OnReceivedAsync(ReadOnlyMemory<byte> data)
+    {
+        // 将数据显示为十六进制字符串
+        var payload = System.Text.Encoding.UTF8.GetString(data.Span);
+        _items.Add(new ConsoleMessageItem
+        {
+            Message = $"接收到来自站点的数据为 {payload}"
+        });
+
+        // 保持队列中最大数量为 50
+        if (_items.Count > 50)
+        {
+            _items.RemoveAt(0);
+        }
+        await InvokeAsync(StateHasChanged);
+    }
+
+    private void Dispose(bool disposing)
+    {
+        if (disposing)
+        {
+            if (_client is { IsConnected: true })
+            {
+
+            }
+        }
+    }
+
+    /// <summary>
+    /// <inheritdoc/>
+    /// </summary>
+    public void Dispose()
+    {
+        Dispose(true);
+        GC.SuppressFinalize(this);
+    }
+}