LightProto 1.0.0

LightProto 🚀

A high‑performance, Native AOT–friendly, production ready Protocol Buffers implementation for C#/.NET, powered by source generators.

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
• AOT-friendly by design, No IL warnings
• minimal C# 9.0 requirement for broader compatibility (including Unity)
• No third-party dependencies
• protobuf-net–style Serializer API and familiar attributes
• Performance is about 20%-50% better than protobuf-net, see benchmarks below
• Target frameworks: netstandard2.0, net8.0, net9.0, net10.0
• Stream and IBufferWriter<byte> serialization or ToByteArray
• ReadOnlySpan<byte>/ReadOnlySequence<byte>/Stream deserialization

Rich built-in type support

• .NET primitives (byte, int, bool, char, double, etc.)
• string, decimal, Half, Int128, UInt128, Guid, Rune, BigInteger
• TimeSpan, DateTime, DateTimeOffset, TimeOnly, DateOnly, TimeZoneInfo
• Complex, Plane, Quaternion, Matrix3x2, Matrix4x4, Vector2, Vector3, Vector4
• Uri, Version, StringBuilder, BitArray, CultureInfo
• Nullable<>, Lazy<>
• T[], List<>, LinkedList<>, Queue<>, Stack<>, HashSet<>, SortedSet<>
• Dictionary<,>, SortedList<,>, SortedDictionary<,>, ReadOnlyDictionary<,>
• Collection<>, ReadOnlyCollection<>, ObservableCollection<>, ReadOnlyObservableCollection<>
• IEnumerable<>, ICollection<>, IList<>, IReadOnlyCollection<>, IReadOnlyList<>, ISet<>
• IDictionary<,>, IReadOnlyDictionary<,>
• ConcurrentBag<>, ConcurrentQueue<>, ConcurrentStack<>, ConcurrentDictionary<,>, BlockingCollection<>
• ImmutableList<>, ImmutableArray<>, ImmutableHashSet<>, ImmutableDictionary<,>

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.

Serialization APIs

protobuf-net: Serializer.Serialize<T>(...) and Serializer.Deserialize<T>(...)

LightProto:

• Generic-constrained APIs: Serializer.Serialize<T>(...) and Serializer.Deserialize<T>(...) require that T must implement IProtoParser<T> (i.e., a generated message type);
• Explicitly passing IProtoReader/Writer APIs: Serializer.Serialize<T>(..., IProtoWriter<T>) and Serializer.Deserialize<T>(..., IProtoReader<T>) for types without IProtoParser<T> implementation (e.g., primitive types).
• Non-Generic-constrained APIs: Serializer.SerializeDynamically<T>(...) and Serializer.DeserializeDynamically<T>(...) resolve IProtoReader/Writer at runtime (not AOT-safe for generic container shapes). They only work in AOT when T is a [ProtoContract] marked type or a primitive/known built-in type; using generic container shapes like Nullable<>, Lazy<>, List<>, Dictionary<,> etc. will fail at runtime on AOT due to missing type metadata.

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.GetCollectionWriter());// extension method
ArrayBufferWriter<byte> writer = new ArrayBufferWriter<byte>();
LightProto.Serializer.Serialize(writer, list,Int32ProtoParser.Writer.GetCollectionWriter()); // pass collection writer
LightProto.Serializer.SerializeDynamically<List<int>>(writer, list); // dynamic API, not AOT-safe approach.
List<int> arr2=LightProto.Serializer.Deserialize(bytes,Int32ProtoParser.Reader.GetListReader()); // pass element reader
List<int> arr3=LightProto.Serializer.DeserializeDynamically<List<int>>(bytes); // dynamic API, not AOT-safe approach.

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

If you don't need AOT support, you can use dynamic APIs Serializer.SerializeDynamically<T> and Serializer.DeserializeDynamically<T> without passing ProtoReader/Writer.

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.

Unity Support 🎮

LightProto supports C# 9, making it compatible with Unity projects targeting .NET Standard 2.0. You can use LightProto in Unity by following the same installation and usage instructions as for other .NET projects.

IL2CPP builds are supported since LightProto is AOT-friendly.

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.

Working with .proto files 📄

LightProto doesn’t ship a .proto → C# generator for now. 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.

If you need a dedicated .proto → C# generator, please vote this issue.

Contributing 🤝

Contributions are welcome! Please see CONTRIBUTING for detailed contribution guidelines.

ARCHITECTURE.md describes the internal design and structure of LightProto, which may be helpful for contributors.

License 📄

MIT License — see LICENSE for details.