Bytes and binary data
suggest changeFiles, network packets, hashes, images and encryption keys all show up in C# as raw bytes. The core types for working with them are:
byteis an unsigned 8-bit value (0-255).sbyteis the rarely used signed version.byte[]is a heap-allocated, fixed-size array of bytes. Most APIs take or return one.Span<byte>andReadOnlySpan<byte>are views over contiguous memory (an array, a slice of one, stack memory). Slicing them doesn't copy anything.Memory<byte>is likeSpan<byte>but can be stored in fields and used acrossawait.
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:
new byte[n]is always zero-filled.- Arithmetic on bytes is done as
int.header[0] + header[1]is anint, so assigning it back to abyteneeds a cast. Compound assignment (b += 10) casts for you and wraps silently unless you're in acheckedcontext. See Checked and Unchecked. Convert.ToHexStringandBitConverter.ToStringare the quickest way to print bytes. The Base64 and hex encoding article covers encoding in more detail.
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
string.Lengthcounts UTF-16 code units, not bytes. The UTF-8 size depends on the content (here 8 chars take 14 bytes).Encoding.ASCIIsilently turns anything outside ASCII into?, so you lose data without any error.- By default an invalid byte sequence decodes to the replacement character
U+FFFD(�). If you'd rather get an exception, create aUTF8EncodingwiththrowOnInvalidBytes: true. - The
u8suffix (C# 11) turns a string literal into aReadOnlySpan<byte>of its UTF-8 bytes at compile time, with no allocation. It's handy for protocol constants such as"\r\n"u8or"HTTP/1.1"u8.
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:
- The bytes are in the machine's byte order (little-endian here). For a big-endian format you still need
BinaryPrimitives.ReverseEndiannesson each field. - The struct must contain only unmanaged fields (no strings, arrays or other references).
Pack = 1removes padding so the layout matches the file exactly. MemoryMarshal.Castdoesn't copy, so the result is only valid as long as the source memory is.
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
Rentcan return a larger array than requested, and its contents aren't cleared. Only use the firstnbytes.- Don't use the array after
Return. PassclearArray: truetoReturnif the buffer held secrets. - Keep
stackallocsmall (a few KB at most) and never use it with a size that comes from untrusted input, because a stack overflow kills the whole process.
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
- Use
byte[]to own data andSpan<byte>/ReadOnlySpan<byte>to look at parts of it without copying. - Compare contents with
SequenceEqual, or withCryptographicOperations.FixedTimeEqualsfor secrets. Never use==. - Pick an explicit
Encoding(usually UTF-8) when converting text, and use"..."u8for byte constants. - Use
BinaryPrimitiveswith an explicit byte order for file and network formats.BitConverterandMemoryMarshaluse the machine's byte order, andBinaryReader/BinaryWriteralways use little-endian. - Read from streams with
ReadExactly, validate lengths before slicing, and reuse buffers withArrayPoolorstackallocin hot paths.