Tuesday 4 August 2015

Protocol Buffers in C#

Installation
Protocol Buffers can be installed via Nuget,
 PM> Install-Package Google.ProtocolBuffers  
Or search for Protocol Buffers, there is also a Protocol buffers lite package that is smaller and does not use relection (better for some lighter platforms like mono). Note: an option must be set in the .proto file to compile the proto for use with the lite package.

Tools
As well as installing the protocol buffers library this will also download the tools required to compile .proto files and generate C# files from them. The tools will be located where the nuget package was installed to.

.proto
A .proto file will be required to generate the required files for usage. This example .proto defines a message called TestMessage with 3 properties. The package is used like a namespace and will also be used to generate the namespace of the classes in C#.
 syntax = "proto2";  
   
 package test_proto;  
   
 message TestMessage  
 {  
   required int32 Id = 1;  
   required string Name = 2;  
   optional string Details = 3;  
 }  
For more information on defining a .proto file see the protocol buffer v2 spec.

Protoc
To compile a .proto file locate protoc.exe in the tools dir and run it with the following parameters.
 protoc -oitem test.proto  
where item is the name of the output file and test.proto the name of the .proto file. This outputs a compiled version of the .proto file.

ProtoGen
The next step is to generate the .cs files that will contain the generated code that can be used to create and serialize the data.
 .\ProtoGen.exe item  
This should generate a .cs file containing everything you need to read/write to the protocol buffers.

Serialization
 var builder = new TestMessage.Builder();  
   
 builder.Id = 2;  
 builder.Name = "Test";  
 builder.Details = "Some Detials";  
   
 var message = builder.Build();  
   
 var bytes = message.ToByteArray();  
You must create a builder as messages are immutable (Each message generates and internal Builder class), a message can be turned back in to a builder easily wit the ToBuilder() method.

Deserialization
 var builder = new TestMessage.Builder();  
 builder.MergeFrom(bytes);  
 var message = builder.Build();  
You could just read the data from the builder if you wish.

Other Methods
message.ToJson() & message.ToXml()
These can be used to visualize the message in other formats.

message.WriteTo(Stream stream)
This is used to write the bytes to a stream.

References
https://developers.google.com/protocol-buffers/
https://developers.google.com/protocol-buffers/docs/reference/proto2-spec
https://github.com/google/protobuf

6 comments: