CStructSharp reads and writes binary data using a description that looks like a C struct. Give it a layout and some bytes, and it gives you named values. Give it values, and it can create bytes or change a field in existing data. Use it from C#, Node.js, or JavaScript in a browser.
Zero runtime package dependencies. The core .NET library uses only the .NET runtime, keeping integration simple and your application's dependency tree small.
- Open the binary inspector: apply a layout to one of your own files in the browser, no installation.
- Try the browser lesson: no installation.
- Use C#: create a console app.
- Use JavaScript and WASM: install the npm package for Node.js or browsers.
Install a stable .NET 10 SDK. These commands work in PowerShell or a Unix shell:
dotnet new console -n BinaryHeader -f net10.0
cd BinaryHeader
dotnet add package CStructSharpReplace Program.cs with this complete program, then run dotnet run:
using CStructSharp;
using CStructSharp.Values;
var layout = new CStruct("struct header { uint16 kind; uint32 length; };");
byte[] bytes = { 0x02, 0x00, 0x06, 0x00, 0x00, 0x00 };
StructValue header = layout.Parse(bytes, "header");
Console.WriteLine($"kind = {header.Get<ushort>("kind")}");
Console.WriteLine($"length = {header.Get<uint>("length")}");Output:
kind = 2
length = 6
The layout names the fields. The byte array supplies the data. The result is a StructValue: read a member typed
with header.Get<ushort>("kind"); dynamic field syntax (header.kind) also works on the JIT, at the cost of
compile-time checking. The values:
By default, fields are packed together, numbers use little-endian byte order, and pointers occupy eight bytes. The binary layout basics explain these choices.
The same package ships a source generator. Put the layout on a static partial class and the compiler produces
typed classes, Parse, Serialize, in-place setters, and zero-allocation views for it, with the same values and
the same failures as the runtime reader:
[CStructLayout("struct header { uint16 kind; uint32 length; };")]
public static partial class Wire { }
Wire.Header header = Wire.Parse(bytes); // header.Kind == 2, header.Length == 6
byte[] again = Wire.Serialize(header);Every stream form has an awaitable twin - await layout.ParseAsync(file, "header", cancellationToken: token) reads
the bytes while the thread is free and decodes them with the same reader - and a file of records is foreach
over Wire.Records(bytes) or layout.ParseMany(bytes, "header"), one record per step.
A [CStructMapped] partial class maps a parsed StructValue to your own properties by name, and the analyzer
warns about a path string that does not match the layout it is used with. The
generated code series teaches this
path from the first class to the decision between runtime and generated.
For the background, read how C structs occupy memory and
memory addresses and stored data.
See reading values for managed result types and the
JavaScript API for browser results.
Try changing 0x02 to 0x03: kind becomes 3.
Turn a binary format into an executable specification. CStructSharp combines familiar C struct syntax with portable layout rules, giving you one definition for decoding records, generating bytes, inspecting offsets, and updating individual fields. Load definitions at runtime and use the same format description from C#, Node.js, or a browser to build protocol tools, file inspectors, and binary editors.
- Model rich binary data. Compose nested structs, overlapping union views, enums with explicit integer storage,
and reusable typedefaliases. Represent values with fixed-width integers, IEEE-754 floats, booleans, bitfields, fixed character buffers, and terminated ASCII, UTF-8, or UTF-16 strings.
- Let the data determine the shape. Use arithmetic and bitwise expressions, #defineconstants, earlier fields, and caller-supplied variables to size one-dimensional arrays. Select conditional fields withif/elseorswitch. Describe count-prefixed payloads, fixed multidimensional tables, and arrays of structured records directly in the definition.
- Control the bytes precisely. Mix little- and big-endian primitives in one record with <and>suffixes. Choose packed or aligned layout, refine alignment with@align(N), reserve bits with unnamed bitfields, and assert expected field offsets with@N. Type widths follow portable rules, and pointer width is configured explicitly, so the format's interpretation stays independent of the host process.
- Navigate beyond sequential records. Describe stored pointers, pointer arrays, and multiple levels of
indirection. Read targets using absolute or relative addressing, or inspect stored addresses without following
them. Select nested values with paths such as packet.samples[2].valueorroot.ptr.value.
- Generate the code. Put a layout on a [CStructLayout]class and the source generator in the same package writes typed classes,Parse/Serialize/Write,readonly ref structviews that allocate nothing, typed in-place setters, and size and offset constants at build time - the same parser, the same placement, and the same failure texts as the runtime, checked by a parity suite over every fixture.[CStructMapped]generates the mapping into your own classes, with no reflection, so trimmed and Native AOT publishes need no conventions.
- Streams and pipelines. ParseAsync,WriteAsync, andUpdateAsyncread and write withReadAsync/WriteAsyncand aCancellationTokenthat is checked at every boundary;ReadOnlySequence<byte>input reads aPipeReader's buffer in place;ParseManyand the generatedRecordswalk one record after another lazily, andTryParse,TryGet, andGetOrDefaultturn expected failures into values instead of exceptions - see async reads, cancellation, and pipelines.
- Analyze memory images. CStructSharp.Memoryadds unsigned address spaces, mapped regions, BTF/ISF type import, bounded traversal, and offline patches, with the same zero-dependency runtime; see the memory-analysis guide and the runnable synthetic consumer.
Prepare a layout once and reuse it to read StructValue results or C# classes, write new records, and update
selected fields in existing data. The definition keeps the format's structure and byte-level rules together as your
tools grow from a single header parser into a complete format explorer. The library is trim-safe and Native AOT
compatible; see trimming and Native AOT
for what a published program contains (and why dynamic stays on the JIT).
Start with the language tutorial, explore the language reference, or consult differences from C when adapting an existing header.
Read large files, buffers, and streamed binary input with automatic paging and worker execution. The
large-data guide shows how to pass
File, Blob, byte views, fetch responses, and Node streams directly to parse or parseWithDebug.
The npm package includes the prebuilt WebAssembly runtime and TypeScript declarations:
npm install cstructsharpSave this as example.mjs and run node example.mjs with Node.js 22.14 or later:
import { parse } from "cstructsharp";
const result = await parse(
"struct header { uint16 kind; uint32 length; };",
new Uint8Array([2, 0, 6, 0, 0, 0]),
{ root: "header" },
);
if (!result.success) throw new Error(result.error.message);
console.log(result.data.kind); // 2parse returns the values; parseWithDebug additionally lists each field's byte range for a hex viewer. Node
loads the installed runtime from disk; no .NET SDK or server is needed. Browser applications use the same API
with the cstructsharp/vite plugin or an explicit static-asset directory. See the
npm package README for complete setup, write/update examples, and
supported hosts.
Download cstructsharp-wasm-v<VERSION>.zip from GitHub Releases.
Extract the complete archive. With Node.js installed, run node serve.mjs in that directory and open
http://127.0.0.1:8080/starter/. The included page reads, writes, and updates the same header.
Browser users do not need .NET installed. Keep the runtime files together and serve them over HTTP(S). The browser guide explains the files, JavaScript API, result conversion, and common loading errors.
- Follow the learning path
- Find an executable recipe
- Learn the layout language
- Look up the C# API
- Read release notes
CStructSharp follows semantic versioning and is at major version 0: a minor release (0.5 → 0.6) may change the
public API, the layout language, or the JavaScript contract, and the changelog
marks every such change Breaking with the migration; a patch release never does. Pin 0.5.* in a project that
must not absorb breaking changes. The managed API baseline (contracts/api/managed-rc1) and the browser contract
(contracts/api/browser-rc1, contractVersion 8) are reviewed together with each change; a breaking JavaScript
change increments the contract version.
The NuGet package targets .NET 8 (LTS) and .NET 10 (LTS); a target is dropped in the first minor release after
Microsoft ends its support. The npm package supports the Node.js releases that are active or in maintenance
(currently 22.14 and later) and evergreen Chromium, Firefox, and WebKit browsers. Release assets describe published
versions; the repository's src/CStructSharp/CStructSharp.csproj records the development version.
Package consumers do not need to clone or build this repository. Contributors should start with the repository setup guide, then follow build instructions, testing, and contribution guidance. The repository map explains the projects.
CStructSharp uses the MIT License. Report questions and bugs in the issue tracker.