Dameng.Protobuf 0.3.4

Dameng.Protobuf

A source generator version of Protobuf-net with full NativeAOT support. This library provides the same behavior as Protobuf-net but uses compile-time source generation instead of runtime reflection, making it perfect for ahead-of-time compilation scenarios.

Overview

Dameng.Protobuf is designed as a drop-in replacement for Protobuf-net when you need NativeAOT compatibility. It enables generic protobuf serialization and deserialization by automatically generating implementations of IProtoParser<T>, IProtoReader<T>, and IProtoWriter<T>;

Key Differences from Protobuf-net:

• ✅ Full NativeAOT Support - Uses source generation instead of reflection
• ✅ Compile-time Code Generation - Zero runtime overhead
• ✅ Same API Surface - Familiar interface for Protobuf-net users

⚠️ Development Status

This project is under active development and may introduce breaking changes.

• Current version: Alpha/Preview
• API stability: Not guaranteed until v1.0
• Use in production: At your own risk
• Breaking changes: Expected in minor versions until stable release

Features

• 🔄 Protobuf-net Compatibility: Same serialization behavior and API patterns
• ⚡ Source Generator: Automatically implements interfaces for all protobuf classes
• 🎯 Zero Runtime Overhead: All code generation happens at compile time
• 🚀 NativeAOT Ready: Full support for ahead-of-time compilation scenarios
• 📦 Easy Integration: Just add the NuGet package and configure your protobuf files
• 🔧 Generic Programming: Write type-safe generic methods for protobuf operations
• 🏗️ Build-time Safety: Compile-time errors instead of runtime failures

Installation

Install the package from NuGet:

dotnet add package Dameng.Protobuf

Quick Start

1. Configure your ProtoContracts

using Dameng.Protobuf;
[ProtoContract]
public partial class MyRequest 
{
    [ProtoMember(1)]
    public int RequestId { get; set; }    
    [ProtoMember(2)]
    public string Payload { get; set; }
}

Migration from Protobuf-net

Why Migrate?

Protobuf-net limitations with NativeAOT:

• Heavy reflection usage causes issues with AOT compilation
• Runtime code generation not supported in NativeAOT
• Limited trimming support
• Performance overhead from reflection

Dameng.Protobuf advantages:

• ✅ Full NativeAOT compatibility
• ✅ Compile-time code generation
• ✅ No reflection at runtime
• ✅ Better trimming support
• ✅ Predictable performance

Step-by-Step Migration Guide

1. Replace Package References

<PackageReference Include="protobuf-net" Version="x.x.x"/>

        
<PackageReference Include="Dameng.Protobuf" Version="x.x.x"/>

2. Convert Data Models

Change the namespace from Protobuf to Dameng.Protobuf and ensure your classes implement the required interfaces.

-using ProtoBuf;
+using Dameng.Protobuf;
[ProtoContract]
-public class Person
+public partial class Person
{
    [ProtoMember(1)]
    public string Name { get; set; }
    
    [ProtoMember(2)]  
    public int Age { get; set; }
}

4. Update Serialization Code

-using ProtoBuf;
+using Dameng.Protobuf;
// Serialization
var stream = new MemoryStream();
Serializer.Serialize(stream, myObject);
byte[] data = stream.ToArray();

// Deserialization  
var obj = Serializer.Deserialize<MyClass>(new MemoryStream(data));

Migration Compatibility Matrix

How It Works

The source generator automatically implements the required interfaces on all protobuf generated classes:

// Generated by Dameng.Protobuf for each protobuf class
partial class MyRequest : IProtoMessage<MyRequest>
{
    public static IProtoReader<MyRequest> Reader => MyRequestReader.Instance;
    public static IProtoWriter<MyRequest> Writer => MyRequestWriter.Instance;
}

// Generated reader implementation
internal sealed class MyRequestReader : IProtoMessageReader<MyRequest>
{
    public static MyRequestReader Instance { get; } = new();
    
    public MyRequest ParseFrom(ref ReaderContext input)
    {
        // Generated parsing logic...
    }
}

// Generated writer implementation  
internal sealed class MyRequestWriter : IProtoMessageWriter<MyRequest>
{
    public static MyRequestWriter Instance { get; } = new();
    
    public void WriteTo(ref WriterContext output, MyRequest value)
    {
        // Generated writing logic...
    }
    
    public int CalculateSize(MyRequest value)
    {
        // Generated size calculation...
    }
}

Performance & Benchmarks

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

BenchmarkDotNet v0.15.2, 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 9.0.305
[Host]     : .NET 9.0.9 (9.0.925.41916), X64 RyuJIT AVX2
DefaultJob : .NET 9.0.9 (9.0.925.41916), X64 RyuJIT AVX2


| Method                   | Mean     | Error    | StdDev   | Ratio | RatioSD | Allocated | Alloc Ratio |
|------------------------- |---------:|---------:|---------:|------:|--------:|----------:|------------:|
| Serialize_ProtoBuf_net   | 898.8 us | 18.29 us | 52.48 us |  1.61 |    0.11 | 526.41 KB |        1.03 |
| Serialize_GoogleProtoBuf | 651.7 us | 16.70 us | 48.70 us |  1.17 |    0.10 | 512.95 KB |        1.00 |
| Serialize_DamengProtoBuf | 559.3 us | 11.07 us | 21.34 us |  1.00 |    0.05 | 512.95 KB |        1.00 |

BenchmarkDotNet v0.15.2, 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 9.0.305
  [Host]     : .NET 9.0.9 (9.0.925.41916), X64 RyuJIT AVX2
  DefaultJob : .NET 9.0.9 (9.0.925.41916), X64 RyuJIT AVX2
| Method                     | Mean     | Error    | StdDev   | Ratio | RatioSD | Allocated | Alloc Ratio |
|--------------------------- |---------:|---------:|---------:|------:|--------:|----------:|------------:|
| Deserialize_ProtoBuf_net   | 664.9 us | 13.28 us | 28.00 us |  1.53 |    0.08 |    562 KB |        0.88 |
| Deserialize_GoogleProtoBuf | 538.1 us | 10.73 us | 25.70 us |  1.24 |    0.07 |  648.7 KB |        1.02 |
| Deserialize_DamengProtoBuf | 436.0 us |  8.53 us | 14.71 us |  1.00 |    0.05 | 635.15 KB |        1.00 |

Compatibility

• Wire Format: 100% compatible with Google Protocol Buffers
• Interoperability: Works with any protobuf implementation
• Cross-Platform: Supports all .NET 8+ target platforms
• Trimming: Fully compatible with assembly trimming

Getting Help

• Issues: GitHub Issues

Roadmap

Planned Features:

• Reuse object when deserializing
• Advanced serialization options
• Performance optimizations
• More comprehensive documentation
• Stability improvements leading to v1.0

Current Focus:

• API stabilization
• Bug fixes and performance improvements
• NativeAOT optimization
• Better error messages

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Before contributing:

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

Development Setup:

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