LightProto 0.8.4

LightProto

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

Warnings

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

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

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

.netstandard

In .netstandard targeting platform such as .NET framework, we can't use static virtual members in interface to find ProtoReader/Writer.

So LightProto requires user to specify a ProtoWriter when serializing and a ProtoReader when deserializing.

For [ProtoContract] marked MessageType the ProtoReader/Writer is generated by LightProto, just use MessageType.ProtoReader/Writer.

For primitive types, LightProto has predefined in LightProto.Parser namespace, such as LightProto.Parser.DateTimeParser.

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: You can specify a custom ProtoParserType for MessageType. For example, MessageType is Person, custom ProtoParserType is PersonProtoParser, you can use following attribute to specify a custom ProtoParserType, list as precedence order:

1. member level: [ProtoMember(1,ParserType=typeof(PersonProtoParser))]
2. class level: [ProtoParserTypeMap(typeof(Person), typeof(PersonProtoParser))]
3. module/assembly level: [ProtoParserTypeMap(typeof(Person), typeof(PersonProtoParser))] (messageType and parserType should not be in same assembly, If so, type level attribute is suggested.)
4. type level: [ProtoParserTypeMap(typeof(Person), typeof(PersonProtoParser))]
5. default: LightProto.Parser.PersonProtoParser

The ProtoParserType must implement IProtoParser<MessageType>. The easiest way is defining a SurrogateType with [ProtoContract] and mark [ProtoSurrogateFor<MessageType>].
Example for Person(can be any type):

[ProtoParserType(typeof(PersonProtoParser))] // type level ProtoParser
public class Person
{
 public string Name {get; set;}
 Person(){}
 public static Person FromName(string name) => new Person() { Name = name };
}

[ProtoContract]
[ProtoSurrogateFor<Person>] // mark this to tell source generator generate IProtoParser<Person> instead of `IProtoParser<PersonProtoParser>`
public partial struct PersonProtoParser
{
  [ProtoMember(1)]
  internal string Name { get; set; }    
  public static implicit operator Person(PersonProtoParser parser) //must define implicit conversions for surrogate type
  {
      return Person.FromName(parser.Name)
  }    
  public static implicit operator PersonProtoParser(Person value) //must define implicit conversions for surrogate type
  {
      return new PersonProtoParser() { Name = value.Name };
  }
}
[assembly: ProtoParserTypeMap(typeof(Person), typeof(PersonProtoParser))] // assembly level ProtoParser

[ProtoParserTypeMap(typeof(Person), typeof(PersonProtoParser))] // class level ProtoParser
public class MessageContract
{
  [ProtoMember(1,ParserType=typeof(PersonProtoParser))] //member level ProtoParser
  public Person Person {get; set;}      
}

You can also read/write raw binary data, for example see:DateOnlyProtoParser

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.