protobuf-net 3.2.45

Prefix Reserved
dotnet add package protobuf-net --version 3.2.45                
NuGet\Install-Package protobuf-net -Version 3.2.45                
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="protobuf-net" Version="3.2.45" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add protobuf-net --version 3.2.45                
#r "nuget: protobuf-net, 3.2.45"                
#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.
// Install protobuf-net as a Cake Addin
#addin nuget:?package=protobuf-net&version=3.2.45

// Install protobuf-net as a Cake Tool
#tool nuget:?package=protobuf-net&version=3.2.45                

<img src="https://protogen.marcgravell.com/images/protobuf-net.svg" alt="protobuf-net logo" width="45" height="45"> protobuf-net

protobuf-net is a contract based serializer for .NET code, that happens to write data in the "protocol buffers" serialization format engineered by Google. The API, however, is very different to Google's, and follows typical .NET patterns (it is broadly comparable, in usage, to XmlSerializer, DataContractSerializer, etc). It should work for most .NET languages that write standard types and can use attributes.

Build status

Release Notes

v3 is here!

Change history and pending changes are here.


Supported Runtimes

  • .NET 6.0+ (.NET 5 etc will use .NET Standard 2.1)
  • .NET Standard 2.0, 2.1
  • .NET Framework 4.6.2+

Build tools

Build tools to help you use protobuf-net correctly are available via protobuf-net.BuildTools

Runtime Installation

All stable and some pre-release packages are available on NuGet. CI Builds are available via MyGet (feed URL: https://www.myget.org/F/protobuf-net/api/v3/index.json ).

You can use the following command in the Package Manager Console:

Install-Package protobuf-net
Package NuGet Stable NuGet Pre-release Downloads MyGet
protobuf-net protobuf-net protobuf-net protobuf-net protobuf-net MyGet

Basic usage

1 First Decorate your classes

[ProtoContract]
class Person {
    [ProtoMember(1)]
    public int Id {get;set;}
    [ProtoMember(2)]
    public string Name {get;set;}
    [ProtoMember(3)]
    public Address Address {get;set;}
}
[ProtoContract]
class Address {
    [ProtoMember(1)]
    public string Line1 {get;set;}
    [ProtoMember(2)]
    public string Line2 {get;set;}
}

Note that unlike XmlSerializer, the member-names are not encoded in the data - instead, you must pick an integer to identify each member. Additionally, to show intent it is necessary to show that we intend this type to be serialized (i.e. that it is a data contract).

2 Serialize your data

This writes a 32 byte file to "person.bin" :

var person = new Person {
    Id = 12345, Name = "Fred",
    Address = new Address {
        Line1 = "Flat 1",
        Line2 = "The Meadows"
    }
};
using (var file = File.Create("person.bin")) {
    Serializer.Serialize(file, person);
}

3 Deserialize your data

This reads the data back from "person.bin" :

Person newPerson;
using (var file = File.OpenRead("person.bin")) {
    newPerson = Serializer.Deserialize<Person>(file);
}

Notes

Notes for Identifiers
  • they must be positive integers (for best portability, they should be <= 536870911 and not in the range 19000-19999)
  • they must be unique within a single type but the same numbers can be re-used in sub-types if inheritance is enabled
  • the identifiers must not conflict with any inheritance identifiers (discussed later)
  • lower numbers take less space - don't start at 100,000,000
  • the identifier is important; you can change the member-name, or shift it between a property and a field, but changing the identifier changes the data

Advanced subjects

Inheritance

Inheritance must be explicitly declared, in a similar way that it must for XmlSerializer and DataContractSerializer. This is done via [ProtoInclude(...)] on each type with known sub-types:

[ProtoContract]
[ProtoInclude(7, typeof(SomeDerivedType))]
class SomeBaseType {...}

[ProtoContract]
class SomeDerivedType {...}

There is no special significance in the 7 above; it is an integer key, just like every [ProtoMember(...)]. It must be unique in terms of SomeBaseType (no other [ProtoInclude(...)] or [ProtoMember(...)] in SomeBaseType can use 7), but does not need to be unique globally.

.proto file

As an alternative to writing your classes and decorating them, You can generate your types from a .proto schema using protogen; the protogen tool is available as a zip from that location, or as a "global tool" (multi-platform).

Alternative to attributes

In v2+, everything that can be done with attributes can also be configured at runtime via RuntimeTypeModel. The Serializer.* methods are basically just shortcuts to RuntimeTypeModel.Default., so to manipulate the behaviour of Serializer., you must configure RuntimeTypeModel.Default.

Support

I try to be responsive to Stack Overflow questions in the protobuf-net tag, issues logged on GitHub, email, etc. I don't currently offer a paid support channel. If I've helped you, feel free to buy me a coffee or see the "Sponsor" link at the top of the GitHub page.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 is compatible.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (879)

Showing the top 5 NuGet packages that depend on protobuf-net:

Package Downloads
App.Metrics.Formatters.Prometheus

App Metrics Formatting, formatting metrics data to Prometheus formats.

protobuf-net.Grpc

Package Description

EventStore.Client

The legacy TCP client API for Event Store. Get the open source or commercial versions of Event Store server from https://eventstore.com/

ProtoBufJsonConverter

Convert a protobuf message to a JSON string or object (and back) using the proto definition file.

Unipluss.Sign.Client

Client library to communication with Signere.no REST API. The library contains relevant model classes and a client class with methods to access all resources provided in the Signere.no API. The client class itself is implemented from an interface to make it easily testable. All explicit communication with the API is handled internally and translated to POCO objects. The client methods require certain fields from Signere.no user credentials in order to work properly. To create a user account and obtain these credentials, please visit signere.no . Also, check out the REST API documentation at Https://api.signere.no for further details about the resources that can be accessed through this library.

GitHub repositories (176)

Showing the top 5 popular GitHub repositories that depend on protobuf-net:

Repository Stars
microsoft/semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
aspnetboilerplate/aspnetboilerplate
ASP.NET Boilerplate - Web Application Framework
dotnet/orleans
Cloud Native application framework for .NET
QuantConnect/Lean
Lean Algorithmic Trading Engine by QuantConnect (Python, C#)
JosefNemec/Playnite
Video game library manager with support for wide range of 3rd party libraries and game emulation support, providing one unified interface for your games.
Version Downloads Last updated
3.2.45 229,270 10/23/2024
3.2.30 8,238,772 9/27/2023
3.2.26 3,403,577 5/25/2023
3.2.16 1,876,252 3/17/2023
3.2.12 422,746 3/4/2023
3.2.8 75,817 2/27/2023
3.2.0 139,785 2/20/2023
3.1.33 2,519,783 1/30/2023
3.1.26 1,449,581 12/16/2022
3.1.25 1,590,091 11/9/2022
3.1.22 1,283,234 9/21/2022
3.1.17 2,678,379 6/26/2022
3.1.4 2,015,200 5/10/2022
3.1.0 613,443 4/22/2022
3.0.131 59,958 4/22/2022
3.0.101 11,505,447 3/19/2021
3.0.73 3,828,206 12/2/2020
3.0.72 7,979 12/2/2020
3.0.62 283,196 11/13/2020
3.0.52 1,491,454 10/3/2020
3.0.29 2,682,773 7/8/2020
3.0.27 56,844 7/6/2020
3.0.24 16,790 7/6/2020
3.0.21 7,888 7/5/2020
3.0.18 6,110 7/5/2020
3.0.13 474,479 7/2/2020
3.0.2 197,277 6/24/2020
3.0.0 174,479 6/9/2020
2.4.8 3,696,104 1/9/2023
2.4.7 282,652 4/22/2022
2.4.6 12,226,631 1/28/2020
2.4.4 3,896,112 10/29/2019
2.4.1 648,802 10/9/2019
2.4.0 33,035,042 8/30/2018
2.3.17 685,857 8/3/2018
2.3.16 19,004 8/2/2018
2.3.15 134,819 7/30/2018
2.3.14 56,229 7/24/2018
2.3.14-alpha1 10,390 6/27/2018
2.3.13 934,281 6/19/2018
2.3.7 3,312,710 2/15/2018
2.3.6 529,839 2/1/2018
2.3.5 185,064 1/25/2018
2.3.4 3,282,145 1/19/2018
2.3.3 888,756 12/4/2017
2.3.2 4,180,779 8/4/2017
2.3.1 76,584 7/30/2017
2.3.0 201,674 7/13/2017
2.3.0-gamma 2,716 7/12/2017
2.2.1 752,264 5/27/2017
2.1.0 6,834,361 7/8/2016
2.1.0-alpha-5 3,203 7/7/2016
2.1.0-alpha-4 2,974 7/6/2016
2.1.0-alpha-3 2,795 7/6/2016
2.1.0-alpha-1 49,473 11/22/2015
2.0.0.668 9,593,985 9/30/2013
2.0.0.666 26,774 9/9/2013
2.0.0.664 6,052 9/3/2013
2.0.0.663 3,696 9/2/2013
2.0.0.640 255,550 5/29/2013
2.0.0.638 6,388 5/28/2013
2.0.0.621 118,666 1/16/2013
2.0.0.619 4,751 1/11/2013
2.0.0.614 11,188 12/31/2012
2.0.0.612 12,376 12/10/2012
2.0.0.611 6,958 12/5/2012
2.0.0.602 39,946 11/13/2012
2.0.0.601 18,990 11/6/2012
2.0.0.480 1,317,704 12/11/2011
1.0.0.280 315,647 4/14/2011