Excalibur.Dispatch.Serialization.Protobuf 10.0.0-alpha.19

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher.
This is a prerelease version of Excalibur.Dispatch.Serialization.Protobuf. 
dotnet add package Excalibur.Dispatch.Serialization.Protobuf --version 10.0.0-alpha.19
                    


                    

                
NuGet\Install-Package Excalibur.Dispatch.Serialization.Protobuf -Version 10.0.0-alpha.19
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Excalibur.Dispatch.Serialization.Protobuf" Version="10.0.0-alpha.19" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Excalibur.Dispatch.Serialization.Protobuf" Version="10.0.0-alpha.19" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Excalibur.Dispatch.Serialization.Protobuf" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Excalibur.Dispatch.Serialization.Protobuf --version 10.0.0-alpha.19
                    


                    

                
#r "nuget: Excalibur.Dispatch.Serialization.Protobuf, 10.0.0-alpha.19"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Excalibur.Dispatch.Serialization.Protobuf@10.0.0-alpha.19
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Excalibur.Dispatch.Serialization.Protobuf&version=10.0.0-alpha.19&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Excalibur.Dispatch.Serialization.Protobuf&version=10.0.0-alpha.19&prerelease
                    


                            Install as a Cake Tool

Excalibur.Dispatch.Serialization.Protobuf

Opt-in Protocol Buffers serialization support for the Excalibur framework.

Purpose

Provides Protocol Buffers (Protobuf) serialization for:

  • Google Cloud Platform (GCP) interoperability
  • AWS service integration requiring Protobuf
  • High-performance binary protocols
  • External systems using .proto schema definitions

Installation

dotnet add package Excalibur.Dispatch.Serialization.Protobuf

Usage

One call does everything -- DI registration, serializer registry entry, and setting Protobuf as the current serializer:

services.AddProtobufSerializer();

Configure Protobuf Options

services.AddProtobufSerializer(opts =>
{
    // Wire format: Binary (default) or JSON
    opts.WireFormat = ProtobufWireFormat.Binary;
});

Message Definition

Your message types must implement Google.Protobuf.IMessage and have source-generated parsers:

using Google.Protobuf;

// Example: Generated from .proto file
public partial class UserCreatedEvent : IMessage<UserCreatedEvent>
{
    // Source-generated Protobuf code
}

Package Dependencies

  • Google.Protobuf - Protocol Buffers runtime
  • Excalibur.Dispatch.Abstractions - Core contracts only (no Excalibur.Dispatch dependency)

AOT Compatibility

Native AOT compatible with source-generated Protobuf types.

Ensure your .proto files are compiled with protoc to generate C# code, and the generated types will be trim-safe.

Wire Formats

Binary (Default - Recommended)

opts.WireFormat = ProtobufWireFormat.Binary;
  • Compact binary format
  • Binary serialization/deserialization
  • Best for internal/transport use

JSON

opts.WireFormat = ProtobufWireFormat.Json;
  • Human-readable JSON representation
  • Useful for debugging or external API boundaries
  • Slower than binary format

When to Use This Package

Use Protobuf serialization when:

  • Integrating with GCP services (Cloud Pub/Sub, Cloud Functions, etc.)
  • AWS services require Protobuf (EventBridge, Kinesis with Protobuf schema)
  • External systems expose Protobuf schemas (.proto files)
  • You need schema evolution with backward/forward compatibility

Do NOT use Protobuf when:

  • Internal Excalibur.Dispatch messaging (use MemoryPack or JSON)
  • Public HTTP/REST APIs (use System.Text.Json)
  • No Protobuf schema requirements exist

Architecture Notes

Per Excalibur framework requirements:

  1. Excalibur.Dispatch MUST NOT reference this package (the core package stays serializer-neutral)
  2. This package is pay-for-play (no transitive bloat for consumers who do not use it)
  3. System.Text.Json is the default serializer
  4. This package is opt-in only

Performance characteristics

Protobuf produces a compact binary payload and is normally faster to serialize, and smaller on the wire, than JSON. This package carries no current matched-workload measurement of its own, so no latency or throughput figure is published here.

Earlier revisions of this document quoted 100–500 ns/op for binary serialization and figures in the millions of messages per second. Those were never backed by a verified matched workload and must not be used for capacity planning.

To size this for your application, measure complete payload serialization, deserialization and allocation for the API you actually call. Sustained throughput needs its own load measurement; it cannot be derived by taking the reciprocal of a microbenchmark mean.

Schema Evolution

Protobuf supports schema evolution via:

  • Field numbers: Never reuse field numbers
  • Reserved fields: Mark removed fields as reserved
  • Optional fields: Use optional for nullable fields
  • Unknown fields: Preserved if PreserveUnknownFields = true

Example .proto:

syntax = "proto3";

message UserCreatedEvent {
  string user_id = 1;
  string email = 2;
  reserved 3; // Removed field
  // New field with number 4
  string full_name = 4;
}

License

This package is licensed under the same licenses as the Excalibur framework:

  • Excalibur License 1.0
  • GNU Affero General Public License v3.0 or later (AGPL-3.0)
  • Server Side Public License v1.0 (SSPL-1.0)
  • Apache License 2.0

See LICENSE files in project root for details.

Support

For issues, questions, or contributions, visit:

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
10.0.0-alpha.19 0 10/27/2026
10.0.0-alpha.18 51 10/25/2026
10.0.0-alpha.17 57 10/23/2026
10.0.0-alpha.16 58 10/21/2026
10.0.0-alpha.15 57 10/11/2026
10.0.0-alpha.14 56 10/2/2026
10.0.0-alpha.13 59 9/29/2026
10.0.0-alpha.12 68 9/25/2026
10.0.0-alpha.11 73 9/15/2026
10.0.0-alpha.10 81 9/6/2026
10.0.0-alpha.9 76 8/31/2026
10.0.0-alpha.8 91 8/14/2026
10.0.0-alpha.7 83 8/13/2026
10.0.0-alpha.6 91 8/11/2026
10.0.0-alpha.5 76 8/10/2026
10.0.0-alpha.4 87 8/10/2026
3.0.0-alpha.216 90 6/30/2026
3.0.0-alpha.215 82 6/23/2026
3.0.0-alpha.214 99 6/23/2026
3.0.0-alpha.208 82 6/11/2026
Loading failed

Release notes and versioning policy: https://docs.excalibur-dispatch.dev/docs/migration/version-upgrades