Protocol Buffers library for idiomatic .NET
C# XSLT Protocol Buffer JavaScript Visual Basic ASP Other
Latest commit 4d1c355 Dec 12, 2016 @mgravell committed on GitHub Merge pull request #199 from plangrenay/patch-1
minor change in README.md
Permalink
Failed to load latest commit information.
.nuget Package and deploy: r580 Aug 17, 2012
BasicHttp Before compile, attempt to explore all required types, by requesting … Jun 20, 2010
DAL git-svn-id: http://protobuf-net.googlecode.com/svn/trunk@201 b72047a4… Nov 11, 2008
DataPipeline Code generator: command line options; xslt options; xml/binary/dataco… Oct 27, 2008
DataTableSerializer Initial cut of WinRT changes (may be unstable) Oct 25, 2011
Examples Fix #167; cyclic types should not resolve as list types of themselves… Jul 8, 2016
FX11 Fixing CoreCLR / "unittest": Tests.Dnx Total: 86, Errors: 0, Failed: … Nov 20, 2015
LateLoaded Build kit improved; now builds Nuget and \Package; the latter include… Aug 3, 2012
MetroDto FIX: WinRT enums have an instance field; crazy, yes? Jul 17, 2012
Metro_DevRig FIX: WinRT enums have an instance field; crazy, yes? Jul 17, 2012
MonoDroid_DevRig let MD run the full thing.. Sep 24, 2010
MonoDto let MD run the full thing.. Sep 24, 2010
MonoSerBuilder Implemented: mapped enums; expose pass-thru option on model Sep 22, 2010
Net11_Poco precompile now works for .NET 1.1 Aug 17, 2012
Net11_Runner precompile now works for .NET 1.1 Aug 17, 2012
Net45Dto fix: some incorrect Type vs System.Type, in particular with precompil… Feb 6, 2013
Nuget FIX: ProtoReader not resetting position in Init Sep 30, 2013
Phone8Dto ADD: Phone8 support Nov 1, 2012
Phone8_DevRig Support for BCL immutable collections Sep 8, 2013
PhoneDto Build kit improved; now builds Nuget and \Package; the latter include… Aug 3, 2012
Phone_DevRig FIX: SO11895998 - portable framework shouldn't try using Activator.Cr… Aug 10, 2012
ProtoBufGenerator Added: Byte/SByte May 3, 2010
ProtoGen Merge pull request #2 from kmitrovic/master Nov 3, 2015
QuickStart all.build not builds *all* frameworks (added NET11, CF20, CF35, WINRT) Aug 16, 2012
SO11895998 FIX SO11895998 and SO11892791 Aug 10, 2012
SO11895998_Portable FIX: SO11895998 - portable framework shouldn't try using Activator.Cr… Aug 10, 2012
SampleDto Build kit improved; now builds Nuget and \Package; the latter include… Aug 3, 2012
SignedDto Support for BCL immutable collections Sep 8, 2013
SilverDto Precompile - holy crap! it works! Jul 14, 2012
SilverlightExtended WinRT (runtime only, not fully working library) Jun 20, 2012
SilverlightExtended_HttpHandler provides the core pieces of the web application side of things. Still… Aug 11, 2008
SilverlightExtended_Web provides the core pieces of the web application side of things. Still… Aug 11, 2008
Spikes Better support for "naked enumerables" (IEnumerable<T> instead of ILi… Apr 17, 2013
SqlClr git-svn-id: http://protobuf-net.googlecode.com/svn/trunk@125 b72047a4… Aug 4, 2008
TestWcfClient all.build not builds *all* frameworks (added NET11, CF20, CF35, WINRT) Aug 16, 2012
TestWcfDto Build kit improved; now builds Nuget and \Package; the latter include… Aug 3, 2012
TestWcfServer Detect framework version from the image version; less specific to 1.1 Aug 17, 2012
Tests.Dnx Fix #167; cyclic types should not resolve as list types of themselves… Jul 8, 2016
Tools Precompile: support strong names; support internalvisibleto against t… Jun 20, 2013
VBTestRig Include Extensible on CoreOnly Aug 8, 2012
WcfPerfTest Incomplete attempt to integrate endpoint-behaviour Oct 8, 2009
demo-rpc-client-silverlight WinRT (runtime only, not fully working library) Jun 20, 2012
demo-rpc-server-mvc Callbacks and default values; callbacks now work alongside inheritanc… Apr 9, 2010
precompile.tests Support for BCL immutable collections Sep 8, 2013
precompile FIX: ProtoReader not resetting position in Init Sep 30, 2013
protobuf-net-CF20 Fix for deferred-objects regression Sep 2, 2013
protobuf-net-CF35 Build 662 Sep 2, 2013
protobuf-net-VS9 all.build not builds *all* frameworks (added NET11, CF20, CF35, WINRT) Aug 16, 2012
protobuf-net-mono Snk for CF20/CF35/Mono Mar 2, 2009
protobuf-net.Enyim FIX: Issue356; also minor tweaks / test for Enyim Feb 15, 2013
protobuf-net.Extensions-CF35 all.build not builds *all* frameworks (added NET11, CF20, CF35, WINRT) Aug 16, 2012
protobuf-net.Extensions all.build not builds *all* frameworks (added NET11, CF20, CF35, WINRT) Aug 16, 2012
protobuf-net.unittest More fixups for core-clr release (mostly tooling changes; some behavi… Jul 6, 2016
protobuf-net auto read-only property serialization Oct 11, 2016
protobuf-net_IKVM Build kit improved; now builds Nuget and \Package; the latter include… Aug 3, 2012
protobuf-net_MonoDroid Build kit improved; now builds Nuget and \Package; the latter include… Aug 3, 2012
protobuf-net_Phone7 Optional (opt-in) DateTime.Kind serialization May 26, 2015
protobuf-net_Phone8 Nuget package for phone 8 and netcore Nov 6, 2012
protobuf-net_Portable Support for BCL immutable collections Sep 8, 2013
protobuf-net_Silverlight Support for BCL immutable collections Sep 8, 2013
protobuf-net_WinRT all.build not builds *all* frameworks (added NET11, CF20, CF35, WINRT) Aug 16, 2012
.gitignore Investigating JIT / invalid IL issue re "constrained" use of list API Jul 5, 2016
Info.txt Example for WCF usage in configuration Nov 11, 2009
Licence.txt License: Google's version=>BSD; fixed typo Nov 6, 2008
NuGet.Config Make if compile for rc1 Nov 19, 2015
Proto 2008.sln all.build not builds *all* frameworks (added NET11, CF20, CF35, WINRT) Aug 16, 2012
Proto 2010.sln FIX: SO11895998 - portable framework shouldn't try using Activator.Cr… Aug 10, 2012
Proto 2012.sln Precompile: support strong names; support internalvisibleto against t… Jun 20, 2013
Proto 2013.sln Optional (opt-in) DateTime.Kind serialization May 26, 2015
Proto.sln.cache git-svn-id: http://protobuf-net.googlecode.com/svn/trunk@200 b72047a4… Nov 7, 2008
ProtoBuf.snk git-svn-id: http://protobuf-net.googlecode.com/svn/trunk@3 b72047a4-3… Jul 17, 2008
README.md Update README.md Dec 12, 2016
StartHere.txt Sockets (simple data messaging; not RPC) Sep 25, 2008
What Files Do I Need.txt all.build not builds *all* frameworks (added NET11, CF20, CF35, WINRT) Aug 16, 2012
all.build Deploy 2.0.0.611 Dec 5, 2012
build.bat git-svn-id: http://protobuf-net.googlecode.com/svn/trunk@201 b72047a4… Nov 11, 2008
build_cf20.bat Lots of core fixes; attempt (failed) to use MF; revised build files; … Mar 1, 2010
build_fx11.bat Lots of core fixes; attempt (failed) to use MF; revised build files; … Mar 1, 2010
build_fx20.bat Really ugly hack to the test rig to get some NetDataContractSerialize… Mar 2, 2010
build_gmcs.bat Remove some additional allocations (IPredicate) Sep 3, 2013
build_gmcs_basic.bat Fixup build for iDevice and gmcs; this is a bit hacky, bug suffices f… Mar 30, 2011
build_mcs.bat bytes; fixed for clean build Mar 1, 2010
build_mf30.bat Lots of core fixes; attempt (failed) to use MF; revised build files; … Mar 1, 2010
buildkit20.build git-svn-id: http://protobuf-net.googlecode.com/svn/trunk@201 b72047a4… Nov 11, 2008
buildkit35.build memcached transcoder; interner; allow duplicated enums; general bug f… Jan 28, 2010
buildpack.cmd Additional build scripts May 29, 2013
global.json working through rtm core-clr fun Jul 4, 2016
nugetpush.cmd Add nugetpush.cmd utility cmd Jan 11, 2013
proto_dnx.sln Fix #167; cyclic types should not resolve as list types of themselves… Jul 8, 2016
push.cmd Additional build scripts May 29, 2013

README.md

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.

Supported Runtimes :

  • .net 2.0/3.0/3.5/4.0
  • Compact Framework 2.0/3.5
  • Mono 2.x
  • Silverlight, Windows Phone 7&8
  • Windows 8 apps

Under investigation

  • CoreClr/DNX

install

Nuget : Install-Package protobuf-net

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

Notes on types

supported:

  • custom classes that:
    • are marked as data-contract
    • have a parameterless constructor
    • for Silverlight: are public
  • many common primitives etc
  • single dimension arrays: T[]
  • List / IList
  • Dictionary / IDictionary
  • any type which implements IEnumerable and has an Add(T) method

The code assumes that types will be mutable around the elected members. Accordingly, custom structs are not supported, since they should be immutable.

Advanced subjects

Inheritance

Inheritance must be explicitly declared, in a similar way that if 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 and serializer from a .proto schema.

This done using the precompiler. Additional guidance can be found here.

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.