字节转换 - Snet Docs
文档/核心引擎/字节转换

🔄 字节转换

Snet 的字节转换系统处理协议和设备之间的字节序（端序）差异。

DataFormat（字节序）

格式 名称 描述 示例 (0x12345678)
ABCD 大端序 高字节在前 12 34 56 78
BADC 字交换大端序 每16位字交换 34 12 78 56
CDAB 字交换 16 位字交换（低字在前） 56 78 12 34
DCBA 小端序 完全倒序 78 56 34 12

使用方法

var basics = new ModbusData.Basics
{
    IpAddress = "192.168.1.100",
    Port = 502,
    DataFormat = Snet.Driver.Core.DataFormat.CDAB,
    IsStringReverse = false,
};

BytesTransformHandler

BytesTransformHandler（Snet.Core.handler）通过 TransBool、TransInt16、TransFloat、TransString 等方法转换基础值与字节；无参构造默认 DataFormat.DCBA，可用传入 DataFormat 的构造选择其他字节序。应用 BytesModel 映射并返回 ConcurrentDictionary<string, AddressValue> 的是 BytesHandler，不是 BytesTransformHandler。

EncodingType（编码类型）

编码 代码页
UTF8 65001
Unicode（UTF-16） 1200
BigEndianUnicode（UTF-16 大端） 1201
UTF32 12000
BigEndianUTF32（UTF-32 大端） 12001
ASCII 20127
ANSI 0（26.235.x 起映射 GBK/GB2312 936——0 不是合法代码页）
GB2312 936
大端编码

BigEndianUnicode / BigEndianUTF32 解析为真实 .NET Encoding 实例（Encoding.BigEndianUnicode / 无 BOM 的 UTF-32 大端）——代码页 1201/12001 不是 .NET 已注册代码页，直接 Encoding.GetEncoding(代码页) 会抛异常。这正是西门子 WString（UTF-16 大端）解包可用的原因。GetEncoding() 对 null 的 EncodingType? 返回 UTF8。

BytesHandler.Transform / TransformAsync

BytesHandler（单例，Snet.Core.handler）将组包批次的原始字节解析回各地址的值：

编码说明（26.236.x 起）

BytesHandler 静态构造函数注册 CodePagesEncodingProvider.Instance——类型首次使用即注册，GB2312/GBK（936）与 GB18030（54936）立即可解析，解包 GB2312 编码字符串无需手动调用 Encoding.RegisterProvider。

public OperateResult Transform(AddressValue addressValue, bool isStringReverseByteWord = false);
public Task<OperateResult> TransformAsync(AddressValue addressValue, bool isStringReverseByteWord = false, CancellationToken token = default);
public OperateResult Transform(byte[] bytes, DateTime time, IEnumerable<BytesModel> transformParams, bool isStringReverseByteWord = false);
public Task<OperateResult> TransformAsync(byte[] bytes, DateTime time, IEnumerable<BytesModel> transformParams, bool isStringReverseByteWord = false, CancellationToken token = default);
参数 描述
isStringReverseByteWord String 解包时是否按 16 位字反转字节（每 2 字节一组交换）。连接级配置——如欧姆龙 FINS 的字符串按字反转字节读取。默认 false

仅 AddressDataType=ByteArray 且扩展参数可取得 List 时按字节批解码；其他值以单点字典返回原 AddressValue 同对象，Status 由 Quality==Normal 决定。已识别字节批须质量正常且 OriginalValue 为 byte[]，否则按每个模型返回 Exception 质量点并置 Status=false。偏移、长度或 BoolIndex 越界保留失败项，成功项仍可读取。空字节对非空模型逐项校验边界，空模型可成功返回空字典。异步取消可能传播异常，不承诺取消仅返回失败结果。 Byte 从模型切片索引0取值，BoolIndex 仅用于 Bool。

DaqAbstract.UnPacker 的字典重载可统一处理组包批与直接值，对各项 Status 做与运算，保留所有返回字典（包括失败/部分结果）。任一失败则整体 Status=false（部分点位解包失败）；仍应读取 ResultData 并逐点检查 Quality，不要丢弃结果列表。空字典成功返回空列表，null 输入失败。同名多规格结果键可带 \u0001DataType/序号后缀，AddressValue.AddressName 保留原地址。

同名映射不会静默覆盖：结果键冲突时先追加 \u0001DataType，仍冲突再追加 \u0001 与递增序号；AddressValue.AddressName 保持原地址。按该属性关联原点位，不能假定每个字典键都是未经修改的地址名。

Driver的ushort数组扩宽

Snet.Driver.Core.ByteTransformHelper.TransInt32Array(ushort[] array) 返回等长int[]，逐元素无损扩宽；null输入返回null（签名未标注可空）。它不是字节序转换，也不是BytesTransformHandler的方法。

另请参阅