C# `BinaryPrimitives` 类详解

C#BinaryPrimitives类详解

System.Buffers.Binary.BinaryPrimitives是 .NET 提供的高性能二进制数据处理工具类，专门用于按指定字节序（大端/小端）读写数值类型，完美适配Span<byte>/ReadOnlySpan<byte>，在网络通信、文件解析、硬件协议交互等场景中极为常用。

一、核心功能与方法分类

它的所有方法都围绕「按字节序读写数值」和「字节序反转」展开，分为以下几类：

1.ReadXXXEndian系列（从字节序列读取数值）

从ReadOnlySpan<byte>中按指定字节序读取基础数值类型，读取失败会直接抛出ArgumentOutOfRangeException（当source长度不足时）。
常见方法示例：

// 读取小端序 int（4 字节）publicstaticintReadInt32LittleEndian(ReadOnlySpan<byte>source);// 读取大端序 ushort（2 字节）publicstaticushortReadUInt16BigEndian(ReadOnlySpan<byte>source);// 读取小端序 float（4 字节）publicstaticfloatReadSingleLittleEndian(ReadOnlySpan<byte>source);// 读取大端序 double（8 字节）publicstaticdoubleReadDoubleBigEndian(ReadOnlySpan<byte>source);

2.TryReadXXXEndian系列（安全读取数值）

和ReadXXXEndian功能完全一致，但不会抛出异常，而是通过返回bool表示读取是否成功，适合不确定数据长度的场景。

// 尝试读取小端序 int，成功返回 true，结果存入 out 参数publicstaticboolTryReadInt32LittleEndian(ReadOnlySpan<byte>source,outintvalue);// 尝试读取大端序 ushortpublicstaticboolTryReadUInt16BigEndian(ReadOnlySpan<byte>source,outushortvalue);

3.TryWriteXXXEndian系列（按指定字节序写入数值）

将数值按指定字节序写入Span<byte>，写入失败返回false（目标destination长度不足时）。

// 将 int 按小端序写入字节序列publicstaticboolTryWriteInt32LittleEndian(Span<byte>destination,intvalue);// 将 ushort 按大端序写入字节序列publicstaticboolTryWriteUInt16BigEndian(Span<byte>destination,ushortvalue);

4.ReverseEndianness系列（字节序反转）

用于批量或单个数值的字节序反转，适配不同数值类型：

// 反转单个 int 的字节序publicstaticintReverseEndianness(intvalue);// 批量反转 Span<int> 中所有元素的字节序publicstaticvoidReverseEndianness(ReadOnlySpan<int>source,Span<int>destination);// 支持 short/long/uint/ulong/Int128 等几乎所有数值类型

二、关键概念：大端 vs 小端

• 小端序存储：0x78 0x56 0x34 0x12
• 大端序存储：0x12 0x34 0x56 0x78

三、完整使用示例代码

以下是一个包含「读写、安全操作、字节序反转」的完整示例，可直接运行：

usingSystem;usingSystem.Buffers.Binary;classBinaryPrimitivesDemo{staticvoidMain(){// --------------------------// 1. 按小端序写入/读取 int// --------------------------Span<byte>buffer=newbyte[4];intoriginalValue=0x12345678;// 写入小端序BinaryPrimitives.WriteInt32LittleEndian(buffer,originalValue);Console.WriteLine("小端序写入后的字节：{0}",BitConverter.ToString(buffer.ToArray()));// 读取小端序intreadLittle=BinaryPrimitives.ReadInt32LittleEndian(buffer);Console.WriteLine("读取的小端序 int：0x{0:X}",readLittle);// --------------------------// 2. 按大端序写入/读取 ushort// --------------------------Span<byte>ushortBuffer=newbyte[2];ushortushortValue=0xAABB;BinaryPrimitives.WriteUInt16BigEndian(ushortBuffer,ushortValue);Console.WriteLine("\n大端序写入后的字节：{0}",BitConverter.ToString(ushortBuffer.ToArray()));ushortreadBig=BinaryPrimitives.ReadUInt16BigEndian(ushortBuffer);Console.WriteLine("读取的大端序 ushort：0x{0:X}",readBig);// --------------------------// 3. TryRead/TryWrite 安全操作// --------------------------Span<byte>smallBuffer=newbyte[3];// 长度不足 4 字节boolwriteSuccess=BinaryPrimitives.TryWriteInt32LittleEndian(smallBuffer,0x1234);Console.WriteLine($"\n向 3 字节缓冲区写入 int 是否成功：{writeSuccess}");// 输出 FalseboolreadSuccess=BinaryPrimitives.TryReadInt32LittleEndian(smallBuffer,outint_);Console.WriteLine($"从 3 字节缓冲区读取 int 是否成功：{readSuccess}");// 输出 False// --------------------------// 4. 字节序反转// --------------------------intbigEndianInt=0x12345678;intreversed=BinaryPrimitives.ReverseEndianness(bigEndianInt);Console.WriteLine($"\n反转字节序：0x{bigEndianInt:X}→ 0x{reversed:X}");// 批量反转数组字节序ReadOnlySpan<int>sourceSpan=newint[]{0x11223344,0x55667788};Span<int>destSpan=newint[2];BinaryPrimitives.ReverseEndianness(sourceSpan,destSpan);Console.WriteLine("批量反转结果：");foreach(varnumindestSpan){Console.WriteLine($"0x{num:X}");}}}

运行输出：

小端序写入后的字节：78-56-34-12 读取的小端序 int：0x12345678 大端序写入后的字节：AA-BB 读取的大端序 ushort：0xAABB 向 3 字节缓冲区写入 int 是否成功：False 从 3 字节缓冲区读取 int 是否成功：False 反转字节序：0x12345678 → 0x78563412 批量反转结果： 0x44332211 0x88776655

四、关键注意事项与最佳实践

1. 性能优势
   BinaryPrimitives直接基于Span操作，无堆分配，比BitConverter更高效，且支持直接指定字节序，无需手动判断BitConverter.IsLittleEndian。
2. 异常处理
   • ReadXXXEndian会在source长度不足时抛出ArgumentOutOfRangeException，适合数据长度有保障的场景。
   • TryReadXXXEndian不抛异常，适合网络流、文件流等数据长度不确定的场景。
3. 数据对齐
   该类不要求内存对齐，可直接处理任意Span<byte>，无需手动处理偏移和对齐问题。
4. 常见场景
   • 网络协议解析（TCP/UDP 数据包按大端序传输）
   • 二进制文件读写（如图片、音视频文件头解析）
   • 硬件交互（串口、CAN 总线数据解析）

五、扩展：和BitConverter的对比

六、半导体/上位机开发场景示例（适配你的工作）

在半导体功率循环测试、串口/网口上位机开发中，经常需要解析硬件返回的二进制数据，以下是一个典型示例：

// 解析功率循环测试设备返回的 8 字节数据帧（大端序）publicstaticvoidParsePowerCycleData(ReadOnlySpan<byte>frame){if(frame.Length<8)thrownewArgumentException("数据帧长度不足");// 读取 2 字节温度（大端序 ushort，单位 0.1℃）ushorttempRaw=BinaryPrimitives.ReadUInt16BigEndian(frame.Slice(0,2));doubletemperature=tempRaw*0.1;// 读取 4 字节电压（大端序 float，单位 V）floatvoltage=BinaryPrimitives.ReadSingleBigEndian(frame.Slice(2,4));// 读取 2 字节电流（小端序 ushort，单位 0.1A）ushortcurrentRaw=BinaryPrimitives.ReadUInt16LittleEndian(frame.Slice(6,2));doublecurrent=currentRaw*0.1;Console.WriteLine($"温度：{temperature:F1}℃，电压：{voltage:F2}V，电流：{current:F1}A");}

如果你需要，我可以帮你写一个结合 C# 串口通信的完整数据解析示例，直接适配半导体测试机的二进制协议场景。