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代码库:

-  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:

service RouteGuide {
   ...
}

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

一个 简单 RPC ，客户端使用存根发送请求到服务器并等待响应返回，就像平常的函数调用一样。
```
   // Obtains the feature at a given position.
 rpc GetFeature(Point) returns (Feature) {}
```

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

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

一个 客户端流式 RPC ，客户端写入一个消息序列并将其发送到服务器，同样也是使用流。一旦客户端完成写入消息，它等待服务器完成读取返回它的响应。通过在请求类型前指定 stream 关键字来指定一个客户端的流方法。
```
  // Accepts a stream of Points on a route being traversed, returning a
// RouteSummary when traversal is completed.
rpc RecordRoute(stream Point) returns (RouteSummary) {}
```
一个 双向流式 RPC 是双方使用读写流去发送一个消息序列。两个流独立操作，因此客户端和服务器可以以任意喜欢的顺序读写：比如，服务器可以在写入响应前等待接收所有的客户端消息，或者可以交替的读取和写入消息，或者其他读写的组合。每个流中的消息顺序被预留。你可以通过在请求和响应前加 stream 关键字去制定方法的类型。
```
  // Accepts a stream of RouteNotes sent while a route is being traversed,
// while receiving other RouteNotes (e.g. from other users).
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
```

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

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

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

接下来我们需要从 .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 目录运行：

  > 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 类：

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

简单RPC

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

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

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

服务器端流式 RPC

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

// in RouteGuideImpl
public async Task ListFeatures(Rectangle request,
    Grpc.Core.IServerStreamWriter<Feature> responseStream,
    Grpc.Core.ServerCallContext context)
{
    var responses = features.FindAll( (feature) => feature.Exists() && request.Contains(feature.Location) );
    foreach (var response in responses)
    {
        await responseStream.WriteAsync(response);
    }
}

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

客户端流 RPC

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

public async Task<RouteSummary> RecordRoute(Grpc.Core.IAsyncStreamReader<Point> requestStream,
    Grpc.Core.ServerCallContext context)
{
    int pointCount = 0;
    int featureCount = 0;
    int distance = 0;
    Point previous = null;
    var stopwatch = new Stopwatch();
    stopwatch.Start();
    while (await requestStream.MoveNext())
    {
        var point = requestStream.Current;
        pointCount++;
        if (CheckFeature(point).Exists())
        {
            featureCount++;
        }
        if (previous != null)
        {
            distance += (int) previous.GetDistance(point);
        }
        previous = point;
    }
    stopwatch.Stop();
    return new RouteSummary
    {
        PointCount = pointCount,
        FeatureCount = featureCount,
        Distance = distance,
        ElapsedTime = (int)(stopwatch.ElapsedMilliseconds / 1000)
    };
}

双向流 RPC

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

public async Task RouteChat(Grpc.Core.IAsyncStreamReader<RouteNote> requestStream,
    Grpc.Core.IServerStreamWriter<RouteNote> responseStream,
    Grpc.Core.ServerCallContext context)
{
    while (await requestStream.MoveNext())
    {
        var note = requestStream.Current;
        List<RouteNote> prevNotes = AddNoteForLocation(note.Location, note);
        foreach (var prevNote in prevNotes)
        {
            await responseStream.WriteAsync(prevNote);
        }
    }
}

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

启动服务器

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

var features = RouteGuideUtil.ParseFeatures(RouteGuideUtil.DefaultFeaturesFile);
Server server = new Server
{
    Services = { RouteGuide.BindService(new RouteGuideImpl(features)) },
    Ports = { new ServerPort("localhost", Port, ServerCredentials.Insecure) }
};
server.Start();
Console.WriteLine("RouteGuide server listening on port " + port);
Console.WriteLine("Press any key to stop the server...");
Console.ReadKey();
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方法。

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

调用服务的方法

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

简单 RPC

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

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

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

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

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

流式 RPC

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

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

using (var call = client.ListFeatures(request))
{
    while (await call.ResponseStream.MoveNext())
    {
        Feature feature = call.ResponseStream.Current;
        Console.WriteLine("Received " + feature.ToString());
    }
}

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

using (var call = client.RecordRoute())
{
    foreach (var point in points)
    {
        await call.RequestStream.WriteAsync(point);
    }
    await call.RequestStream.CompleteAsync();
    RouteSummary summary = await call.ResponseAsync;
}

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

using (var call = client.RouteChat())
{
    var responseReaderTask = Task.Run(async () =>
    {
        while (await call.ResponseStream.MoveNext())
        {
            var note = call.ResponseStream.Current;
            Console.WriteLine("Received " + note);
        }
    });
    foreach (RouteNote request in requests)
    {
        await call.RequestStream.WriteAsync(request);
    }
    await call.RequestStream.CompleteAsync();
    await responseReaderTask;
}

来试试吧！

构建客户端和服务器：

用 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.exe 和 mono RouteGuideClient.exe 命令去运行服务器和客户端。

原文:

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

C# 教程