Protocol Buffer 基础知识:c#    原文地址:https://developers.google.com/protocol-buffers/docs/csharptutorial
 
    这篇讲解c#版的Protocol Buffers的帖子,并不是完整的指南。想了解更多的信息请查看 Protocol Buffer Language Guide,  C# API Reference,  C# Generated Code GuideEncoding Reference.
 
    为什么使用protocol buffers?
    我们通过一个非常简单的"地址薄"程序来讲解,这个程序可以把人们的联系方式读取和写入一个文件。每个人的地址包含一个name, ID,email,和一个联系电话phone.
    你要怎么序列化和获取这样的结构化数据?这里有几种解决方案:
    *通过使用.net的二进制序列化System.Runtime.Serialization.Formatters.Binary.BinaryFormatter和相关的类。在一些数据大小要求苛刻的情况下,面对改变,这是非常脆弱的。
     并且对于跨平台共享数据方面做的不是很好。
    *你可以用特别的方式把数据编码成一个字符串-例:把4个int型数据编码成"12:3:-23:67".尽管它需要一次性编码和解析,解析时会造成一点运行时的损耗,但是它是非常简单灵活的做法。
     对于简单的数据编码这是最好的方式。
    *把数据序列化成XML。这种方式是非常吸引人的,因为对于人类XML是通俗易懂的,并且很多语言都有相应的库。但是XML是出了名的空间密集,编码和解码会造成程序上很大的性能损失。
     并且导航一个XML DOM树通常要比导航一个类中的字段复杂的多。
    Protocol Buffe 是灵活的,高效的,自动化的解决方案,完美的解决了上述的问题。你可以写一个 .proto文件用于描述你想存储的数据结构。然后,protocol buffer 编译器创建一个类。
这个类使用高效的二进制格式实现了自动编码和解析protocol buffer 数据。这个生成的类为字段生成了getters和setters,组成一条protocol buffer。并且会像一个单元一样处理详细的读写protocol
buffer.重要的是,potocol buffer格式支持随着时间扩展的概念,使用这样的方式代码始终可以读取旧格式的数据编码。
     
     从哪找到示例代码?
     我们的例子是用管理地址薄数据文件的命令行应用程序,使用protocol buffers 编码。 AddressBook 命令(查看 Program.cs )可以把一个新的实体添加到数据文件或者解析数据文件并输出到控制台。
     你可以在GitHub的 examples directorycsharp/src/AddressBook directory找到完整的示例代码。
 
     定义你自己的协议格式(protcol format)
     你需要使用 .proto文件来创建地址薄应用程序.在 .proto文件内定义非常简单:为每一个你想序列化的数据结构添加一个message,在message中为每个字段指定名称和类型。在我们的示例中,定义message 的 .proto文件在 addressbook.proto
     .proto文件的起始行声明一个包,这样可以避免在不同的项目中命名空间发生冲突。
syntax = "proto3";
package tutorial;
     使用c#,如果你没有指定命名空间( csharp_namespace)你生成的类会被放置到和包名称一至的命名空间中。在我们的示例中, csharp_namespace 选项已经被重新指新值,所以生成的代码使用命名空间 Google.Protobuf.Examples.AddressBook而不是 Tutorial。   
option csharp_namespace = "Google.Protobuf.Examples.AddressBook";
     下一步,定义你自己的message .message 是字段的集合。有许多标准的简单数据类型可以供字段类型使用,包含 boolint32floatdouble, and string.你可以通过使用其它message 类型做为字段类型,来增加更多的结构。
message Person {
string name = ;
int32 id = ; // Unique ID number for this person.
string email = ; enum PhoneType {
MOBILE = ;
HOME = ;
WORK = ;
} message PhoneNumber {
string number = ;
PhoneType type = ;
} repeated PhoneNumber phones = ;
} // Our address book file is just one of these.
message AddressBook {
repeated Person people = ;
}

     在上边的示例中, Person  message包含  PhoneNumber message, AddressBook message 包含 Person message.甚至你可以在message里定义message类型- 你可以看到, PhoneNumber类型定义在 Person里。如果你想字段拥有预定义好的集合中的一个值,你可以定义枚举( enum)类型 -这里我们指定一个手机号,可以是 MOBILEHOME, 或者 MOBILEHOME, 。
     每一个元素都有 " = 1", " = 2"这样的标记,这些标记是字段在二进制编码内的唯一标识标签,标签数字1-15比更大的数字需要更少的字节编码,做为优化你可以为常用的或repeated元素使用这些标签数字,把16以上的标签留给不经常使用的元素。重复字段的每一个元素都需要重新编码标签数字,所以重复字段特别适合这种优化。
     如果字段值没有被设置,使用默认值( default value):数值类型使用0,字符串类型使用空字符串,布尔类型为false。对于内嵌的message,如果没有给字段赋值,默认的值一般是message的"默认示例"或"原型"。如果没有显示的给字段设置值,在调用访问器时得到的是它的默认值。
     如果字段是 repeated这个字段可以重复任意次(包含0)。重复的值按序保存到protocol buffer.把重复字段相像成一个动态大小的数组。
     你可以在  Protocol Buffer Language Guide 找到一个完整编写 .proto文件的指南-包含所有可能的字段类型。不要去寻找类似于继承的功能,protocol buffer不这么做。
     编译你自己的 protocol buffers
     现在你已经有了一个 .proto.下面的事你需要做的是生成一个类,这个类用来读写 AddressBook消息(包含 Person和 PhoneNumber)。为了能完成这样的工作,你需要运行protocol buffer的编译器 protoc,编译你的 protoc文件。
     1.如果你没有安装编译器,下载 download the package后根据README的指示进行操作。
     2.现在运行你的编译器,指定源码目录(你的应用程序源码所在的文件夹-如果你不指定,会使用当前的文件夹目录),目标目录(生成代码保存的目录;一般和 $SRC_DIR是一样的),你的 .proto文件的路径,这个例子中你...:     
protoc -I=$SRC_DIR --csharp_out=$DST_DIR $SRC_DIR/addressbook.proto
     因为你使用c#类,所以使用 --csharp_out选项--相似的选项用来支持其它的语言。
     在你指定的目录生成 Addressbook.cs类。为了能编译这个代码,你需要有一个引用了 Google.Protobuf程序集的工程。
 
     地址薄类
     生成的 Addressbook.cs提供了5种有用的类型:
     1.一个静态的 AddressBook类,包含protocol buffer message的元数据。
     2.一个有只读 People属性类 AddressBook。
     3.一个拥有的 NameIdEmail和 Phones属性的类 Person。
     4.一个 PhoneNumber类,嵌入在静态的类 Person.Types中。
     5.一个 PhoneType枚举,也嵌入在 Person.Types中。
 
     你可以在 C# Generated Code guide阅读更多更详细的的生成信息。但是大部分你都可以把它们看成普通的c#类型。需要声明的一点重复字段(repeated fields)是只读的。你可以添加或删除项,但是不能使用一个完全独立的集合替换它。重复字段的集合类型是 RepeatedField<T>。这个类型像 List<T>一样,只是多了一些额外的便利方法,就像 Add方法的重载可以接收项的集合,用于集合的初始化。
     下边是一个例子用于说明如何创建一个Person的实例:
Person john = new Person
{
Id = ,
Name = "John Doe",
Email = "jdoe@example.com",
Phones = { new Person.Types.PhoneNumber { Number = "555-4321", Type = Person.Types.PhoneType.HOME } }
};
     注意如果使用c#6,你可以使用 using static删除 Person.Types。
 
// Add this to the other using directives
using static Google.Protobuf.Examples.AddressBook.Person.Types;
...
// The earlier Phones assignment can now be simplified to:
Phones = { new PhoneNumber { Number = "555-4321", Type = PhoneType.HOME } }
     解析和序列化
     使用protocol buffers的目的是序列化你的数据,在任何地方都可以解析。所有生成的类都有一个 WriteTo(CodedOutputStream)方法, CodedOutputStream是prtocol buffer运行时库的一个类。然而,一般情况下你可以使用扩展方法之一来写入到一个常规的 System.IO.Stream或者把message转换成二进制数组或者 ByteString.这些扩展信息在 Google.Protobuf.MessageExtensions类,所以当你想序列化时,你需要使用 using引入 Google.Protobuf命名空间,例:
using Google.Protobuf;
...
Person john = ...; // Code as before
using (var output = File.Create("john.dat"))
{
john.WriteTo(output);
}

     解析也是非常简单的。每一个生成的类都有一个静态的属性 Parser,为这个类型返回 MessageParser<T>。反过来有一个方法用来解析流,二进制数组和 ByteString。用来解析我们刚创建的文件,我们可以这么做:
Person john;
using (var input = File.OpenRead("john.dat"))
{
john = Person.Parser.ParseFrom(input);
}

     使用这些信息维护一个addressbook(添加一个新实体,和现有的清单) 的完整的示例程序在这里 in the Github repository
 
    扩展 Protocol Buffer
    迟早你会发布使用protocol buffer的代码,毫无疑问的你想改善protocol buffer的定义。如果你想要新的buffers向后兼容,并且你的旧buffers向前兼容-不用说你一定想要这个-这里有一些规则你需要遵守。在新版本的protocol buffer:
     1.你不能改变已有字段的数字标签.
     2.你不能删除字段.
     3.添加新字段的时候一定要用没使用过的标签数字(也就是说,你不能使用已经使用过的标签数字,删除字段的标签数字也不要用)。
    如果你遵守这些规则,老的代码会非常高兴的读取新消息,并且忽略你新添加的字段。对于旧代码来说,删除的单独字段也会有它们的默认值,删除的repeated字段会被赋为空。新代码也会透明的读取旧的消息。
 
    反射
    消息描述(文件的内容信息)消息的实例可使用反射api进行检验。对于编写不同文本格式的的代码或智能比较工具是非常有用的。每一个生成的类都有一个静态的 Descriptor属性,可以使用 IMessage.Descriptor属性获取任意实例的描述。下面是一个如何使用上述内容的简单例子,一个用来打印任意message的顶级字段的简单的方法。
public void PrintMessage(IMessage message)
{
var descriptor = message.Descriptor;
foreach (var field in descriptor.Fields.InDeclarationOrder())
{
Console.WriteLine(
"Field {0} ({1}): {2}",
field.FieldNumber,
field.Name,
field.Accessor.GetValue(message);
}
}
 
 
 
 
 
 
 
 
 
 
 
 

[原创翻译]Protocol Buffer Basics: C#的更多相关文章

  1. [翻译]Protocol Buffer 基础: C++

    目录 Protocol Buffer Basics: C++ 为什么使用 Protocol Buffers 在哪可以找到示例代码 定义你的协议格式 编译你的 Protocol Buffers Prot ...

  2. Protocol Buffer Basics: Python

    原文https://developers.google.com/protocol-buffers/docs/pythontutorial Protocol Buffer Basics: Python ...

  3. Protocol Buffer Basics: C#

    Protocol Buffer 基础知识:c#    原文地址:https://developers.google.com/protocol-buffers/docs/csharptutorial   ...

  4. Google Protocol Buffer Basics: C++

    proto文件简介 每个元素上的"= 1","= 2"标记标识该字段在二进制编码中使用的唯一"标记" 每个字段有三个可选修饰符 requir ...

  5. Protocol Buffer技术

    转载自http://www.cnblogs.com/stephen-liu74/archive/2013/01/02/2841485.html 该系列Blog的内容主体主要源自于Protocol Bu ...

  6. Protocol Buffer技术详解(语言规范)

    Protocol Buffer技术详解(语言规范) 该系列Blog的内容主体主要源自于Protocol Buffer的官方文档,而代码示例则抽取于当前正在开发的一个公司内部项目的Demo.这样做的目的 ...

  7. Protocol Buffer基本介绍

    转自:http://www.cnblogs.com/stephen-liu74/archive/2013/01/02/2841485.html 该系列Blog的内容主体主要源自于Protocol Bu ...

  8. Google Protocol Buffer

    Google Protocol Buffer(protobuf)是一种高效且格式可扩展的编码结构化数据的方法.和JSON不同,protobuf支持混合二进制数据,它还有先进的和可扩展的模式支持.pro ...

  9. Protocol Buffer学习教程之语法手册(二)

    1.说明 此向导介绍如何使用protocol buffer language创建一个自己的protocolbuffer文件,包括语法与如何通过“.proto”文件生成数据访问的类,此处只介绍proto ...

随机推荐

  1. Android Do not keep activities选项分析

    Android Do not keep activities选项分析 Developer Options里面有一项: Do not keep activities -> 不保留Activitie ...

  2. 浅谈html5 响应式布局

    一.什么是响应式布局? 响应式布局是Ethan Marcotte在2010年5月份提出的一个概念,简而言之,就是一个网站能够兼容多个终端——而不是为每个终端做一个特定的版本. 这个概念是为解决移动互联 ...

  3. SCRIPT5011:不能执行已释放Script的代码

    环境:win7 64位 IE9 错误:SCRIPT5011:不能执行已释放Script的代码. 现象:在父窗体的close()中调用嵌套的iframe页面的js方法返回一个对象时抛此异常. 原因:在一 ...

  4. iOS Class 使用NSProxy和NSObject设计代理类的差异

    经常发现在一些需要使用消息转发而创建代理类时, 不同的程序员都有着不同的使用方法, 有些采用继承于NSObject, 而有一些采用继承自NSProxy. 二者都是Foundation框架中的基类, 并 ...

  5. 初识angularjs

    1,angular的ng-model带来了双向绑定机制 2,用angular的表达式{{...}}现实在HTML中,存储在我们的$scope上 3,在angular中$scope是连接controll ...

  6. Android应用开发基础之十二:版本控制

    为什么需要版本控制? 场景1: 你的代码正常工作 你改了其中的几行代码 程序出了问题 你把代码改回来 程序还是不能正常工作——为什么? 场景2: 你的程序昨天还能正常运行 昨天晚上你修改了很多内容,做 ...

  7. ORACLE OLAP错误ORA-06512: at "SYS.OLAPIHISTORYRETENTION"

    刚刚安装了ORACLE 10g R2后,启动数据库时发现告警日志有如下错误: Database Characterset is UTF8 replication_dependency_tracking ...

  8. 如何让Log4net日志文件按每月归成一个文件夹,StaticLogFileName参数的用法

    想要让Log4net日志(以下称日志)按每月自动归类为一个文件夹,为此,学习和修改了log4net.config文件.查了资料,重点是以下这些参数:      <param name=" ...

  9. mysql中boolean类型

      MYSQL保存BOOLEAN值时用1代表TRUE,0代表FALSE,boolean在MySQL里的类型为tinyint(1), MySQL里有四个常量:true,false,TRUE,FALSE, ...

  10. win10磁盘100%解决办法

    控制面板-管理工具-服务 找到“HomeGroupListener”服务,双击打开或右键单击“属性”命令. 在弹出属性界面窗口,在常规选项卡单击启动类型的下拉框,出来的列表选择“禁用”.然后在服务状态 ...