gRPC 基础: C#

本教程提供了 C# 程序员如何使用 gRPC 的指南。

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

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

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

为什么使用 gRPC?

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

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

例子代码和设置

教程的代码在这里 grpc/grpc/examples/cpp/route_guide. 要下载例子,请通过运行下面的命令去克隆grpc代码库:

  1. - git clone https://github.com/grpc/grpc.git

本教程的所有文件都在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 的类型。你可以在examples/protos/route_guide.proto看到完整的 .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消息类型:

  1. // Points are represented as latitude-longitude pairs in the E7 representation
  2. // (degrees multiplied by 10**7 and rounded to the nearest integer).
  3. // Latitudes should be in the range +/- 90 degrees and longitude should be in
  4. // the range +/- 180 degrees (inclusive).
  5. message Point {
  6. int32 latitude = 1;
  7. int32 longitude = 2;
  8. }

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

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

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

  • 对于 Windows 系统来说,Grpc.Tools 和 Google.Protobuf 的 NuGet 包包含了生成代码所需要的二进制文件。
  • 对于 Linux 或者 OS X,请确保你查看了如何使用指令的文档。
    以上都完成后,你就可以生成下面的 C# 代码:

  • 我们使用 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 服务器,监听来自客户端的请求并返回服务的响应。
    你可以从examples/csharp/route_guide/RouteGuideServer/RouteGuideImpl.cs看到我们的 RouteGuide 服务器的实现代码。现在让我们近距离研究它是如何工作的。

实现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. foreach (var response in responses)
  8. {
  9. await responseStream.WriteAsync(response);
  10. }
  11. }

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

客户端流 RPC

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

  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();
  10. while (await requestStream.MoveNext())
  11. {
  12. var point = requestStream.Current;
  13. pointCount++;
  14. if (CheckFeature(point).Exists())
  15. {
  16. featureCount++;
  17. }
  18. if (previous != null)
  19. {
  20. distance += (int) previous.GetDistance(point);
  21. }
  22. previous = point;
  23. }
  24. stopwatch.Stop();
  25. return new RouteSummary
  26. {
  27. PointCount = pointCount,
  28. FeatureCount = featureCount,
  29. Distance = distance,
  30. ElapsedTime = (int)(stopwatch.ElapsedMilliseconds / 1000)
  31. };
  32. }

双向流 RPC

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

  1. public async Task RouteChat(Grpc.Core.IAsyncStreamReader<RouteNote> requestStream,
  2. Grpc.Core.IServerStreamWriter<RouteNote> responseStream,
  3. Grpc.Core.ServerCallContext context)
  4. {
  5. while (await requestStream.MoveNext())
  6. {
  7. var note = requestStream.Current;
  8. List<RouteNote> prevNotes = AddNoteForLocation(note.Location, note);
  9. foreach (var prevNote in prevNotes)
  10. {
  11. await responseStream.WriteAsync(prevNote);
  12. }
  13. }
  14. }

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

启动服务器

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

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

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

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

创建客户端

在这一部分,我们将会学习用RouteGuide创建一个 C# 客户端。可以在examples/csharp/route_guide/RouteGuideClient/Program.cs查看完整的客户端代码。

创建一个存根

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

首先需要为我们的存根创建一个可以连接到 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);
  3. // YOUR CODE GOES HERE
  4. 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 获取方法的结果。

  1. using (var call = client.RecordRoute())
  2. {
  3. foreach (var point in points)
  4. {
  5. await call.RequestStream.WriteAsync(point);
  6. }
  7. await call.RequestStream.CompleteAsync();
  8. RouteSummary summary = await call.ResponseAsync;
  9. }

最后,让我们看看双向流式 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. });
  11. foreach (RouteNote request in requests)
  12. {
  13. await call.RequestStream.WriteAsync(request);
  14. }
  15. await call.RequestStream.CompleteAsync();
  16. await responseReaderTask;
  17. }

来试试吧!

构建客户端和服务器:

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

  • 运行服务器,它会监听50052端口:

> cd RouteGuideServer/bin/Debug
> RouteGuideServer.exe

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

> cd RouteGuideClient/bin/Debug
> RouteGuideClient.exe

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

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

原文:

http://doc.oschina.net/grpc?t=60132