gRPC 基础： C＃

通过学习教程中例子，你可以学会如何:

  • 用 protocol buffer 编译器生成服务器和客户端代码。
  • 使用 gRPC 的 C# API 为你的服务实现一个简单的客户端和服务器。
    假设你已经阅读了并且熟悉protocol buffers。 注意，教程中的例子使用的是 protocol buffers 语言的 proto3 版本，它目前只是 alpha 版:可以在和 protocol buffers 的 Github 仓库的版本注释发现更多关于新版本的内容。

这算不上是一个在 C# 中使用 gRPC 的综合指南：以后会有更多的参考文档。

我们的例子是一个简单的路由映射的应用，它允许客户端获取路由特性的信息，生成路由的总结，以及交互路由信息，如服务器和其他客户端的流量更新。

有了 gRPC， 我们可以一次性的在一个 .proto 文件中定义服务并使用任何支持它的语言去实现客户端和服务器，反过来，它们可以在各种环境中，从Google的服务器到你自己的平板电脑—— gRPC 帮你解决了不同语言间通信的复杂性以及环境的不同。使用 protocol buffers 还能获得其他好处，包括高效的序列号，简单的 IDL 以及容易进行的接口更新。

例子代码和设置

教程的代码在这里 . 要下载例子，请通过运行下面的命令去克隆代码库:

本教程的所有文件都在examples/csharp/route_guide目录下。从 Visual Studio (或者 Linux 上的 Monodevelop)打开解决方案 examples/csharp/route_guide/RouteGuide.sln。

如果系统是Windows，除了打开解决方案文件之外，你应当不用多做任何事情。所有你需要的依赖都会在都会在构建解决方案的过程中通过 Grpc NuGet 包自动恢复。

如果系统是 Linux 或者 Mac OS X，为了生成服务器和客户端接口代码，运行例子，你首先需要安装 protobuf 和 gRPC 的 C# 原生依赖。请查看如何使用指令的文档。

我们的第一步(可以从中得知)是使用 protocol buffers去定义 gRPC service 和方法 request 以及 response 的类型。你可以在看到完整的 .proto 文件。

要定义一个服务，你必须在你的 .proto 文件中指定 service:

  1. service RouteGuide {
  2.    ...
  3. }

然后在你的服务中定义 rpc 方法，指定请求的和响应类型。gRPC允 许你定义4种类型的 service 方法，在 RouteGuide 服务中都有使用：

  • 一个 简单 RPC ， 客户端使用存根发送请求到服务器并等待响应返回，就像平常的函数调用一样。

    1.    // Obtains the feature at a given position.
    2.  rpc GetFeature(Point) returns (Feature) {}

  • 一个 服务器端流式 RPC ， 客户端发送请求到服务器，拿到一个流去读取返回的消息序列。 客户端读取返回的流，直到里面没有任何消息。从例子中可以看出，通过在 响应 类型前插入 stream 关键字，可以指定一个服务器端的流方法。

    1.   // Obtains the Features available within the given Rectangle.  Results are
    2. // streamed rather than returned at once (e.g. in a response message with a
    3. // repeated field), as the rectangle may cover a large area and contain a
    4. // huge number of features.
    5. rpc ListFeatures(Rectangle) returns (stream Feature) {}

  • 一个 客户端流式 RPC ， 客户端写入一个消息序列并将其发送到服务器，同样也是使用流。一旦客户端完成写入消息，它等待服务器完成读取返回它的响应。通过在 请求 类型前指定 stream 关键字来指定一个客户端的流方法。

    1.   // Accepts a stream of Points on a route being traversed, returning a
    2. // RouteSummary when traversal is completed.
    3. rpc RecordRoute(stream Point) returns (RouteSummary) {}

  • 一个 双向流式 RPC 是双方使用读写流去发送一个消息序列。两个流独立操作，因此客户端和服务器可以以任意喜欢的顺序读写：比如， 服务器可以在写入响应前等待接收所有的客户端消息，或者可以交替的读取和写入消息，或者其他读写的组合。 每个流中的消息顺序被预留。你可以通过在请求和响应前加 stream 关键字去制定方法的类型。

    1.   // Accepts a stream of RouteNotes sent while a route is being traversed,
    2. // while receiving other RouteNotes (e.g. from other users).
    3. rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}

我们的 .proto 文件也包含了所有请求的 protocol buffer 消息类型定义以及在服务方法中使用的响应类型-比如，下面的Point消息类型：

生成客户端和服务器端代码

接下来我们需要从 .proto 的服务定义中生成 gRPC 客户端和服务器端的接口。我们通过 protocol buffer 的编译器 protoc 以及一个特殊的 gRPC C# 插件来完成。

如果你想自己运行，请确保你已经安装了 protoc 和 gRPC 的 C# 插件。运行的指令因操作系统而异：

  • 对于 Windows 系统来说，Grpc.Tools 和 Google.Protobuf 的 NuGet 包包含了生成代码所需要的二进制文件。

  • 我们使用 Google.Protobuf NuGet 包的protoc.exe 和 Grpc.Tools NuGet 包的 grpc_csharp_plugin.exe （都在 tools 目录下）在 Windows 上生成代码。
    一般来说，你需要自己添加 Grpc.Tools 包到解决方案中，但在本教程中，它已经帮你完成了。下面的命令应当从examples/csharp/route_guide 目录运行：

  1.   > packages\Google.Protobuf.3.0.0-alpha4\tools\protoc.exe -I../../protos --csharp_out RouteGuide --grpc_out RouteGuide --plugin=protoc-gen-grpc=packages\Grpc.Tools.0.7.0\tools\grpc_csharp_plugin.exe ../../protos/route_guide.proto

  • 在 Linux 或者 OS X 系统，我们可以用 Linuxbrew/Homebrew 安装 protoc 和 grpc_csharp_plugin 依赖。从 route_guide 目录运行下面的命令：

  • protoc -I../../protos —csharp_out RouteGuide —grpc_out RouteGuide —plugin=which grpc_csharp_plugin ../../protos/route_guide.proto

根据操作系统的不同，运行对应的命令去重新在 RouteGuide 目录生成下面的文件：

  • RouteGuide/RouteGuide.cs 定义了一个命名空间 Routeguide
    • 它包含了所有填充，序列化的 protocol buffer 代码以及获取我们的请求和响应的类型。
  • RouteGuide/RouteGuideGrpc.cs, 提供了存根和服务类
    • 定义 RouteGuide 服务实现时继承的接口 RouteGuide.IRouteGuide
    • 用来访问远程 RouteGuide 实例的类 RouteGuide.RouteGuideClient

首先来看看我们如何创建一个 RouteGuide 服务器。如果你只对创建 gRPC 客户端感兴趣，你可以跳过这个部分，直接到创建客户端 (当然你也可能发现它也很有意思)。

让 RouteGuide 服务工作有两个部分：

  • 实现我们服务定义的生成的服务接口：做我们的服务的实际的“工作”。
  • 运行一个 gRPC 服务器，监听来自客户端的请求并返回服务的响应。
    你可以从看到我们的 RouteGuide 服务器的实现代码。现在让我们近距离研究它是如何工作的。

我们可以看出，服务器有一个实现了生成的 RouteGuide.IRouteGuide 接口的 RouteGuideImpl 类：

  1. // RouteGuideImpl provides an implementation of the RouteGuide service.
  2. public class RouteGuideImpl : RouteGuide.IRouteGuide

简单RPC

RouteGuideImpl 实现了所有的服务方法。让我们先来看看最简单的类型 GetFeature，它从客户端拿到一个 Point 然后将对应的从数据库中取得的特征信息置于 Feature 内返回给客户端。

  1. public Task<Feature> GetFeature(Point request, Grpc.Core.ServerCallContext context)
  2. {
  3.     return Task.FromResult(CheckFeature(request));
  4. }

为了 RPC，方法被传入一个上下文（alpha 版的时候为空），指客户端的 Point protocol buffer 请求，返回一个 Feature protocol buffer。在方法中，我们用适当的信息创建 Feature 然后返回。为了允许异步的实现，方法返回 Task<Feature> 而不仅是 Feature。你可以随意的同步执行你的计算，并在完成后返回结果，就像我们在例子中做的一样。

服务器端流式 RPC

现在让我们来看看稍微复杂点的 —— 一个流式 RPC。ListFeatures 是一个服务器端的流式 RPC，所以我们需要给客户端发回多个 Feature protocol buffer。

  1. // in RouteGuideImpl
  2. public async Task ListFeatures(Rectangle request,
  3.     Grpc.Core.IServerStreamWriter<Feature> responseStream,
  4.     Grpc.Core.ServerCallContext context)
  5. {
  6.     var responses = features.FindAll( (feature) => feature.Exists() && request.Contains(feature.Location) );
  7.     {
  8.         await responseStream.WriteAsync(response);
  10. }

如你所见，这里的请求对象是一个 Rectangle，客户端期望从中找到 Feature，但是我们需要使用异步方法 WriteAsync 写入响应到 IServerStreamWriter 异步流而不是一个简单的响应。

客户端流 RPC

类似的，客户端流方法 RecordRoute 使用一个IAsyncEnumerator，使用异步方法 MoveNext 和 Current 属性去读取请求的流。

  1. public async Task<RouteSummary> RecordRoute(Grpc.Core.IAsyncStreamReader<Point> requestStream,
  2.     Grpc.Core.ServerCallContext context)
  3. {
  4.     int pointCount = 0;
  5.     int featureCount = 0;
  6.     int distance = 0;
  7.     Point previous = null;
  8.     var stopwatch = new Stopwatch();
  9.     stopwatch.Start();
  11.     while (await requestStream.MoveNext())
  12.     {
  13.         var point = requestStream.Current;
  14.         pointCount++;
  15.         if (CheckFeature(point).Exists())
  16.         {
  17.             featureCount++;
  18.         }
  19.         if (previous != null)
  20.         {
  21.             distance += (int) previous.GetDistance(point);
  22.         }
  23.         previous = point;
  24.     }
  26.     stopwatch.Stop();
  28.     return new RouteSummary
  29.     {
  30.         PointCount = pointCount,
  31.         FeatureCount = featureCount,
  32.         Distance = distance,
  33.         ElapsedTime = (int)(stopwatch.ElapsedMilliseconds / 1000)
  34.     };
  35. }

双向流 RPC

最后，让我们来看看双向流 RPC RouteChat。

这里的方法同时接收到 requestStream 和 responseStream 参数。读取请求和客户端流方法 RecordRoute 的方式相同。写入响应和服务器端流方法 ListFeatures 的方式相同。

一旦我们实现了所有的方法，我们还需要启动一个gRPC服务器，这样客户端才可以使用服务。下面这段代码展示了在我们 RouteGuide 服务中实现的过程：

  1. var features = RouteGuideUtil.ParseFeatures(RouteGuideUtil.DefaultFeaturesFile);
  3. Server server = new Server
  4. {
  5.     Services = { RouteGuide.BindService(new RouteGuideImpl(features)) },
  6.     Ports = { new ServerPort("localhost", Port, ServerCredentials.Insecure) }
  7. };
  8. server.Start();
  9. Console.WriteLine("RouteGuide server listening on port " + port);
  10. Console.WriteLine("Press any key to stop the server...");
  13. server.ShutdownAsync().Wait();

如你所见，我们通过使用 Grpc.Core.Server 去构建和启动服务器。为了做到这点，我们需要：

    • 创建 Grpc.Core.Server 的一个实例。
    • 创建我们的服务实现类 RouteGuideImpl 的一个实例。
    • 通过在 Services 集合中添加服务的定义（我们从生成的 RouteGuide.BindService 方法中获得服务定义）注册我们的服务实现。
    • 指定想要接受客户端请求的地址和监听的端口。通过往 Ports 集合中添加 ServerPort 即可完成。
    • 在服务器实例上调用 Start 为我们的服务启动一个 RPC 服务器。

创建客户端

为了能调用服务的方法，我们得先创建一个 存根。

首先需要为我们的存根创建一个可以连接到 gRPC 服务器的 gRPC channel。然后我们使用 .proto 生成的RouteGuide类的RouteGuide.NewClient方法。

  1. Channel channel = new Channel("127.0.0.1:50052", ChannelCredentials.Insecure)
  2. var client = RouteGuide.NewClient(channel);
  4. // YOUR CODE GOES HERE
  6. channel.ShutdownAsync().Wait();

现在我们来看看如何调用服务的方法。gRPC C# 的每个支持的方法类型都提供了异步的版本。为了方便起见，gPRC C# 也提供了同步方法存根，不过只能用于简单的（单个请求/单个响应）RPC。

简单 RPC

以同步的方式调用简单 RPC GetFeature 几乎是和调用一个本地方法一样直观。

  1. Point request = new Point { Latitude = 409146138, Longitude = -746188906 };
  2. Feature feature = client.GetFeature(request);

如你所见，我们创建并且填充了一个请求的 protocol buffer 对象（例子中为 Point），在客户端对象上调用期望的方法，并传入请求。如果 RPC 成功结束，则返回响应的 protocol buffer（在例子中是Feature）。否则抛出 RpcException 类型的异常，指出问题的状态码。

或者，如果你在异步的上下文环境中，你可以调用这个方法的异步版本并且使用 await 关键字来等待结果:

  1. Point request = new Point { Latitude = 409146138, Longitude = -746188906 };
  2. Feature feature = await client.GetFeatureAsync(request);

流式 RPC

现在来看看我们的流方法。如果你已经读过，本节的一些内容看上去很熟悉——流式 RPC 是在客户端和服务器两端以一种类似的方式实现的。和简单的调用不同的地方在于客户端方法返回了调用对象的实例。它提供了使用请求/响应流和（或者）异步的结果，取决于你使用的流类型。

下面就是我们称作是服务器端的流方法 ListFeatures，它有IAsyncEnumerator<Feature>类型的属性ReponseStream：

  1. using (var call = client.ListFeatures(request))
  2. {
  3.     while (await call.ResponseStream.MoveNext())
  4.     {
  5.         Feature feature = call.ResponseStream.Current;
  6.         Console.WriteLine("Received " + feature.ToString());
  7.     }
  8. }

客户端的流方法 RecordRoute 的使用和它很相似，除了我们通过 WriteAsync 使用 RequestStream 属性挨个写入请求，最后使用 CompleteAsync 去通知不再需要发送更多的请求。可以通过 ResponseAsync 获取方法的结果。

最后，让我们看看双向流式 RPC RouteChat()。在这种场景下，我们将请求写入 RequestStream 并且从 ResponseStream 接受到响应。从例子可以看出，流之间是互相独立的。

  1. using (var call = client.RouteChat())
  2. {
  3.     var responseReaderTask = Task.Run(async () =>
  4.     {
  5.         while (await call.ResponseStream.MoveNext())
  6.         {
  7.             var note = call.ResponseStream.Current;
  8.             Console.WriteLine("Received " + note);
  9.         }
  10.     });
  12.     foreach (RouteNote request in requests)
  13.     {
  14.         await call.RequestStream.WriteAsync(request);
  15.     }
  16.     await call.RequestStream.CompleteAsync();
  17.     await responseReaderTask;
  18. }

构建客户端和服务器：

  • 用 Visual Studio (或者Linux上的Monodevelop) 打开解决方案 examples/csharp/route_guide/RouteGuide.sln并选择 Build。

> cd RouteGuideServer/bin/Debug
> RouteGuideServer.exe

  • 在另一个终端运行客户端：

> cd RouteGuideClient/bin/Debug
> RouteGuideClient.exe

你也可以直接从 Visual Studio 里直接运行服务器和客户端。

在Linux 或者 Mac系统中， 使用 mono RouteGuideServer.exe 和 mono RouteGuideClient.exe 命令去运行服务器和客户端。

原文: