What is endianness, and how do you read and write multi-byte binary data correctly in .NET?

1. Picture it in memory

int value = 0x0A0B0C0D;

        lower addresses  ------------------>  higher addresses
LE:     [0D] [0C] [0B] [0A]     (least significant byte first)
BE:     [0A] [0B] [0C] [0D]     (most significant byte first, reads like the hex)

The names come from Gulliver's Travels (which end of an egg to crack). Bit order inside a byte isn't affected; you never see it from C#.

2. Where byte order sneaks in

3. How BinaryPrimitives stays fast

BinaryPrimitives.ReadInt32BigEndian(span) compiles to a 4-byte load and a bswap (x64) or rev (Arm64) instruction when the machine is little-endian, and a plain load when it already matches. There's no loop and no allocation, which is why it's used throughout Kestrel, System.Text.Json and the gRPC libraries.

4. Designing a binary format

• Write the byte order into the specification and the code (WriteInt32BigEndian), never rely on defaults.
• Prefer fixed-width fields or a well-known varint scheme, plus a version field.
• Validate lengths before allocating: a corrupt or malicious length prefix shouldn't trigger a huge allocation.
• Consider whether you need a custom format at all: Protocol Buffers, MessagePack or CBOR handle byte order and versioning for you.

5. GUIDs: the classic surprise

string form:          00112233-4455-6677-8899-AABBCCDDEEFF
ToByteArray():        33 22 11 00 55 44 77 66 88 99 AA BB CC DD EE FF
ToByteArray(true):    00 11 22 33 44 55 66 77 88 99 AA BB CC DD EE FF   (.NET 8+)

Systems that store GUIDs as 16 raw bytes (PostgreSQL uuid, Java, Python) use the big-endian layout. Mixing the layouts gives "the same" GUID different bytes, and lookups fail.

6. Is big-endian hardware still relevant?

Rarely for .NET: IBM s390x (mainframes) is big-endian and has community .NET builds. The real-world reason to care is data formats and protocols, not CPUs.

7. Try it yourself

1. Write 0x12345678 with BitConverter.GetBytes, BinaryWriter and BinaryPrimitives.WriteInt32BigEndian, and print each result in hex.
2. Read the width and height of a PNG file: they're big-endian uint values at byte offsets 16 and 20.
3. Convert a Guid to bytes with and without bigEndian: true and compare them with the string form.
4. Write a length-prefixed message reader with PipeReader or a Stream that rejects lengths over 1 MB.

namespace Endianness;

using System.Buffers.Binary;

public static class Program
{
    public static void Main()
    {
        Console.WriteLine($"This machine is little-endian: {BitConverter.IsLittleEndian}");

        Span<byte> buffer = stackalloc byte[4];

        BinaryPrimitives.WriteInt32BigEndian(buffer, 0x12345678);
        Console.WriteLine(Convert.ToHexString(buffer));      // 12345678

        BinaryPrimitives.WriteInt32LittleEndian(buffer, 0x12345678);
        Console.WriteLine(Convert.ToHexString(buffer));      // 78563412

        // Reading the dimensions from a PNG header (big-endian per the PNG specification)
        byte[] png = File.ReadAllBytes("logo.png");
        uint width = BinaryPrimitives.ReadUInt32BigEndian(png.AsSpan(16, 4));
        uint height = BinaryPrimitives.ReadUInt32BigEndian(png.AsSpan(20, 4));
        Console.WriteLine($"{width} x {height}");

        var id = Guid.Parse("00112233-4455-6677-8899-aabbccddeeff");
        Console.WriteLine(Convert.ToHexString(id.ToByteArray()));                 // 33221100554477668899AABBCCDDEEFF
        Console.WriteLine(Convert.ToHexString(id.ToByteArray(bigEndian: true)));  // 00112233445566778899AABBCCDDEEFF
    }
}

public static class FrameReader
{
    private const int MaxFrameLength = 1024 * 1024;

    /// Reads one big-endian length-prefixed frame from a stream.
    public static async Task<byte[]> ReadFrameAsync(Stream stream, CancellationToken ct)
    {
        byte[] header = new byte[4];
        await stream.ReadExactlyAsync(header, ct);
        int length = BinaryPrimitives.ReadInt32BigEndian(header);
        if (length is < 0 or > MaxFrameLength)
        {
            throw new InvalidDataException($"Frame length {length} is out of range.");
        }
        byte[] payload = new byte[length];
        await stream.ReadExactlyAsync(payload, ct);
        return payload;
    }
}