doc(SerialPort): add ISerialPortFactory documentation (#6775)

* doc: 更新 ModbusFactory 文档

* doc:  更新 SocketFactory 文档

* doc: 更新 SocketClient 文档

* doc: 增加菜单

* doc: 增加源码文件映射

* doc: 增加串口通信服务文档

* doc: 更新注意事项

* doc: 增加串口参数配置类文档

Author: ArgoZhang

src/BootstrapBlazor.Server/Components/Samples/Modbus/ModbusFactories.razor

@@ -1,24 +1,24 @@
 @page "/modbus-factory"
 @inject IStringLocalizer<ModbusFactories> Localizer
 
-<h3>Modbus 串行通讯服务 <code>IModbusFactory</code></h3>
-<h4>组件库内置了 Modbus 串行通讯服务</h4>
+<h3>Modbus 串行通信服务 <code>IModbusFactory</code></h3>
+<h4>组件库内置了 Modbus 串行通信服务</h4>
 
 <PackageTips Name="Longbow.Modbus" />
 
-<Tips><div>特别注意：本服务需要 <code>Socket</code> 支持，不支持 <code>wasm</code> 模式</div></Tips>
+<Tips><div>特别注意：本服务不支持 <code>wasm</code> 模式</div></Tips>
 
 <p class="code-label">1. 服务注入</p>
 
 <Pre>services.AddModbusFactory();</Pre>
 
-<p class="code-label">2. 使用服务</p>
-<p>调用 <code>ModbusFactory</code> 实例方法 <code>GetOrCreateTcpMaster</code> 即可得到一个 <code>IModbusClient</code> 实例。内部提供复用机制，调用两次得到的 <code>IModbusClient</code> 为同一对象</p>
-
 <Pre>[Inject]
 [NotNull]
 private IModbusFactory? ModbusFactory { get; set; }</Pre>
 
+<p class="code-label">2. 使用服务</p>
+<p>调用 <code>ModbusFactory</code> 实例方法 <code>GetOrCreateTcpMaster</code> 即可得到一个 <code>IModbusClient</code> 实例。内部提供复用机制，调用两次得到的 <code>IModbusClient</code> 为同一对象</p>
+
 <p class="code-label">3. 通过工厂获得相对应协议 <code>IModbusClient</code> 实例</p>
 
 <p><code>IModbusClient</code> 有两个派生类</p>

src/BootstrapBlazor.Server/Components/Samples/SerialPorts/SerialPortFactories.razor

@@ -0,0 +1,50 @@
+@page "/serial-port-factory"
+@inject IStringLocalizer<SerialPortFactories> Localizer
+
+<h3>SerialPort 串行通信服务 <code>ISerialPortFactory</code></h3>
+<h4>组件库内置了 SerialPort 串口通信服务</h4>
+
+<PackageTips Name="Longbow.SerialPort" />
+
+<Tips><div>特别注意：本服务不支持 <code>wasm</code> 模式</div></Tips>
+
+<p class="code-label">1. 服务注入</p>
+
+<Pre>services.AddSerialPortFactory();</Pre>
+
+<Pre>[Inject]
+[NotNull]
+private ISerialPortFactory? SerialPortFactory { get; set; }</Pre>
+
+<p class="code-label">2. 使用服务</p>
+<p>调用 <code>SerialPortFactory</code> 实例方法 <code>GetOrCreate</code> 即可得到一个 <code>ISerialPortClient</code> 实例。内部提供复用机制，调用两次得到的 <code>ISerialPortClient</code> 为同一对象</p>
+
+<p class="code-label">3. 通过工厂获得相对应协议 <code>ISerialPortClient</code> 实例</p>
+
+<p><code>ISerialPortFactory</code> 实例方法</p>
+
+<ul class="ul-demo">
+    <li>通过 <code>GetOrCreate</code> 获得 <code>ISerialPortClient</code> 实例</li>
+    <li>通过 <code>Remove</code> 移除指定名称的 <code>ISerialPortClient</code> 实例</li>
+</ul>
+
+<Pre>SerialPortFactory.Remove("test");</Pre>
+
+<p>可以通过注入服务直接获得 <code>ISerialPortClient</code> 实例</p>
+
+<Pre>[Inject]
+[NotNull]
+private ISerialPortClient? SerialPortClient { get; set; }</Pre>
+
+<p><code>ISerialPortClient</code> 实例方法</p>
+
+<ul class="ul-demo">
+    <li>打开端口方法 <code>OpenAsync</code></li>
+    <li>发送数据方法 <code>SendAsync</code></li>
+    <li>接收数据方法 <code>ReceiveAsync</code></li>
+    <li>关闭端口方法 <code>CloseAsync</code></li>
+</ul>
+
+<p class="code-label">4. 串口参数配置类 <code>SerialPortOptions</code></p>
+
+<p>通过此配置类对串口参数进行配置</p>

src/BootstrapBlazor.Server/Components/Samples/SerialPorts/SerialPortFactories.razor.cs

@@ -0,0 +1,14 @@
+// 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.Server.Components.Samples.SerialPorts;
+
+/// <summary>
+/// ISerialPortFactory 服务说明文档
+/// </summary>
+public partial class SerialPortFactories
+{
+
+}

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

@@ -2,28 +2,34 @@
 @inject IStringLocalizer<SocketFactories> Localizer
 
 <h3>Tcp 套接字服务 <code>ITcpSocketFactory</code></h3>
-<h4>组件库内置了 Socket 套接字通讯服务</h4>
+<h4>组件库内置了 Socket 套接字通信服务</h4>
 
 <PackageTips Name="Longbow.TcpSocket" />
 
-<Tips><div>特别注意：本服务需要 <code>Socket</code> 支持，不支持 <code>wasm</code> 模式</div></Tips>
+<Tips><div>特别注意：本服务不支持 <code>wasm</code> 模式</div></Tips>
 
 <p class="code-label">1. 服务注入</p>
 
 <Pre>services.AddTcpSocketFactory();</Pre>
 
-<p class="code-label">2. 使用服务</p>
-<p>调用 <code>TcpSocketFactory</code> 实例方法 <code>GetOrCreate</code> 即可得到一个 <code>ITcpSocketClient</code> 实例。内部提供复用机制，调用两次得到的 <code>ITcpSocketClient</code> 为同一对象</p>
-
 <Pre>[Inject]
 [NotNull]
 private ITcpSocketFactory? TcpSocketFactory { get; set; }</Pre>
 
+<p class="code-label">2. 使用服务</p>
+<p>调用 <code>TcpSocketFactory</code> 实例方法 <code>GetOrCreate</code> 即可得到一个 <code>ITcpSocketClient</code> 实例。内部提供复用机制，调用两次得到的 <code>ITcpSocketClient</code> 为同一对象</p>
+
 <Pre>var client = TcpSocketFactory.GetOrCreate("bb", options =>
 {
     options.LocalEndPoint = new IPEndPoint(IPAddress.Loopback, 0);
 });</Pre>
 
+<p>可以通过注入服务直接获得 <code>ITcpSocketClient</code> 实例</p>
+
+<Pre>[Inject]
+[NotNull]
+private ITcpSocketClient? TcpSocketClient { get; set; }</Pre>
+
 <p class="code-label">3. 使用方法</p>
 
 <p>注意：以下方法均为线程不安全方法，多线程并发时需要自行处理</p>

src/BootstrapBlazor.Server/Extensions/MenusLocalizerExtensions.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information.
 // Maintainer: Argo Zhang(argo@live.ca) Website: https://www.blazor.zone
 
+using Longbow.SerialPorts;
 using Microsoft.AspNetCore.Components.Routing;
 
 namespace BootstrapBlazor.Server.Extensions;
@@ -97,6 +98,13 @@ public static List<MenuItem> GenerateMenus(this IStringLocalizer<NavMenu> Locali
         };
         AddModbus(item);
 
+        item = new DemoMenuItem()
+        {
+            Text = Localizer["SerialPortComponents"],
+            Icon = "fa-fw fa-solid fa-satellite-dish text-danger"
+        };
+        AddSerialPort(item);
+
         item = new DemoMenuItem()
         {
             Text = Localizer["Services"],
@@ -266,6 +274,21 @@ void AddModbus(DemoMenuItem item)
             AddBadge(item, count: 2);
         }
 
+        void AddSerialPort(DemoMenuItem item)
+        {
+            item.Items = new List<DemoMenuItem>
+            {
+                new()
+                {
+                    IsNew = true,
+                    Text = Localizer["SerialPortFactory"],
+                    Url = "serial-port-factory"
+                }
+            };
+
+            AddBadge(item, count: 2);
+        }
+
         void AddQuickStar(DemoMenuItem item)
         {
             item.Items = new List<DemoMenuItem>

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

@@ -4862,7 +4862,9 @@
     "SocketAutoConnect": "Reconnect",
     "SocketDataEntity": "DataEntity",
     "ModbusComponents": "Modbus Services",
+    "SerialPortComponents": "SerialPort Services",
     "ModbusFactory": "IModbusFactory",
+    "SerialPortFactory": "ISerialPortFactory",
     "NetworkMonitor": "Network Monitor",
     "Toolbar": "Toolbar",
     "OpcDaService": "OpcDaServer",

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

@@ -4860,9 +4860,11 @@
     "SocketManualReceive": "手动接收数据",
     "DataPackageAdapter": "数据适配器",
     "SocketAutoConnect": "自动重连",
-    "SocketDataEntity": "通讯数据转实体类",
+    "SocketDataEntity": "通信数据转实体类",
     "ModbusComponents": "串行通信协议 Modbus",
-    "ModbusFactory": "通讯服务 IModbusFactory",
+    "SerialPortComponents": "串行通信协议 SerialPort",
+    "ModbusFactory": "通信服务 IModbusFactory",
+    "SerialPortFactory": "通信服务 ISerialPortFactory",
     "NetworkMonitor": "网络状态 NetworkMonitor",
     "Toolbar": "工具栏 Toolbar",
     "OpcDaService": "OpcDaServer 服务",

src/BootstrapBlazor.Server/docs.json

@@ -254,7 +254,8 @@
     "opc-da": "OpcDa",
     "navbar": "Navbars",
     "task-board": "TaskBoard",
-    "modbus-factory": "Modbus\\ModbusFactories"
+    "modbus-factory": "Modbus\\ModbusFactories",
+    "serial-port-factory": "SerialPorts\\SerialPortFactories"
   },
   "video": {
     "table": "BV1ap4y1x7Qn?p=1",