文档/API 参考/地址模型

📐 地址模型

命名空间: Snet.Model.data | 类: Address, AddressDetails, AddressValue

地址模型系统定义了 Snet 如何在协议驱动和物理设备之间表示、配置和传输数据。三个类协同工作：Address（容器）、AddressDetails（点位配置）、AddressValue（带采集数据的点位）。

模型层次结构

Address                         -- 容器，含 SN + AddressArray(List<AddressDetails>)
AddressDetails                  -- 单个点位：地址名、数据类型、长度、编码、MQ 参数
  └── AddressValue              -- 继承 AddressDetails，增加 Quality、ResultValue、OriginalValue、Time

Address

用于一组读写地址点的顶层容器。

属性	类型	默认值	描述
`SN`	`string`	`Guid.NewGuid().ToUpperNString()`	唯一标识符（可存机台号、组名、车间、厂）
`AddressArray`	`List<AddressDetails>`	—	所有地址点位
`CreationTime`	`DateTime`	`DateTime.Now`	创建时间

关键方法：CheckAddress() 验证无空地址名，RemoveVirtualAddress() 筛选仅 AddressType.Reality，GetRealityAddressCount() 统计实际地址数。

var address = new Address
{
    SN = "Station1",
    AddressArray = new List<AddressDetails>
    {
        new("温度", DataType.Int16),
        new("湿度", DataType.Int16),
    }
};

AddressDetails

单个点位的配置。独立类（不继承 Address）。

属性	类型	默认值	描述
`SN`	`string`	`Guid.NewGuid().ToUpperNString()`	唯一标识符
`AddressName`	`string`	—	必填。 PLC 地址（如 "1", "DB1.DBX0.0"）。扩展数据时可为空
`AddressAnotherName`	`string?`	`null`	地址别名
`AddressPropertyName`	`string?`	`null`	地址属性名（对应实体字段名）
`AddressDescribe`	`string?`	`null`	描述说明
`AddressDataType`	`DataType`	`String`	数据类型
`AddressType`	`AddressType`	`Reality`	Reality=实际地址，VirtualDynamic_*=虚拟仿真
`Length`	`ushort`	`1`	数组长度；使用 Array 类型时按需调整
`EncodingType`	`EncodingType`	`UTF8`	字符串编码（26.235.x 起构造参数默认 `null` → `UTF8`；此前为 `ANSI`）
`IsEnable`	`bool`	`true`	`false`=跳过此点位采集
`AddressMqParam`	`AddressMq?`	`null`	MQ 转发配置 (ISns + Topic + ContentFormat)
`AddressParseParam`	`AddressParse?`	`null`	反射解析配置
`AddressExtendParam`	`object?`	`null`	指定通信的扩展数据

多种构造函数：

// 最简
new AddressDetails("温度", DataType.Int16);

// 完整
new AddressDetails(sn, addressName, alias, propName, desc,
    extendParam, mqParam, parseParam,
    dataType, addressType, isEnable, length, encodingType);

AddressValue

继承 AddressDetails，增加数据质量和值字段。是 ReadAsync 返回的主要数据载体。

属性	类型	默认值	描述
（所有 `AddressDetails` 属性）	—	—	继承的点位配置
`Quality`	`QualityType`	`None` (-1)	数据质量枚举（见下方）
`ResultValue`	`object?`	`null`	解析后的值（经过类型转换/解析）
`OriginalValue`	`object?`	`null`	解析前的值（原始数据；未解析时与 ResultValue 一致）
`Message`	`string?`	—	详细信息
`Time`	`DateTime`	`DateTime.Now`	采集时间戳

关键方法：

GetDetails(out resultValue, out originalValue, out message, out time) → 返回 QualityType
GetSimplify() → 转为轻量级 AddressValueSimplify 传输模型（Protobuf 优化）
SET(AddressDetails) / SET(value, source, time, bytesModel, msg, quality) → 流式配置

完整构造函数：

new AddressValue(
    quality: QualityType.Normal,
    resultValue: 25.6f,
    originalValue: rawBytes,
    message: "成功",
    time: DateTime.Now,
    addressDetails: detail
);

其他构造函数重载（均要求 quality、resultValue、originalValue、message；time 与 addressDetails 可选）：

// 默认构造函数
new AddressValue();

// 最小字段
new AddressValue(QualityType.Normal, 25.6f, rawBytes, "成功");

// 带时间戳
new AddressValue(QualityType.Normal, 25.6f, rawBytes, "成功", DateTime.Now);

// 带时间戳 + 地址详情
new AddressValue(QualityType.Normal, 25.6f, rawBytes, "成功", DateTime.Now, detail);

// 带地址详情（无时间戳）
new AddressValue(QualityType.Normal, 25.6f, rawBytes, "成功", detail);

QualityType 质量码枚举

枚举 QualityType : int，位于 Snet.Model.@enum 命名空间。每个值带有中文 [Description] 特性。

值	枚举	Int	描述 (EN)	描述 (ZH)
-1	`None`	-1	Not yet processed	未经过处理
0	`Exception`	0	Error / exception	异常
1	`Normal`	1	正常 — 触发 MQ 自动转发	正常
2	`DataTypeError`	2	Data type mismatch	数据类型错误
3	`ParseUnknown`	3	Parsed successfully but correctness unknown (also triggers MQ forward)	数据经过解析，并且解析成功，无法得知数据的正确性
4	`ParseError`	4	Parse failed	解析错误