c# - Google Protocol buffer getting started

Google protocol buffer is an open-sourced message protocol that has been announced public by Google coporation. 
 
 
you may get glimpse of the CSharp port of the google protocol buffer at this location: protobuf-csharp-port ;
 
 
There are some benefit of using GBP over the xml :

simpler

Smaller

Faster

Less Ambiguous

Generate Data access classes that are easier to use programmatically

 
Today, I am going to introduce how to get startted with Gbp;
 
 
I first try to come up with some .proto file definition, below shows one.
 

// 
//  Google Protocol Buffer definition for GBP overview
//  v10
//
message Person {
  required string name = 1;
  required int32 id = 2;
  optional string email = 3;

  // you can define some types, nested in another type
  enum PhoneType { 
    MOBILE = 0;
	HOME = 1;
	WORK = 2;
  }


  message PhoneNumber {
    required string number = 1;
	optional PhoneType type = 2 [default = HOME]; // you can specify the default value 
	                                              // like object, you can structure the proto messgae with hierarchy
  }


  repeated PhoneNumber phone = 4;                // repeated type is something that can 
                                                 // appear more than once in the message
}

 
As you can see, you can define types just as you can with other type of messages, you are allowed to define nested types, and you can specify whether a particular field of a message is required or optional; You can even specify the default value for an field.  .proto also supports some file that has a "repeated"attribute, which means it may appear more than once.
 
NOTE: One thing about the .proto file is that you should save the .proto file as ANSI encoding, saving to something like UTF8, will ends up having error 
 
'Message' should be in the first line...
 
After you have the .proto file ready, next thing you can do is to generate code from the .proto file.
 
You can ran the following command: 
 

C:\MSDE\boqwang\clr\clr\0.0.0\src\assemblies\GBP\GbpOverview\proto>\\ms\dist\msdotnet\PROJ\protobuf-csharp-port\2.4.1\assemblies\ProtoGen.exe --include_imports -namespace="Protobuf" --proto_path="C:\MSDE\boqwang\clr\clr\0.0.0\src\assemblies\GBP\GbpOverview\Protobuf" "C:\MSDE\boqwang\clr\clr\0.0.0\src\assemblies\GBP\GbpOverview\proto\person.proto"

 
of course, the tool support relative path, you can do the following as well.
 

C:\MSDE\boqwang\clr\clr\0.0.0\src\assemblies\GBP\GbpOverview\proto>\\ms\dist\msdotnet\PROJ\protobuf-csharp-port\2.4.1\assemblies\ProtoGen.exe --include_imports -namespace="Protobuf" --proto_path="." ".\person.proto"

 
be careful where you put the .proto file, the containing folder may ends up in the generated namespace...
 
 
Third, you may add the references to your project that uses Gbp
 

Google.ProtocolBuffers.dll

Google.ProtocolBuffers.Serialization.dll

 
 
there are some lite version of Gbp, which is exclusive from the non-lite one, of the two set of assemblies, only one set can be choosed.
 

Google.ProtocolBuffersLite.dll

Google.ProtocolBuffersLite.Serialization.dll

 
Fourth, add the generated code to .csproj, with that you can program agains the google protocol buffers now.
 
 
Below shows a fairly simple code on how to use the Googlel Protocol Buffer.
 
 

class Program
  {
    static void Main(string[] args)
    {
      var memoryStream = Serialize();
      var person = Deserialize(memoryStream);

      if (person == null)
      {
        Console.Error.WriteLine("Gbp Serialize and Deserialize error!");
      }
    }


    static MemoryStream Serialize()
    {
      Person.Builder builder = new Person.Builder();
      builder.SetName("John").SetId(123).SetEmail("[email protected]");
      Person person = builder.Build();

      MemoryStream stream = new MemoryStream();
      person.WriteTo(stream);

      return stream;
    }

    static Person Deserialize(MemoryStream stream)
    {
      Person person = Person.ParseFrom(stream.ToArray());
      Console.Write("Name: " + person.Name);
      Console.Write("E-mail: " + person.Email);
      return person;
    }
  }

 
As you can see from the code above, Gbp offer
 

simple way to construct.parse object from some raw bytes

And it also support serializing an object to some raw bytes

It support easy manipulate on the fields thrugh the objec tnotation.

the bytes/object conversion is reversible cross machine boundary