连接字符串构建器 (ConnectionStringBuilder)

约 668 字大约 2 分钟

2026-05-19

概述 (Overview)

ConnectionStringBuilder 是 UniCon 核心层（Core）提供的实用工具类，旨在为用户提供强类型、流式（Fluent）的链式接口来动态组建各种工业协议（S7、Modbus、MQTT、OPC UA、PubSub）的连接字符串，彻底避免手动拼接字符串导致的语法拼写错误，大幅提升开发效率与使用体验。

同时，框架还为 IUniconDriver 提供了快捷连接扩展方法（如 ConnectS7Async），可直接在驱动实例上调用，无需手动拼接连接字符串。

使用方法 (Usage)

通过 ConnectionStringBuilder 的静态入口创建对应协议的 Builder 实例，链式设置属性后调用 Build() 生成连接字符串；或直接在驱动实例上使用快捷的扩展连接方法。

参数说明 (Parameters)

S7Builder 属性与参数

参数名	类型	说明	是否必填	默认值
cpuType	`S7CpuType`	PLC CPU 类型枚举（支持 `S7200`, `S7300`, `S7400`, `S71200`, `S71500`）	是	`S7CpuType.S71200`
ip	`string`	PLC 的 IP 地址	是	`127.0.0.1`
rack	`short`	机架号	否	`0`
slot	`short`	插槽号	否	`1`

ModbusBuilder 属性与参数

参数名	类型	说明	是否必填	默认值
ip	`string`	Modbus 从站或网关的 IP 地址	是	`127.0.0.1`
port	`int`	Modbus 服务端口	否	`502`

OpcUaPubSubBuilder 属性与参数

参数名	类型	说明	是否必填	默认值
scheme	`PubSubScheme`	传输协议模式（支持 `Udp`, `Mqtt`）	是	`PubSubScheme.Udp`
host	`string`	组播 IP 地址或 Broker IP	是	`224.0.2.14`
port	`int`	端口号	是	`4840`
topic	`string`	MQTT 订阅的 Topic 路径（仅 MQTT 模式有效）	否	`""`

返回值 (Returns)

Build() 方法返回值

类型	说明
`string`	拼接完整、格式正确的底层驱动所需物理连接字符串

扩展连接方法（如 ConnectS7Async）返回值

类型	说明
`Task<bool>`	驱动初始连接动作的异步布尔值（是否连接成功）

使用示例 (Examples)

示例 1：使用强类型流式构建 S7 连接串

using UniCon.Core.Helpers;

string connStr = ConnectionStringBuilder.S7()
    .WithCpuType(S7CpuType.S71500)
    .WithIp("192.168.1.10")
    .WithRack(0)
    .WithSlot(1)
    .Build();
// 输出: CpuType=S71500;Ip=192.168.1.10;Rack=0;Slot=1

示例 2：直接使用快捷连接扩展方法（推荐）

在已使用 IDriverRegistry 的项目中，驱动由工厂创建（DI 自动装配依赖）：

using UniCon.Core;
using UniCon.Core.Helpers;

// 通过 DI 工厂创建驱动（自动装配所有依赖）
var driver = _driverRegistry.CreateDriver("S7", "Line1_PLC");
_driverRegistry.Register(driver);

// 强类型、参数自解释的快捷连接扩展方法
bool isConnected = await driver.ConnectS7Async("192.168.1.10", S7CpuType.S71500);

示例 3：Modbus 连接串构建

string connStr = ConnectionStringBuilder.Modbus()
    .WithIp("192.168.0.50")
    .WithPort(502)
    .Build();
// 输出: ip=192.168.0.50;port=502

示例 4：OPC UA PubSub UDP 组播连接串构建

string connStr = ConnectionStringBuilder.OpcUaPubSub()
    .WithScheme(PubSubScheme.Udp)
    .WithHost("224.0.2.14")
    .WithPort(4840)
    .Build();
// 输出: opc.udp://224.0.2.14:4840