Skip to main content
Search Documentation & Spec
Type to search all 11 pages

OmniBuf
for C# & .NET.

Managed .NET 8 library on NuGet paired with a Buf code generator. Serialize attributed records, classes, and structs, pass in Google Protobuf messages, or generate partial classes and lazy packet views for in-place field reads and updates.

Add .NET Package
$ dotnet add package OmniBuf

Three ways to use OmniBuf in C#.

All three produce identical wire bytes across .NET 8 and newer runtimes.

Attribute-annotated C# records and classes

[OmniBufMessage] and [OmniBufField] work on mutable classes, value structs, and immutable C# positional records. OmniBufSerializer compiles expression-tree encoders and decoders once per type.

[OmniBufField] C# Record
using OmniBuf;

[OmniBufMessage(TypeName = "SensorSample")]
public sealed record SensorSample(
    [property: OmniBufField(1, Name = "sensor_id")] string SensorId,
    [property: OmniBufField(2, Name = "celsius")] double Celsius,
    [property: OmniBufField(3, Name = "seq")] ulong Seq);

var sample = new SensorSample("rack-42-inlet", 21.75, 1042UL);
byte[] pkt = OmniBufSerializer.Marshal(sample);
SensorSample outSample = OmniBufSerializer.Unmarshal<SensorSample>(pkt);

Standard Google.Protobuf.IMessage types

ASP.NET Core and gRPC projects already generating Google.Protobuf classes pass any IMessage directly to OmniBufProtobuf.Marshal and OmniBufProtobuf.Unmarshal<T>.

Google.Protobuf Bridge
using Omnibuf.Bench;
using OmniBuf;

byte[] pkt = OmniBufProtobuf.Marshal(peer);
PeerUpdate copy = OmniBufProtobuf.Unmarshal<PeerUpdate>(pkt);

Generated partial classes with protoc-gen-omnibuf-cs

Adding protoc-gen-omnibuf-cs to buf.gen.yaml attaches direct Span<byte> encoders and decoders onto generated C# partial classes and emits Opaque* views. Single-field sequence updates complete in ~134 ns.

buf.gen.yaml
version: v2
clean: true
plugins:
  - protoc_builtin: csharp
    out: src/Generated
  - local: protoc-gen-omnibuf-cs
    out: src/Generated
Lint & Generate with Buf
$ buf lint
$ buf generate
Generated Partial Class & Opaque Splice
using Omnibuf.Bench;
using OmniBuf;

byte[] pkt = peer.MarshalOmniBuf();

var view = new OpaquePeerUpdate(pkt);
string city = view.GetLocationCity();

view.Sequence = 9_876_543_211UL;
byte[] updated = view.MarshalOmniBuf();

C# & .NET 8 benchmarks.

11-field PeerUpdate workload on .NET 8.0.29 (RyuJIT) across OmniBuf, Google.Protobuf, MessagePack-CSharp, and System.Text.Json. Shorter bars = Faster.

Full Message Encode Speed

Serializing PeerUpdate into a fresh byte[] on .NET 8 RyuJIT.

OmniBuf (Generated)
1.0x (base) (308 ns)
OmniBuf ([OmniBufField])
1.6x slower (478 ns)
MessagePack-CSharp
2.0x slower (607 ns)
Google.Protobuf
2.1x slower (655 ns)
System.Text.Json
3.6x slower (1,122 ns)
Full Message Decode Speed

Decoding ReadOnlySpan<byte> into a fresh PeerUpdate instance and reading all 11 fields.

OmniBuf (Generated)
1.0x (base) (743 ns)
OmniBuf ([OmniBufField])
1.2x slower (896 ns)
Google.Protobuf
1.2x slower (900 ns)
MessagePack-CSharp
1.7x slower (1,300 ns)
System.Text.Json
4.4x slower (3,279 ns)
Read a Single Nested Field

Reading a nested city string via OpaquePeerUpdate vs full message decode.

OmniBuf (Generated)
1.0x (base) (144 ns)
Google.Protobuf
5.7x slower (820 ns)
MessagePack-CSharp
8.3x slower (1,200 ns)
System.Text.Json
22.0x slower (3,169 ns)
Selective Single-Field Mutation

Checking a nested city string and splicing an updated sequence counter via OpaquePeerUpdate vs full decode and re-encode.

OmniBuf (Generated)
1.0x (base) (365 ns)
Google.Protobuf
4.1x slower (1,499 ns)
MessagePack-CSharp
5.1x slower (1,845 ns)
System.Text.Json
12.0x slower (4,370 ns)
Large Embedded Message Encode

Serializing a 39 KiB packet whose >16 KiB nested sub-messages trigger 2B-to-4B header expansion.

MessagePack-CSharp
1.1x faster (6,186 ns)
OmniBuf (Generated)
1.0x (base) (6,649 ns)
OmniBuf ([OmniBufField])
1.0x slower (6,946 ns)
System.Text.Json
1.4x slower (9,047 ns)
Google.Protobuf
4.0x slower (26,575 ns)
Embedded Message Growth

Growing a nested string field past 16 KiB ahead of 32 trailing Neighbor entries via Opaque splicing vs full decode and re-encode.

OmniBuf (Generated)
1.0x (base) (6,629 ns)
MessagePack-CSharp
1.4x slower (9,000 ns)
Google.Protobuf
2.9x slower (19,480 ns)
System.Text.Json
3.1x slower (20,479 ns)

Benchmark Environment

Hardware & Runtime
CPU: Apple M1 Pro (darwin/arm64)
Runtime: .NET 8.0.29 (RyuJIT Tier-1 PGO)
Command: just bench

Measured on .NET 8.0.29 (Release build with Dynamic PGO warmup) on an Apple M1 Pro Mac. Every benchmark allocates a fresh byte[] on encode and reads all 11 fields on decode, tracking per-operation heap bytes with GC.GetAllocatedBytesForCurrentThread.

Benchmark source lives in src/OmniBuf.Benchmarks/Program.cs, with recorded output in testdata/benchmarks.json.

C# & .NET questions.

Why does protoc-gen-omnibuf-cs pair with protoc_builtin: csharp?

Google.Protobuf generates sealed partial class message types in C#. protoc-gen-omnibuf-cs emits companion partial class files adding MarshalOmniBuf() and ParseOmniBuf(ReadOnlySpan<byte>) directly onto your existing message types alongside standalone Opaque* views.

Why is [OmniBufField] nearly as fast as generated code on .NET 8?

OmniBufSerializer compiles typed System.Linq.Expressions delegates once per type, avoiding per-field reflection and primitive boxing. Under RyuJIT Dynamic PGO, [OmniBufField] decodes within 20% of generated partial methods while still edging out Google.Protobuf.

How does OmniBufBlind inspect schema-less packets?

OmniBufBlind.DecodeBlind(pkt) reads 4-bit wire tags into a dictionary with field_1, field_2, ... keys, or maps Field #0 names when SelfDescribing = true was set on encode.

Example
using OmniBuf;

byte[] pkt = OmniBufSerializer.Marshal(sample, new MarshalOptions { SelfDescribing = true });
string json = OmniBufBlind.DecodeBlindJson(pkt);

Language implementations.

v0.1 Draft Wire Format · GitHub Feedback →
Architecture, Tooling & Wire Specification