SunnyUI.FrameDecoder v7.1.1 — nugetz
yhuse/SunnyUI.FrameDecoderv7.1.1
✓ Verified.NET FW4.7.2.NET 8.0.NET 9.0
SunnyUI.FrameDecoder 开源TCP、UDP、串口数据解码库
Get Started
$ dotnet add package SunnyUI.FrameDecoderReadme
SunnyUI.FrameDecoder
欢迎交流，QQ群： 56829229 (SunnyUI技术交流群)，请给源码项目点个Star吧！！！
开始
从Nuget安装最新版本。
Install-Package SunnyUI.FrameDecoder
目的
SunnyUI.FrameDecoder 开源TCP、UDP、串口等流式数据解码库
- 实现解码自由
- 底层缓冲区采用数据池实现
- 通过使用池化缓冲区来消除大型对象堆分配
- 减少GC次数
- 缓冲区实现IBufferWrite接口
- 广泛支持较新的内存相关类型，如
Span<byte>, ReadOnlySpan<byte>以及Memory<byte>
- 避免内存碎片
- 提供出色的性能
介绍
TCP是面向连接的传输协议，TCP传输的数据是以流的形式，而流数据是没有明确的开始结尾边界，应用层处理接收数据时可能产生半包或者粘包，其主要原因如下：
- TCP发送方原因：
因为TCP本身传输的数据包大小就有限制，所以应用发出的消息包过大，TCP会把应用消息包拆分为多个TCP数据包发送出去。
Negal算法的优化，当应用发送数据包太小，TCP为了减少网络请求次数的开销，它会等待多个消息包一起，打成一个TCP数据包一次发送出去。
- TCP接收方原因：
因为TCP缓冲区里的数据都是字符流的形式，没有明确的边界，因为数据没边界，所以应用从TCP缓冲区中读取数据时就没办法指定一个或几个消息一起读，而只能选择一次读取多大的数据流，而这个数据流中就可能包含着某个消息包的一部分数据。
所以为了解决半包或者粘包，得到应用层需要的数据，实现解码自由，开发了此数据解码库，原理也就是给数据流转时给流式数据加上消息边界。在接收数据时，将流式数据通过相应的解码器（FrameDecoder），解码输出完整的帧数据（FrameData）。
UDP是面向消息的，它有边界协议，可以根据消息的格式区分消息的开始和结尾。那为什么还要解码呢？
举个例子，实际项目：FPGA通过千兆网卡将数据以UDP协议输出，其数据实际还是流式数据，需要在UDP接收到的数据中寻找包头和包尾，来截取一段需要的数据，这样数据解码器就有意义了。
串口在数据发送和接收时，根据串口的配置（波特率、奇偶校验等）、串口缓冲设置、数据发送间隔的不匹配，也会出现接收数据时可能产生半包或者粘包。
Modbus-RTU总线是通过时间间隔来判断一帧数据结束的，3.5个字符时间内没有收到新的数据，则认为这一帧数据结束。
普通的串口数据传输，还是要给数据增加消息边界，通过解码器来获取实际需要的数据。
其实不限于TCP、UDP、串口，只要是从流式数据中获取指定格式的数据，都可以用过解码器来实现。
SunnyUI.FrameDecoder则面向流式数据，不拘泥于数据从哪儿来，通过流式数据的解码器来获取到有用的数据。
软件架构
针对这两种数据，实现了泛型数据缓存： DataCache<T>，其内存分配通过数据池：DataPool<T> 实现
通过DataCache<byte>实现字节数据组缓存，通过DataCache<char>实现字符串缓存
安装教程
动态库应用环境： VS2012及以上均可，支持.Net Framework 4.5+、包括.Net 6、.Net7
推荐通过Nuget安装：NuGet\Install-Package SunnyUI.FrameDecoder
或者通过Nuget搜索：SunnyUI.FrameDecoder 安装。
使用说明
- DelimiterBasedFrameDecoder 基于分隔符 - 数据帧解码器
数据格式：
/// <summary>
/// 构造函数
/// </summary>
/// <param name="delimiters">分隔符，最好为多字节，并且数据中不会出现分隔符而造成误解码</param>
/// <param name="maxFrameLength">最大数据长度，仅判断数据长度</param>
public DelimiterBasedFrameDecoder(byte[] delimiters, int maxFrameLength = 0)
var bts = new byte[] { 1, 2, 3, 0xFF, 0xFB };
var decoder1 = new DelimiterBasedFrameDecoder(new byte[] { 0xFF, 0xFB });
decoder1.OnDecoder += DelimiterBasedFrameDecoder_OnDecoder;
decoder1.Decode(bts);
private static void DelimiterBasedFrameDecoder_OnDecoder(object sender, IByteEventArgs e)
{
Console.WriteLine("Value: " + ByteHelper.HexString(e.Value));
}
Value: 010203
- FixedLengthFrameDecoder 固定长度 - 数据帧解码器
数据格式：
/// <summary>
/// 构造函数
/// </summary>
/// <param name="frameLength">帧固定长度</param>
public FixedLengthFrameDecoder(int frameLength)
var bts = new byte[] { 1, 2, 3, 4, 5, 6, 7, 8 };
var decoder0 = new FixedLengthFrameDecoder(3);
decoder0.OnDecoder += FixedLengthFrameDecoder_OnDecoder;
decoder0.Decode(bts);
private static void FixedLengthFrameDecoder_OnDecoder(object sender, IByteEventArgs e)
{
Console.WriteLine("Value: " + ByteHelper.HexString(e.Value));
}
Value: 010203
Value: 040506
- HeaderDelimiterFrameDecoder 数据头部 - 数据帧解码器
数据格式：
/// <summary>
/// 构造函数
/// </summary>
/// <param name="headers">数据头部</param>
/// <param name="maxFrameLength">最大数据长度，仅判断数据长度</param>
public HeaderDelimiterFrameDecoder(byte[] headers, int maxFrameLength = 0)
var bts = new byte[] { 0xFF, 0xFB, 1, 2, 3 };
var decoder2 = new HeaderDelimiterFrameDecoder(new byte[] { 0xFF, 0xFB });
decoder2.OnDecoder += HeaderDelimiterFrameDecoder_OnDecoder;
decoder2.Decode(bts);
decoder2.Decode(bts);
private static void HeaderDelimiterFrameDecoder_OnDecoder(object sender, IByteEventArgs e)
{
Console.WriteLine("Value: " + ByteHelper.HexString(e.Value));
}
Value: 010203
- HeaderTagLengthValueTailFrameDecoder 数据头部、标签、数据长度、数据、数据尾部 - 数据帧解码器
数据格式：
/// <summary>
/// 构造函数
/// </summary>
/// <param name="headers">数据头部</param>
/// <param name="tails">数据尾部</param>
/// <param name="tagLength">标签长度</param>
/// <param name="valueLengthType">数据长度类型</param>
/// <param name="valueIsLittleEndian">数据长度字节顺序</param>
/// <param name="isFullLength">数据长度是否包含数据头部、标签、数据长度、数据尾部的长度，false为仅数据长度</param>
/// <param name="maxFrameLength">最大数据长度，仅判断数据长度</param>
public HeaderTagLengthValueTailFrameDecoder(byte[] headers, byte[] tails, int tagLength, ValueLengthType valueLengthType, bool valueIsLittleEndian = true, bool isFullLength = false, int maxFrameLength = 0)
var bts = new byte[] { 0xFF, 0xFB, 0xAA, 2, 3, 4, 0xF7, 0xF7 };
var decoder3 = new HeaderTagLengthValueTailFrameDecoder(new byte[] { 0xFF, 0xFB }, new byte[] { 0xF7, 0xF7 }, 1, ValueLengthType.Byte);
decoder3.OnDecoder += HeaderTagLengthValueTailFrameDecoder_OnDecoder;
decoder3.Decode(bts);
private static void HeaderTagLengthValueTailFrameDecoder_OnDecoder(object sender, IByteEventArgs e)
{
var args = (TagLengthValueFrameDataEventArgs)e;
Console.WriteLine("Tag: " + ByteHelper.HexString(args.Tag) + ", Value: " + ByteHelper.HexString(args.Value));
}
Tag: AA, Value: 0304
- HeaderTailFrameDecoder 数据头部、数据尾部 - 数据帧解码器
数据格式：
/// <summary>
/// 构造函数
/// </summary>
/// <param name="headers">数据头部</param>
/// <param name="tails">数据尾部</param>
/// <param name="maxFrameLength">最大数据长度，仅判断数据长度</param>
public HeaderTailFrameDecoder(byte[] headers, byte[] tails, int maxFrameLength = 0)
var bts = new byte[] { 0xFF, 0xFB, 2, 3, 4, 0xF7, 0xF7 };
var decoder4 = new HeaderTailFrameDecoder(new byte[] { 0xFF, 0xFB }, new byte[] { 0xF7, 0xF7 });
decoder4.OnDecoder += HeaderTailFrameDecoder_OnDecoder;
decoder4.Decode(bts);
private static void HeaderTailFrameDecoder_OnDecoder(object sender, IByteEventArgs e)
{
Console.WriteLine("Value: " + ByteHelper.HexString(e.Value));
}
Value: 020304
- LengthValueFrameDecoder 数据长度、数据 - 数据帧解码器
数据格式：
/// <summary>
/// 构造函数
/// </summary>
/// <param name="valueLengthType">数据长度类型</param>
/// <param name="valueIsLittleEndian">数据长度字节顺序</param>
/// <param name="isFullLength">数据长度是否包含数据长度的长度，false为仅数据长度</param>
/// <param name="maxFrameLength">最大数据长度，仅判断数据长度</param>
public LengthValueFrameDecoder(ValueLengthType valueLengthType, bool valueIsLittleEndian = true, bool isFullLength = false, int maxFrameLength = 0)
bts = new byte[] { 2, 3, 4 };
var decoder5 = new LengthValueFrameDecoder(ValueLengthType.Byte);
decoder5.OnDecoder += LengthValueFrameDecoder_OnDecoder;
decoder5.Decode(bts);
private static void LengthValueFrameDecoder_OnDecoder(object sender, IByteEventArgs e)
{
Console.WriteLine("Value: " + ByteHelper.HexString(e.Value));
}
Value: 0304
- TagLengthValueFrameDecoder 标签、数据长度、数据 - 数据帧解码器
数据格式：
/// <summary>
/// 构造函数
/// </summary>
/// <param name="tagLength">标签长度</param>
/// <param name="valueLengthType">数据长度类型</param>
/// <param name="valueIsLittleEndian">数据长度字节顺序</param>
/// <param name="isFullLength">数据长度是否包含标签、数据长度的长度，false为仅数据长度</param>
/// <param name="maxFrameLength">最大数据长度，仅判断数据长度</param>
public TagLengthValueFrameDecoder(int tagLength, ValueLengthType valueLengthType, bool valueIsLittleEndian = true, bool isFullLength = false, int maxFrameLength = 0)
bts = new byte[] { 0xAA, 2, 3, 4 };
var decoder6 = new TagLengthValueFrameDecoder(1, ValueLengthType.Byte);
decoder6.OnDecoder += TagLengthValueFrameDecoder_OnDecoder;
decoder6.Decode(bts);
private static void TagLengthValueFrameDecoder_OnDecoder(object sender, IByteEventArgs e)
{
var args = (TagLengthValueFrameDataEventArgs)e;
Console.WriteLine("Tag: " + ByteHelper.HexString(args.Tag) + ", Value: " + ByteHelper.HexString(args.Value));
}
Tag: AA, Value: 0304
- NMEA0183FrameDecoder NMEA0183 - 数据帧解码器
数据格式：
var decoder = new NMEA0183FrameDecoder();
decoder.OnDecoder += NMEA0183Decoder_OnDecoder;
decoder.Decode("4,19.7,M,,,,0000*1F$GPGGA,092204.999,4250.5589,S,147");
decoder.Decode("18.5084,E,1,04,24.4,19.7,M,,,,0000*1F$GPGSA,A,3,01,20,");
decoder.Decode("19,13,,,,,,,,,40.4,24.4,32.2*0A$GPGSV,3,1,10,20,78,331,45,01,59,235,47,22,41,");
decoder.Decode("069,,13,32,252,45*70$GPVTG,092204.999,42");
public static void NMEA0183Decoder_OnDecoder(object sender, IStringEventArgs e)
{
Console.WriteLine(e.Value);
}
$GPGGA,092204.999,4250.5589,S,14718.5084,E,1,04,24.4,19.7,M,,,,0000*1F
$GPGSA,A,3,01,20,19,13,,,,,,,,,40.4,24.4,32.2*0A
$GPGSV,3,1,10,20,78,331,45,01,59,235,47,22,41,069,,13,32,252,45*70
- LineBasedFrameDecoder 基于换行符 - 数据帧解码器
数据格式：
var decoder = new LineBasedFrameDecoder();
decoder.OnDecoder += NMEA0183Decoder_OnDecoder;
decoder.Decode("*AA" + '\r' + '\n' + "$GPGGA");
decoder.Decode("*1F" + '\n' + '\r' + "$GPGSA");
decoder.Decode("*0A" + '\r' + "$GPGSV");
decoder.Decode("*70" + '\n' + "$GPVTG");
public static void NMEA0183Decoder_OnDecoder(object sender, IStringEventArgs e)
{
Console.WriteLine(e.Value);
}
*AA
$GPGGA*1F
$GPGSA*0A
$GPGSV*70
参与贡献
- Fork 本仓库
- 新建 Feat_xxx 分支
- 提交代码
- 新建 Pull Request
新的解码器
