CStructSharp 0.3.2

CStructSharp

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.

Choose your starting point

• 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.

Read your first value in C#

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 CStructSharp

Replace Program.cs with this complete program, then run dotnet run:

using CStructSharp;

var layout = new CStruct("struct header { uint16 kind; uint32 length; };");
byte[] bytes = { 0x02, 0x00, 0x06, 0x00, 0x00, 0x00 };
dynamic header = layout.Parse(bytes.AsSpan(), "header");

Console.WriteLine($"kind = {header.kind}");
Console.WriteLine($"length = {header.length}");

Output:

kind = 2
length = 6

The layout names the fields. The byte array supplies the data. The result contains 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. Try changing 0x02 to 0x03: kind becomes 3.

When to use it

Use CStructSharp to read a documented device message, inspect a file header, or change a fixed field in a binary record. A hand-written BinaryReader may be sufficient for a few fixed fields. A reusable layout description is useful when several operations share a format or the format is supplied at runtime.

The language has its own portable rules. It does not compile C, import arbitrary C headers, discover an unknown format, or automatically match a native compiler's struct layout. Floating-point and boolean fields are currently unsupported. See differences from C before translating a header.

Supported features include integers, structs, unions, enums, arrays, text, bitfields, expressions, and stored pointers. You can read dynamic objects or C# classes, write new bytes, and update a path such as packet.header.length. Advanced APIs support streams, spans, memory, buffer writers, explicit limits, and reuse of a compiled layout.

Use JavaScript in Node.js or a browser

The npm package includes the prebuilt WebAssembly runtime and TypeScript declarations:

npm install cstructsharp

Save this as example.mjs and run node example.mjs with Node.js 22.14 or later:

import { parseWithDebug } from "cstructsharp";

const result = await parseWithDebug(
  "struct header { uint16 kind; uint32 length; };",
  new Uint8Array([2, 0, 6, 0, 0, 0]),
  { rootTypeName: "header" },
);
if (!result.Success) throw new Error(result.Error.Message);
console.log(JSON.parse(result.Data).header.kind); // 2

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. Until the first npm publication, contributors can install the tested .tgz produced by npm run pack:npm in CStructSharpWeb. The release guide covers the first publication.

Use the standalone browser bundle

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.

Continue learning

• Learn step by step
• Find an executable recipe
• Learn the layout language
• Look up the C# API
• Read release notes

The package targets .NET 8 and .NET 10. Release assets describe published versions; the repository's CStructSharp/CStructSharp.csproj records the development version. Historical compatibility snapshots have their own labels and do not identify the latest release.

Work on the project

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.