LightProto 0.7.1

LightProto

A high‑performance, Native AOT–friendly Protocol Buffers implementation for C#/.NET.

Why LightProto?

protobuf-net is a popular Protocol Buffers implementation in .NET, but some scenarios (especially Native AOT) can be challenging due to runtime reflection and dynamic generation. LightProto addresses this with compile-time code generation and a protobuf-net–style API.

Features

• Source generator–powered serializers/parsers at compile time
• protobuf-net–style Serializer API and familiar attributes
• Target frameworks: netstandard2.0, net8.0, net9.0, net10.0
• Performance is about 20%-50% better than protobuf-net
• AOT-friendly by design
• Stream and IBufferWriter<byte> serialization or ToByteArray
• ReadOnlySpan<byte>/ReadOnlySequence<byte>/Stream deserialization

Performance & Benchmarks

The following benchmarks compare serialization performance between LightProto, protobuf-net, and Google.Protobuf.

You can reproduce these by cloning the repo and running tests/Benchmark.

BenchmarkDotNet v0.15.3, Windows 11 (10.0.26100.4652/24H2/2024Update/HudsonValley)
AMD Ryzen 7 5800X 3.80GHz, 1 CPU, 16 logical and 8 physical cores
.NET SDK 10.0.100-rc.1.25451.107
[Host]    : .NET 8.0.20 (8.0.20, 8.0.2025.41914), X64 RyuJIT x86-64-v3
.NET 10.0 : .NET 10.0.0 (10.0.0-rc.1.25451.107, 10.0.25.45207), X64 RyuJIT x86-64-v3
.NET 8.0  : .NET 8.0.20 (8.0.20, 8.0.2025.41914), X64 RyuJIT x86-64-v3
.NET 9.0  : .NET 9.0.9 (9.0.9, 9.0.925.41916), X64 RyuJIT x86-64-v3

Note: Results vary by hardware, runtime, and data model. Please run the benchmarks on your environment for the most relevant numbers.

Quick Start

Install from NuGet:

dotnet add package LightProto

Define your contracts (partial classes) using LightProto attributes:

using LightProto;

[ProtoContract]
public partial class Person
{
    [ProtoMember(1)]
    public string Name { get; set; } = string.Empty;

    [ProtoMember(2)]
    public int Age { get; set; }
}

var person = new Person { Name = "Alice", Age = 30 };

// Serialize to a byte[]
byte[] bytes = person.ToByteArray();
// person.ToByteArray(Person.ProtoWriter); // use this overload when .netstandard2.0

// Or serialize to a Stream
using var stream = new MemoryStream();
Serializer.Serialize(stream, person);
// Serializer.Serialize(stream, person, Person.ProtoWriter); // use this overload when .netstandard2.0

byte[] data = stream.ToArray();

// Deserialize from byte[] (ReadOnlySpan<byte> overload will be used)
Person fromBytes = Serializer.Deserialize<Person>(bytes);
// Person fromBytes = Serializer.Deserialize<Person>(bytes,Person.ProtoReader); // use this overload when .netstandard2.0

// Or deserialize from Stream
using var input = new MemoryStream(data);
Person fromStream = Serializer.Deserialize<Person>(input);
// Person fromStream = Serializer.Deserialize<Person>(input,Person.ProtoReader); // use this overload when .netstandard2.0

Warnings

This project is under active development and may introduce breaking changes. Use in production at your own risk.

Migration from protobuf-net

Most code migrates by swapping the namespace and marking your types partial.

1. Replace ProtoBuf with LightProto.
2. Mark serializable types as partial.
3. Remove runtime configuration (e.g., RuntimeTypeModel). LightProto generates code at compile time.

Example:

- using ProtoBuf;
+ using LightProto;

[ProtoContract]
- public class Person
+ public partial class Person
{
    [ProtoMember(1)]
    public string Name { get; set; } = string.Empty;

    [ProtoMember(2)]
    public int Age { get; set; }
}

var myObject = new Person { Name = "Alice", Age = 30 };

// Serialization
var stream = new MemoryStream();
Serializer.Serialize(stream, myObject);
byte[] data = stream.ToArray();

// Deserialization
var obj = Serializer.Deserialize<Person>(new ReadOnlySpan<byte>(data));

Common replacements:

• RuntimeTypeModel and runtime surrogates → use compile-time attributes (see Surrogates below).
• Non-partial types → mark as partial to enable generator output.

Need to know

LightProto aims to minimize differences from protobuf-net; notable ones include:

• Partial classes required

  • protobuf-net: partial not required
  • LightProto: mark [ProtoContract] types as partial so the generator can emit code

• Generic Serialize/Deserialize type constraint

  • protobuf-net: Serializer.Serialize<int>(...) and Serializer.Deserialize<int>(...)
  • LightProto: T must implement IProtoParser<T> (i.e., a generated message type); primitives are not supported directly. Use another method which pass IProtoReader/Writer explicitly.

    int a=10;
    ArrayBufferWriter<byte> writer = new ArrayBufferWriter<byte>();
    LightProto.Serializer.Serialize<int>(writer, a,Int32ProtoParser.Writer); // must pass writer
    var bytes = a.ToByteArray(Int32ProtoParser.Writer); // extension method
    int result = LightProto.Serializer.Deserialize<int>(bytes,Int32ProtoParser.Reader); // must pass reader
    

    List<int> list=[1,2,3];
    var bytes = list.ToByteArray(Int32ProtoParser.Writer);// extension method
    ArrayBufferWriter<byte> writer = new ArrayBufferWriter<byte>();
    LightProto.Serializer.Serialize(writer, list,Int32ProtoParser.Writer);// must pass element writer
    List<int> arr2=LightProto.Serializer.Deserialize<List<int>,int>(bytes,Int32ProtoParser.Reader); // must pass element reader
    

• IExtensible

  • protobuf-net: supports IExtensible for dynamic extensions
  • LightProto: IExtensible is defined for compatibility only and has no effect

• Surrogates

  • protobuf-net: can register surrogates via RuntimeTypeModel at runtime

  • LightProto: define at compile time via attributes

    Example for Guid:

    namespace LightProto.Parser; //must defined in this namespace
    [ProtoContract]
    [ProtoSurrogateFor<Guid>]
    public partial struct GuidProtoParser // name must be <OriginalTypeName>ProtoParser
    {
        [ProtoMember(1, DataFormat = DataFormat.FixedSize)]
        internal ulong Low { get; set; }
    
        [ProtoMember(2, DataFormat = DataFormat.FixedSize)]
        internal ulong High { get; set; }
    
        public static implicit operator Guid(GuidProtoParser protoParser) //must define implicit conversions
        {
            Span<byte> bytes = stackalloc byte[16];
            BinaryPrimitives.WriteUInt64LittleEndian(bytes, protoParser.Low);
            BinaryPrimitives.WriteUInt64LittleEndian(bytes.Slice(8), protoParser.High);
            return new Guid(bytes);
        }
    
        public static implicit operator GuidProtoParser(Guid value) //must define implicit conversions
        {
            Span<byte> bytes = stackalloc byte[16];
            value.TryWriteBytes(bytes);
            return new GuidProtoParser()
            {
                Low = BinaryPrimitives.ReadUInt64LittleEndian(bytes),
                High = BinaryPrimitives.ReadUInt64LittleEndian(bytes.Slice(8)),
            };
        }
    }
    

• StringIntern

  • protobuf-net: Use RuntimeTypeModel.Default.StringInterning = true; to enable string interning globally
  • LightProto: [StringIntern] attribute can apply to individual string members/class/module/assembly

• RuntimeTypeModel

  • Not supported; all configuration is static via attributes and generated code

If you encounter different behavior versus protobuf-net, please open an issue.

Working with .proto files

LightProto doesn’t ship a .proto → C# generator. You can generate C# using protobuf-net (or other tools), then adapt the output to LightProto (typically replacing the ProtoBuf namespace with LightProto and marking types partial). If something doesn’t work, please file an issue.

Contributing

Contributions are welcome!

1. Check existing issues and discussions
2. Follow the project’s coding standards
3. Add tests for new functionality
4. Update documentation as needed

Development setup:

git clone https://github.com/dameng324/LightProto.git
cd LightProto
dotnet restore
dotnet build
dotnet test

License

MIT License — see LICENSE for details.