DataParser 1.0.0

DataParser - 结构化数据解析器

一个基于特性的.NET数据解析库，允许开发者通过声明式编程将原始字节数据转换为强类型对象。

特性

• ✅ 声明式解析 - 使用特性定义数据结构，自动完成解析
• ✅ 多种数据类型 - 支持整数、浮点数、字符串、十六进制、字节数组等
• ✅ 字节序支持 - 灵活处理大端序和小端序数据
• ✅ 嵌套结构 - 支持复杂的嵌套对象解析
• ✅ 数组解析 - 支持固定长度和动态长度数组
• ✅ 多种输入格式 - 支持字节数组和十六进制字符串输入
• ✅ 可扩展 - 通过计算属性或自定义转换器扩展功能

快速开始

安装

将 DataParser 项目添加到您的解决方案中，并添加项目引用。

基本使用

1. 定义数据结构

using DataParser;

public class SimplePacket
{
    [BinaryField(0, 1, ConvertType.ToHex)]
    public string Header { get; set; } = string.Empty;

    [BinaryField(1, 2, ConvertType.ToInt16, IsLittleEndian = true)]
    public short Length { get; set; }

    [BinaryField(3, 4, ConvertType.ToString)]
    public string Data { get; set; } = string.Empty;

    [BinaryField(7, 1, ConvertType.ToHex)]
    public string Checksum { get; set; } = string.Empty;
}

2. 解析数据

var parser = new DataParser.DataParser();

// 从字节数组解析
byte[] data = new byte[] { 0xAA, 0x05, 0x00, 0x54, 0x65, 0x73, 0x74, 0xFF };
var packet = parser.Parse<SimplePacket>(data);

// 从十六进制字符串解析
string hexData = "AA-05-00-54-65-73-74-FF";
var packet2 = parser.Parse<SimplePacket>(hexData);

Console.WriteLine($"Header: {packet.Header}");  // 输出: AA
Console.WriteLine($"Data: {packet.Data}");      // 输出: Test

使用示例

混合字节序解析

public class MixedEndianPacket
{
    [BinaryField(0, 2, ConvertType.ToInt16, IsLittleEndian = true)]
    public short LittleInt16 { get; set; }

    [BinaryField(2, 2, ConvertType.ToInt16, IsLittleEndian = false)]
    public short BigInt16 { get; set; }
}

byte[] data = new byte[] { 0x01, 0x02, 0x01, 0x02 };
var packet = parser.Parse<MixedEndianPacket>(data);
// LittleInt16 = 513 (0x0201)
// BigInt16 = 258 (0x0102)

自定义数据转换

使用计算属性实现自定义转换：

public class SensorDataPacket
{
    [BinaryField(0, 2, ConvertType.ToInt16, IsLittleEndian = false)]
    public short TemperatureRaw { get; set; }
    
    // 自定义转换: 原始值除以10得到实际温度
    public double Temperature => TemperatureRaw / 10.0;
}

嵌套结构解析

public class NestedPacket
{
    [BinaryField(0, 2, ConvertType.ToHex, Order = 1)]
    public string Header { get; set; } = string.Empty;

    [BinaryField(2, 8, ConvertType.ToObject, Order = 2)]
    public Metadata Metadata { get; set; } = new Metadata();

    [BinaryField(10, 10, ConvertType.ToBytes, Order = 3)]
    public byte[] Payload { get; set; } = Array.Empty<byte>();
}

public class Metadata
{
    [BinaryField(0, 4, ConvertType.ToInt32, IsLittleEndian = true)]
    public int Timestamp { get; set; }

    [BinaryField(4, 2, ConvertType.ToInt16, IsLittleEndian = false)]
    public short PayloadLength { get; set; }
}

数组解析

固定长度数组

public class DeviceArrayPacket
{
    [BinaryField(0, 2, ConvertType.ToHex, Order = 1)]
    public string Header { get; set; } = string.Empty;

    [BinaryArray(2, Count = 3, ItemLength = 5, ElementType = typeof(DeviceInfo), Order = 2)]
    public DeviceInfo[] Devices { get; set; } = Array.Empty<DeviceInfo>();
}

public class DeviceInfo
{
    [BinaryField(0, 2, ConvertType.ToInt16, IsLittleEndian = true)]
    public short DeviceId { get; set; }

    [BinaryField(2, 1, ConvertType.ToHex)]
    public string Status { get; set; } = string.Empty;
}

动态长度数组

public class DynamicArrayPacket
{
    [BinaryField(0, 2, ConvertType.ToInt16, IsLittleEndian = true, Order = 1)]
    public short DeviceCount { get; set; }

    [BinaryArray(2, CountField = "DeviceCount", ItemLength = 5, 
                 ElementType = typeof(DeviceInfo), Order = 2)]
    public DeviceInfo[] Devices { get; set; } = Array.Empty<DeviceInfo>();
}

支持的数据类型

特性参数说明

BinaryFieldAttribute

BinaryArrayAttribute

错误处理

解析器提供详细的错误信息：

try
{
    var packet = parser.Parse<MyPacket>(data);
}
catch (InvalidDataLengthException ex)
{
    Console.WriteLine($"数据长度不足: 需要 {ex.RequiredLength} 字节，实际 {ex.ActualLength} 字节");
    Console.WriteLine($"字段: {ex.FieldName}, 偏移: {ex.Offset}");
}
catch (DataParseException ex)
{
    Console.WriteLine($"解析错误: {ex.Message}");
    Console.WriteLine($"字段: {ex.FieldName}");
}

最佳实践

1. 使用 Order 属性 - 当字段之间有依赖关系时（如动态数组），使用 Order 确保正确的解析顺序
2. 明确指定字节序 - 始终明确设置 IsLittleEndian 参数，避免歧义
3. 验证数据长度 - 在解析前验证输入数据长度是否足够
4. 使用计算属性 - 对于简单的数据转换，使用计算属性比自定义转换器更简洁
5. 嵌套深度限制 - 避免过深的嵌套结构（最大深度：10层）

运行示例

项目包含完整的示例程序：

cd StructDataConverterTest
dotnet run

示例涵盖：

• 基本数据类型解析
• 混合字节序处理
• 自定义数据转换
• 嵌套结构解析
• 固定和动态数组
• 错误处理

系统要求

• .NET 6.0 或更高版本
• C# 10.0 或更高版本

项目结构

.
├── DataParser/              # 核心解析库
│   ├── DataParser.cs       # 主解析器
│   ├── TypeConverter.cs    # 类型转换器
│   ├── ArrayProcessor.cs   # 数组处理器
│   ├── Attributes.cs       # 特性定义
│   └── Exceptions.cs       # 异常类
├── StructDataConverterTest/ # 示例和测试
│   └── Program.cs          # 完整示例代码
└── README.md               # 本文档

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

贡献

欢迎提交问题和拉取请求！