gRPC-Protocol基础知识-C#篇

本文使用协议缓冲区语言的proto3版本，为C＃程序员提供了使用协议缓冲区的基本介绍。通过创建一个简单的示例应用程序，展示了如何

在.proto文件中定义消息格式。
使用协议缓冲区编译器。
使用C＃协议缓冲区API写入和读取消息。

这不是在C＃中使用协议缓冲区的全面指南。有关更多详细的参考信息，请参阅《协议缓冲区语言指南》，《 C＃API参考》，《 C＃生成的代码指南》和《编码参考》。

为什么要使用协议缓冲区？

我们将使用的示例是一个非常简单的“地址簿”应用程序，该应用程序可以在文件中读写人的联系方式。通讯录中的每个人都有一个姓名，一个ID，一个电子邮件地址和一个联系电话。

您如何像这样序列化和检索结构化数据？有几种方法可以解决此问题：

将.NET二进制序列化与System.Runtime.Serialization.Formatters.Binary.BinaryFormatter和关联的类一起使用。面对变化，这最终变得非常脆弱，在某些情况下，数据大小非常昂贵。如果您需要与为其他平台编写的应用程序共享数据，它也不是很好。

您可以发明一种将数据项编码为单个字符串的临时方法，例如将4个整数编码为“ 12：3：-23：67”。尽管确实需要编写一次性的编码和解析代码，但是这是一种简单且灵活的方法，而且解析带来的运行时成本很小。这对于编码非常简单的数据最有效。

将数据序列化为XML。由于XML是人类（一种）可读的，并且存在用于多种语言的绑定库，因此这种方法可能非常有吸引力。如果要与其他应用程序/项目共享数据，这可能是一个不错的选择。但是，众所周知，XML占用大量空间，对它进行编码/解码会给应用程序带来巨大的性能损失。同样，导航XML DOM树比通常导航类中的简单字段要复杂得多。

协议缓冲区是灵活，高效，自动化的解决方案，可以准确地解决此问题。使用协议缓冲区，您可以编写要存储的数据结构的.proto描述。由此，协议缓冲区编译器创建了一个类，该类以有效的二进制格式实现协议缓冲区数据的自动编码和解析。生成的类为构成协议缓冲区的字段提供获取器和设置器，并以协议为单位来处理读写协议缓冲区的详细信息。重要的是，协议缓冲区格式支持随时间扩展格式的想法，以使代码仍可以读取以旧格式编码的数据。

在哪里找到示例代码?

我们的示例是一个命令行应用程序，用于管理使用协议缓冲区编码的地址簿数据文件。命令AddressBook（请参阅：Program.cs）可以将新条目添加到数据文件或解析数据文件并将数据打印到控制台。

您可以在GitHub存储库的examples目录和csharp / src / AddressBook目录中找到完整的示例。

定义协议格式

要创建地址簿应用程序，您需要以.proto文件开头。 .proto文件中的定义很简单：您为要序列化的每个数据结构添加一条消息，然后为消息中的每个字段指定名称和类型。在我们的示例中，定义消息的.proto文件是addressbook.proto。

.proto文件以程序包声明开头，这有助于防止不同项目之间的命名冲突。

syntax = "proto3";

package tutorial;

import "google/protobuf/timestamp.proto";

在C＃中，如果未指定csharp_namespace，则将生成的类放置在与程序包名称匹配的名称空间中。在我们的示例中，指定了csharp_namespace选项以覆盖默认值，因此生成的代码使用Google.Protobuf.Examples.AddressBook的命名空间而不是Tutorial。

option csharp_namespace = "Google.Protobuf.Examples.AddressBook";

接下来，您将拥有消息定义。消息只是包含一组类型字段的汇总。许多标准的简单数据类型可用作字段类型，包括bool，int32，float，double和string。您还可以通过使用其他消息类型作为字段类型来为消息添加更多的结构。

message Person {

  string name = 1;

  int32 id = 2;  // Unique ID number for this person.

  string email = 3;

  enum PhoneType {

    MOBILE = 0;

    HOME = 1;

    WORK = 2;

  }

  message PhoneNumber {

    string number = 1;

    PhoneType type = 2;

  }

  repeated PhoneNumber phones = 4;

  google.protobuf.Timestamp last_updated = 5;

}

// Our address book file is just one of these.

message AddressBook {

  repeated Person people = 1;

}

在上面的示例中，Person消息包含PhoneNumber消息，而AddressBook消息包含Person消息。您甚至可以定义嵌套在其他消息中的消息类型-如您所见，PhoneNumber类型在Person内部定义。如果希望您的字段之一具有预定义的值列表之一，也可以定义枚举类型-在这里您要指定电话号码可以是MOBILE，HOME或WORK之一。

每个元素上的“ = 1”，“ = 2”标记标识该字段在二进制编码中使用的唯一“标记”。标签编号1至15与较高的编号相比，编码所需的字节减少了一个字节，因此，为了进行优化，您可以决定将这些标签用于常用或重复的元素，而将标签16和更高的标签用于较少使用的可选元素。重复字段中的每个元素都需要重新编码标签号，因此重复字段是此优化的最佳候选者。

如果未设置字段值，则使用默认值：数字类型为零，字符串为空字符串，布尔值为false。对于嵌入式消息，默认值始终是消息的“默认实例”或“原型”，没有设置任何字段。调用访问器以获取尚未显式设置的字段的值将始终返回该字段的默认值。

如果重复一个字段，则该字段可以重复任意次（包括零次）。重复值的顺序将保留在协议缓冲区中。将重复字段视为动态大小的数组。

在协议缓冲区语言指南中，您将找到有关编写.proto文件的完整指南-包括所有可能的字段类型。但是，不要去寻找类似于类继承的工具–协议缓冲区不能做到这一点。

编译协议缓冲区

现在，您有了.proto，接下来需要做的是生成读取和写入AddressBook（以及Person和PhoneNumber）消息所需的类。为此，您需要在.proto上运行协议缓冲区编译器协议：

如果尚未安装编译器，请下载软件包并按照自述文件中的说明进行操作。
现在运行编译器，指定源目录（应用程序的源代码所在的位置；如果您不提供值，则使用当前目录），目标目录（您希望生成的代码进入的位置；通常与$相同） SRC_DIR），以及.proto的路径。在这种情况下，您将调用：

protoc -I=$SRC_DIR --csharp_out=$DST_DIR $SRC_DIR/addressbook.proto

因为需要C＃代码，所以使用--csharp_out选项–其他受支持的语言也提供了类似的选项。

这将在您指定的目标目录中生成Addressbook.cs。要编译此代码，您需要一个引用Google.Protobuf程序集的项目。

通讯录类

生成Addressbook.cs提供了五种有用的类型：

静态地址簿类，其中包含有关协议缓冲区消息的元数据。
具有只读People属性的AddressBook类。
具有“名称”，“ ID”，“电子邮件”和“电话”属性的Person类。
一个PhoneNumber类，嵌套在静态Person.Types类中。
一个PhoneType枚举，也嵌套在Person.Types中。

您可以在《C＃生成的代码》指南中详细了解确切生成的内容的详细信息，但是在大多数情况下，您可以将它们视为完全普通的C＃类型。需要强调的一点是，对应于重复字段的任何属性都是只读的。您可以向集合中添加项目或从集合中删除项目，但是不能用完全独立的集合来替换它。重复字段的收集类型始终为RepeatedField 。此类型类似于List ，但有一些额外的便捷方法，例如，在大学初始化程序中使用的Add重载接受项目集合。

这是一个如何创建Person实例的示例：

Person john = new Person

{

    Id = 1234,

    Name = "John Doe",

    Email = "jdoe@example.com",

    Phones = { new Person.Types.PhoneNumber { Number = "555-4321", Type = Person.Types.PhoneType.Home } }

};

请注意，在C＃6中，可以使用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 } }

解析和序列化

使用协议缓冲区的全部目的是对数据进行序列化，以便可以在其他位置对其进行解析。每个生成的类都有一个WriteTo（CodedOutputStream）方法，其中CodedOutputStream是协议缓冲区运行时库中的类。但是，通常您将使用一种扩展方法来写入常规System.IO.Stream或将消息转换为字节数组或ByteString。这些扩展消息位于Google.Protobuf.MessageExtensions类中，因此，当您要序列化时，通常会希望对Google.Protobuf名称空间使用using指令。例如：

using Google.Protobuf;

...

Person john = ...; // Code as before

using (var output = File.Create("john.dat"))

{

    john.WriteTo(output);

}

解析也很简单。每个生成的类都有一个静态的Parser属性，该属性返回该类型的MessageParser 。反过来，它具有解析流，字节数组和ByteStrings的方法。因此，要解析我们刚刚创建的文件，我们可以使用：

Person john;

using (var input = File.OpenRead("john.dat"))

{

    john = Person.Parser.ParseFrom(input);

}

Github存储库中提供了使用这些消息维护地址簿（添加新条目并列出现有条目）的完整示例程序。

扩展协议缓冲区

在发布使用协议缓冲区的代码后早晚，您无疑会想要“改善”协议缓冲区的定义。如果您希望新的缓冲区向后兼容，而旧的缓冲区向后兼容，并且您几乎肯定希望这样做，那么您需要遵循一些规则。在新版本的协议缓冲区中：

您不得更改任何现有字段的标签号。
您可以删除字段。
您可以添加新字段，但必须使用新的标签号（即，该协议缓冲区中从未使用过的标签号，即使删除的字段也从未使用过）。

（这些规则有一些例外，但很少使用。）

如果遵循这些规则，旧代码将很乐意阅读新消息，而忽略任何新字段。对于旧代码，删除的单个字段将仅具有其默认值，而删除的重复字段将为空。新代码还将透明地读取旧消息。

但是，请记住，新字段不会出现在旧消息中，因此您需要对默认值进行合理的处理。使用特定于类型的默认值：对于字符串，默认值为空字符串。对于布尔值，默认值为false。对于数字类型，默认值为零。

反射

可以使用反射API以编程方式检查消息描述符（.proto文件中的信息）和消息实例。在编写通用代码（例如不同的文本格式或智能差异工具）时，此功能很有用。每个生成的类都有一个静态的Descriptor属性，并且可以使用IMessage.Descriptor属性来检索任何实例的描述符。作为如何使用它们的一个快速示例，这是一种打印任何消息的顶级字段的简短方法。

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);

    }

}

参考文档

https://developers.google.com/protocol-buffers/docs/csharptutorial