Bytes and binary data

suggest change

Files, network packets, hashes, images and encryption keys all show up in C# as raw bytes. The core types for working with them are:

On top of these, .NET has BinaryPrimitives for reading and writing integers in a chosen byte order, BinaryReader / BinaryWriter for streams, Encoding for converting between text and bytes, and MemoryMarshal for reinterpreting bytes as structs.

Examples use C# 14 / .NET 10 and run as top-level programs (dotnet run app.cs).

Creating byte arrays

byte[] zeros = new byte[4];
byte[] header = { 0x89, 0x50, 0x4E, 0x47 };
byte[] fromCollection = [1, 2, 3, 255];
byte[] filled = new byte[3];
Array.Fill(filled, (byte)0xAA);

Console.WriteLine(BitConverter.ToString(zeros));
Console.WriteLine(BitConverter.ToString(header));
Console.WriteLine(Convert.ToHexString(fromCollection));
Console.WriteLine(Convert.ToHexString(filled));

byte b = 250;
b += 10; // wraps around, byte arithmetic is unchecked by default
Console.WriteLine(b);
int sum = header[0] + header[1]; // byte + byte is int
Console.WriteLine(sum);
00-00-00-00
89-50-4E-47
010203FF
AAAAAA
4
217

A few things to note:

For writing byte values in source code, see byte literals and Binary literals.

Slicing, comparing and searching

A range on an array (data[1..4]) copies the elements into a new array. AsSpan gives you a view, and writes through the view change the original array:

byte[] data = [10, 20, 30, 40, 50, 60];

byte[] copy = data[1..4];        // new array
Span<byte> view = data.AsSpan(1, 3); // no copy
view[0] = 99;
Console.WriteLine(string.Join(",", data));
Console.WriteLine(string.Join(",", copy));

ReadOnlySpan<byte> tail = data.AsSpan()[^2..];
Console.WriteLine(Convert.ToHexString(tail));

byte[] a = [1, 2, 3];
byte[] b = [1, 2, 3];
Console.WriteLine(a == b);
Console.WriteLine(a.AsSpan().SequenceEqual(b));

ReadOnlySpan<byte> png = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A];
byte[] file = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 13];
Console.WriteLine(file.AsSpan().StartsWith(png));
Console.WriteLine(file.AsSpan().IndexOf((byte)0x1A));
Console.WriteLine(file.AsSpan().IndexOf("\r\n"u8));
10,99,30,40,50,60
20,30,40
323C
False
True
True
6
4

== on arrays compares references, not contents. To compare contents use SequenceEqual on a span. It's vectorized and much faster than LINQ's Enumerable.SequenceEqual. Span also has IndexOf, LastIndexOf, StartsWith, EndsWith, Contains and IndexOfAny, which work for both single bytes and byte sequences.

When comparing secrets such as MAC tags or password hashes, use CryptographicOperations.FixedTimeEquals instead (shown below), because SequenceEqual returns as soon as it finds a difference and that timing can leak information.

Concatenating, copying and resizing

byte[] part1 = [1, 2];
byte[] part2 = [3, 4, 5];

byte[] joined = [.. part1, .. part2];
Console.WriteLine(Convert.ToHexString(joined));

byte[] dest = new byte[part1.Length + part2.Length];
part1.CopyTo(dest, 0);
part2.AsSpan().CopyTo(dest.AsSpan(part1.Length));
Console.WriteLine(Convert.ToHexString(dest));

byte[] grow = [1, 2, 3];
Array.Resize(ref grow, 5);
Console.WriteLine(Convert.ToHexString(grow));

Array.Reverse(grow);
Console.WriteLine(Convert.ToHexString(grow));
Array.Clear(grow);
Console.WriteLine(Convert.ToHexString(grow));
0102030405
0102030405
0102030000
0000030201
0000000000

The spread syntax [.. a, .. b] is the shortest way to concatenate. Array.Resize allocates a new array and copies into it, so it doesn't actually grow anything in place. If you're appending bytes in a loop, write them to a MemoryStream or an ArrayBufferWriter<byte> instead of resizing over and over.

Text to bytes and back

Text only becomes bytes once you pick an encoding. Encoding.UTF8 is the right default:

using System.Text;

string text = "Zażółć €";
byte[] utf8 = Encoding.UTF8.GetBytes(text);
byte[] utf16 = Encoding.Unicode.GetBytes(text);
byte[] ascii = Encoding.ASCII.GetBytes(text);

Console.WriteLine($"chars: {text.Length}");
Console.WriteLine($"UTF-8:  {utf8.Length} bytes {Convert.ToHexString(utf8)}");
Console.WriteLine($"UTF-16: {utf16.Length} bytes");
Console.WriteLine($"ASCII:  {ascii.Length} bytes, decoded: {Encoding.ASCII.GetString(ascii)}");
Console.WriteLine(Encoding.UTF8.GetString(utf8));

ReadOnlySpan<byte> hello = "hello"u8;
Console.WriteLine($"{hello.Length} {hello[0]}");

byte[] bad = [0x41, 0xFF, 0x42];
Console.WriteLine(Encoding.UTF8.GetString(bad));
var strict = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false, throwOnInvalidBytes: true);
try { strict.GetString(bad); }
catch (DecoderFallbackException e) { Console.WriteLine(e.GetType().Name); }
chars: 8
UTF-8:  14 bytes 5A61C5BCC3B3C582C48720E282AC
UTF-16: 16 bytes
ASCII:  8 bytes, decoded: Za???? ?
Zażółć €
5 104
A�B
DecoderFallbackException

Byte order: BinaryPrimitives and BitConverter

Multi-byte numbers can be stored with the least significant byte first (little-endian, which is what x86 and ARM use) or the most significant byte first (big-endian, also called "network order", used by most file formats and network protocols).

BitConverter always uses the machine's byte order. System.Buffers.Binary.BinaryPrimitives makes you name the byte order, so prefer it for file and wire formats:

using System.Buffers.Binary;

Console.WriteLine(BitConverter.IsLittleEndian);

int value = 0x12345678;
byte[] native = BitConverter.GetBytes(value);
Console.WriteLine(Convert.ToHexString(native));

Span<byte> buf = stackalloc byte[4];
BinaryPrimitives.WriteInt32BigEndian(buf, value);
Console.WriteLine(Convert.ToHexString(buf));
BinaryPrimitives.WriteInt32LittleEndian(buf, value);
Console.WriteLine(Convert.ToHexString(buf));

byte[] packet = [0x00, 0x2A, 0xDE, 0xAD, 0xBE, 0xEF, 0x40, 0x49, 0x0F, 0xDB];
ushort id = BinaryPrimitives.ReadUInt16BigEndian(packet);
uint magic = BinaryPrimitives.ReadUInt32BigEndian(packet.AsSpan(2));
float pi = BinaryPrimitives.ReadSingleBigEndian(packet.AsSpan(6));
Console.WriteLine($"id={id} magic=0x{magic:X8} pi={pi}");

if (!BinaryPrimitives.TryReadInt64LittleEndian(packet.AsSpan(6), out long l))
    Console.WriteLine("not enough bytes for an int64");

uint swapped = BinaryPrimitives.ReverseEndianness(0x12345678u);
Console.WriteLine($"0x{swapped:X8}");
True
78563412
12345678
78563412
id=42 magic=0xDEADBEEF pi=3.1415927
not enough bytes for an int64
0x78563412

BinaryPrimitives has Read, Write, TryRead and TryWrite methods for every integer type plus Half, Single and Double, in both byte orders. They work on spans and don't allocate. The Read methods throw ArgumentOutOfRangeException if the span is too short, while the Try versions return false.

Parsing a binary format with spans

Spans make it easy to walk through a buffer without copying. Read a header, slice off the payload, then move the span forward. This example parses records laid out as 1 byte type, 2 bytes big-endian length, then the payload:

using System.Buffers.Binary;
using System.Text;

// each record: 1 byte type, 2 bytes big-endian length, then payload
byte[] msg = [0x01, 0x00, 0x03, (byte)'b', (byte)'o', (byte)'b',
              0x02, 0x00, 0x04, 0x00, 0x00, 0x01, 0x00];

ReadOnlySpan<byte> rest = msg;
while (rest.Length >= 3)
{
    byte type = rest[0];
    ushort len = BinaryPrimitives.ReadUInt16BigEndian(rest[1..]);
    if (rest.Length < 3 + len)
        throw new InvalidDataException("truncated record");
    ReadOnlySpan<byte> payload = rest.Slice(3, len);
    string desc = type switch
    {
        1 => $"name={Encoding.UTF8.GetString(payload)}",
        2 => $"score={BinaryPrimitives.ReadInt32BigEndian(payload)}",
        _ => $"unknown {Convert.ToHexString(payload)}",
    };
    Console.WriteLine(desc);
    rest = rest[(3 + len)..];
}
name=bob
score=256

Always validate lengths before slicing. Input from a file or socket can't be trusted, and a bad length field should turn into a clean InvalidDataException, not a crash somewhere deeper in the code.

BinaryWriter and BinaryReader

If your data is in a Stream (a file, a network connection, a MemoryStream), BinaryWriter and BinaryReader read and write primitive values in sequence. They always use little-endian:

using System.Text;

var ms = new MemoryStream();
using (var w = new BinaryWriter(ms, Encoding.UTF8, leaveOpen: true))
{
    w.Write((byte)1);          // version
    w.Write(42);               // int32, little-endian
    w.Write(3.5);              // double, 8 bytes
    w.Write("hi");             // length-prefixed UTF-8 string
    w.Write([0xCA, 0xFE]);     // raw bytes
}

byte[] bytes = ms.ToArray();
Console.WriteLine($"{bytes.Length} bytes: {Convert.ToHexString(bytes)}");

ms.Position = 0;
using var r = new BinaryReader(ms);
byte version = r.ReadByte();
int answer = r.ReadInt32();
double d = r.ReadDouble();
string s = r.ReadString();
byte[] raw = r.ReadBytes(2);
Console.WriteLine($"v{version} {answer} {d} {s} {Convert.ToHexString(raw)}");
Console.WriteLine(ms.Position == ms.Length);
18 bytes: 012A0000000000000000000C40026869CAFE
v1 42 3.5 hi CAFE
True

Watch out for the overloads. w.Write(42) writes 4 bytes because 42 is an int, so cast if you want a byte or short. Write(string) writes a 7-bit encoded length prefix (02 here) followed by the UTF-8 bytes. That format only makes sense to another BinaryReader, so for a format someone else defined, write the length and the bytes yourself.

leaveOpen: true keeps the MemoryStream usable after the writer is disposed. More on streams in Using Streams.

Reading and writing binary files

string path = Path.Combine(Path.GetTempPath(), "demo.bin");

byte[] payload = new byte[1000];
Random.Shared.NextBytes(payload);
File.WriteAllBytes(path, payload);

byte[] back = File.ReadAllBytes(path);
Console.WriteLine($"{back.Length} {back.AsSpan().SequenceEqual(payload)}");

// read only the first 4 bytes without loading the whole file
using (var fs = File.OpenRead(path))
{
    Span<byte> head = stackalloc byte[4];
    fs.ReadExactly(head);
    Console.WriteLine(Convert.ToHexString(head) == Convert.ToHexString(payload.AsSpan(0, 4)));
}

await File.AppendAllBytesAsync(path, [1, 2, 3]);
Console.WriteLine(new FileInfo(path).Length);
File.Delete(path);
1000 True
True
1003

File.ReadAllBytes is fine for small files. For large ones, open a FileStream and read in chunks. Note that Stream.Read may return fewer bytes than you asked for. Use ReadExactly (.NET 7+) when you need an exact count. It loops for you and throws EndOfStreamException if the data runs out. File.AppendAllBytes and AppendAllBytesAsync are new in .NET 9.

Reinterpreting bytes as structs

MemoryMarshal can copy a struct to bytes and back, or view a byte span as a span of another primitive type, without parsing field by field:

using System.Runtime.InteropServices;

var hdr = new Header { Magic = 0x46464952, Size = 1234, Channels = 2, Bits = 16 };
Console.WriteLine(Marshal.SizeOf<Header>());

byte[] buf = new byte[Marshal.SizeOf<Header>()];
MemoryMarshal.Write(buf, in hdr);
Console.WriteLine(Convert.ToHexString(buf));

Header parsed = MemoryMarshal.Read<Header>(buf);
Console.WriteLine($"size={parsed.Size} channels={parsed.Channels} bits={parsed.Bits}");

ReadOnlySpan<byte> raw = [1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0];
ReadOnlySpan<int> ints = MemoryMarshal.Cast<byte, int>(raw);
Console.WriteLine($"{ints.Length} ints: {ints[0]} {ints[1]} {ints[2]}");

[StructLayout(LayoutKind.Sequential, Pack = 1)]
struct Header
{
    public uint Magic;
    public int Size;
    public ushort Channels;
    public ushort Bits;
}
12
52494646D204000002001000
size=1234 channels=2 bits=16
3 ints: 1 2 3

This is fast, but it has caveats:

For pointer-based approaches see Pointers and Unsafe Code.

Working with individual bits

Use the bitwise operators &, |, ^, ~, << and >> to pack flags or small fields into bytes. System.Numerics.BitOperations provides fast (often single-instruction) helpers:

using System.Numerics;

byte flags = 0b0000_0101;
bool bit2 = (flags & (1 << 2)) != 0;
flags |= 1 << 7;                 // set bit 7
flags &= unchecked((byte)~(1 << 0)); // clear bit 0
flags ^= 1 << 1;                 // toggle bit 1
Console.WriteLine($"{bit2} {Convert.ToString(flags, 2).PadLeft(8, '0')} 0x{flags:X2}");

byte packed = 0xA7;
int high = packed >> 4;
int low = packed & 0x0F;
Console.WriteLine($"high={high} low={low}");

Console.WriteLine(BitOperations.PopCount(0b1011_0110u));
Console.WriteLine(BitOperations.LeadingZeroCount(1u));
Console.WriteLine(BitOperations.TrailingZeroCount(8u));
Console.WriteLine(BitOperations.RotateLeft(0x80000001u, 1));
Console.WriteLine(BitOperations.IsPow2(4096));
Console.WriteLine($"{flags:B8}");
True 10000110 0x86
high=10 low=7
5
31
3
3
True
10000110

~(1 << 0) is a negative int, so turning it into a byte mask requires unchecked. The B format specifier (.NET 8+) prints numbers in binary, so {flags:B8} is a shorter alternative to Convert.ToString(x, 2).PadLeft(...). Shifts are covered in Bit-Shifting Operators.

For a resizable set of bits, System.Collections.BitArray can convert to and from byte arrays:

using System.Collections;

var bits = new BitArray(10);
bits[3] = true;
bits[7] = true;
Console.WriteLine(string.Concat(bits.Cast<bool>().Select(b => b ? '1' : '0')));

byte[] bytes = new byte[2];
bits.CopyTo(bytes, 0);
Console.WriteLine(Convert.ToHexString(bytes));

var fromBytes = new BitArray(new byte[] { 0b0000_0011 });
Console.WriteLine($"{fromBytes.Length} {fromBytes[0]} {fromBytes[1]} {fromBytes[2]}");
0001000100
8800
8 True True False

Bit 0 of BitArray is the least significant bit of the first byte.

Avoiding allocations: stackalloc and ArrayPool

In hot code, allocating a new byte[] for every temporary buffer puts pressure on the garbage collector. For small buffers, use stackalloc. For large ones, rent from ArrayPool<byte>:

using System.Buffers;

byte[] rented = ArrayPool<byte>.Shared.Rent(1000);
try
{
    Console.WriteLine(rented.Length >= 1000);
    Span<byte> work = rented.AsSpan(0, 1000); // only use what you asked for
    work.Fill(0x7F);
    Console.WriteLine(work[999]);
}
finally
{
    ArrayPool<byte>.Shared.Return(rented);
}

Span<byte> small = stackalloc byte[16];
small[0] = 1;
Console.WriteLine(small.Length);
True
127
16

Printing a hex dump

When debugging a binary protocol, a classic hex dump with offsets and printable characters is very useful:

using System.Text;

static string HexDump(ReadOnlySpan<byte> data, int width = 16)
{
    var sb = new StringBuilder();
    for (int off = 0; off < data.Length; off += width)
    {
        var line = data.Slice(off, Math.Min(width, data.Length - off));
        sb.Append($"{off:X8}  ");
        for (int i = 0; i < width; i++)
            sb.Append(i < line.Length ? $"{line[i]:X2} " : "   ");
        sb.Append(' ');
        foreach (byte b in line)
            sb.Append(b is >= 0x20 and < 0x7F ? (char)b : '.');
        sb.AppendLine();
    }
    return sb.ToString();
}

byte[] data = [.. "Hello, binary world!"u8, 0x00, 0x01, 0xFF, 0x7F];
Console.Write(HexDump(data));
00000000  48 65 6C 6C 6F 2C 20 62 69 6E 61 72 79 20 77 6F  Hello, binary wo
00000010  72 6C 64 21 00 01 FF 7F                          rld!....

Hashes, random bytes and hex parsing

A few common one-liners for byte arrays in System.Security.Cryptography and Convert:

using System.Security.Cryptography;

byte[] data = "hello"u8.ToArray();
byte[] sha = SHA256.HashData(data);
Console.WriteLine(Convert.ToHexStringLower(sha));

byte[] key = RandomNumberGenerator.GetBytes(32);
Console.WriteLine(key.Length);

byte[] expected = SHA256.HashData("hello"u8);
Console.WriteLine(CryptographicOperations.FixedTimeEquals(sha, expected));

byte[] parsed = Convert.FromHexString("DEADBEEF");
Console.WriteLine(string.Join(" ", parsed));
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
32
True
222 173 190 239

Use RandomNumberGenerator for keys, tokens and salts. Random.NextBytes is fine for test data but isn't cryptographically secure. Convert.ToHexStringLower was added in .NET 9. For more on hashing see Hash Functions.

Summary

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents