mirror of https://github.com/grpc/grpc.git
Michael Lumish
10 years ago
commit
3637455d95
22 changed files with 4105 additions and 0 deletions
@ -0,0 +1,5 @@ |
||||
bin/ |
||||
obj/ |
||||
packages/ |
||||
*.suo |
||||
*.userprefs |
||||
@ -0,0 +1,392 @@ |
||||
#gRPC Basics: C# |
||||
|
||||
This tutorial provides a basic C# programmer's introduction to working with gRPC. By walking through this example you'll learn how to: |
||||
|
||||
- Define a service in a .proto file. |
||||
- Generate server and client code using the protocol buffer compiler. |
||||
- Use the C# gRPC API to write a simple client and server for your service. |
||||
|
||||
It assumes that you have read the [Getting started](https://github.com/grpc/grpc-common) guide and are familiar with [protocol buffers] (https://developers.google.com/protocol-buffers/docs/overview). Note that the example in this tutorial only uses the proto2 version of the protocol buffers language, as proto3 support for C# is not ready yet (see [protobuf C# README](https://github.com/google/protobuf/tree/master/csharp#proto2--proto3)). |
||||
|
||||
This isn't a comprehensive guide to using gRPC in C#: more reference documentation is coming soon. |
||||
|
||||
## Why use gRPC? |
||||
|
||||
Our example is a simple route mapping application that lets clients get information about features on their route, create a summary of their route, and exchange route information such as traffic updates with the server and other clients. |
||||
|
||||
With gRPC we can define our service once in a .proto file and implement clients and servers in any of gRPC's supported languages, which in turn can be run in environments ranging from servers inside Google to your own tablet - all the complexity of communication between different languages and environments is handled for you by gRPC. We also get all the advantages of working with protocol buffers, including efficient serialization, a simple IDL, and easy interface updating. |
||||
|
||||
## Example code and setup |
||||
|
||||
The example code for our tutorial is in [grpc/grpc-common/csharp/route_guide](https://github.com/grpc/grpc-common/tree/master/csharp/route_guide). To download the example, clone the `grpc-common` repository by running the following command: |
||||
```shell |
||||
$ git clone https://github.com/google/grpc-common.git |
||||
``` |
||||
|
||||
All the files for this tutorial are in the directory `grpc-common/csharp/route_guide`. |
||||
Open the solution `grpc-common/csharp/route_guide/RouteGuide.sln` from Visual Studio (or Monodevelop on Linux). |
||||
|
||||
You also should have the relevant tools installed to generate the server and client interface code. |
||||
|
||||
**TODO: more on how to install protoc** |
||||
|
||||
## Defining the service |
||||
|
||||
Our first step (as you'll know from [Getting started](https://github.com/grpc/grpc-common)) is to define the gRPC *service* and the method *request* and *response* types using [protocol buffers] (https://developers.google.com/protocol-buffers/docs/overview). You can see the complete .proto file in [`grpc-common/csharp/route_guide/RouteGuide/protos/route_guide.proto`](https://github.com/grpc/grpc-common/blob/master/sharp/route_guide/RouteGuide/protos/route_guide.proto). |
||||
|
||||
To define a service, you specify a named `service` in your .proto file: |
||||
|
||||
```protobuf |
||||
service RouteGuide { |
||||
... |
||||
} |
||||
``` |
||||
|
||||
Then you define `rpc` methods inside your service definition, specifying their request and response types. gRPC lets you define four kinds of service method, all of which are used in the `RouteGuide` service: |
||||
|
||||
- A *simple RPC* where the client sends a request to the server using the stub and waits for a response to come back, just like a normal function call. |
||||
```protobuf |
||||
// Obtains the feature at a given position. |
||||
rpc GetFeature(Point) returns (Feature) {} |
||||
``` |
||||
|
||||
- A *server-side streaming RPC* where the client sends a request to the server and gets a stream to read a sequence of messages back. The client reads from the returned stream until there are no more messages. As you can see in our example, you specify a server-side streaming method by placing the `stream` keyword before the *response* type. |
||||
```protobuf |
||||
// 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) {} |
||||
``` |
||||
|
||||
- A *client-side streaming RPC* where the client writes a sequence of messages and sends them to the server, again using a provided stream. Once the client has finished writing the messages, it waits for the server to read them all and return its response. You specify a server-side streaming method by placing the `stream` keyword before the *request* type. |
||||
```protobuf |
||||
// Accepts a stream of Points on a route being traversed, returning a |
||||
// RouteSummary when traversal is completed. |
||||
rpc RecordRoute(stream Point) returns (RouteSummary) {} |
||||
``` |
||||
|
||||
- A *bidirectional streaming RPC* where both sides send a sequence of messages using a read-write stream. The two streams operate independently, so clients and servers can read and write in whatever order they like: for example, the server could wait to receive all the client messages before writing its responses, or it could alternately read a message then write a message, or some other combination of reads and writes. The order of messages in each stream is preserved. You specify this type of method by placing the `stream` keyword before both the request and the response. |
||||
```protobuf |
||||
// 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) {} |
||||
``` |
||||
|
||||
Our .proto file also contains protocol buffer message type definitions for all the request and response types used in our service methods - for example, here's the `Point` message type: |
||||
```protobuf |
||||
// 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; |
||||
} |
||||
``` |
||||
|
||||
|
||||
## Generating client and server code |
||||
|
||||
Next we need to generate the gRPC client and server interfaces from our .proto service definition. We do this using the protocol buffer compiler `protoc` with a special gRPC C# plugin. |
||||
|
||||
If you want to run this yourself, make sure you've installed protoc and followed the gRPC C# plugin [installation instructions](https://github.com/grpc/grpc/blob/master/INSTALL) first. |
||||
|
||||
**TODO: more on how to install protoc and grpc_csharp_plugin** |
||||
|
||||
Once that's done, the following command can be used to generate the C# code. |
||||
|
||||
```shell |
||||
$ protoc -I RouteGuide/protos --csharp_out=RouteGuide --grpc_out=RouteGuide --plugin=protoc-gen-grpc=`which grpc_csharp_plugin` RouteGuide/protos/route_guide.proto |
||||
``` |
||||
|
||||
**TODO: command for windows** |
||||
|
||||
Running this command regenerates the following files in the RouteGuide directory: |
||||
- `RouteGuide/RouteGuide.cs` defines a namespace `examples` |
||||
- This contains all the protocol buffer code to populate, serialize, and retrieve our request and response message types |
||||
- `RouteGuide/RouteGuideGrpc.cs`, provides stub and service classes |
||||
- an interface `RouteGuide.IRouteGuide` to inherit from when defining RouteGuide service implementations |
||||
- a class `RouteGuide.RouteGuideClient` that can be used to access remote RouteGuide instances |
||||
|
||||
|
||||
<a name="server"></a> |
||||
## Creating the server |
||||
|
||||
First let's look at how we create a `RouteGuide` server. If you're only interested in creating gRPC clients, you can skip this section and go straight to [Creating the client](#client) (though you might find it interesting anyway!). |
||||
|
||||
There are two parts to making our `RouteGuide` service do its job: |
||||
- Implementing the service interface generated from our service definition: doing the actual "work" of our service. |
||||
- Running a gRPC server to listen for requests from clients and return the service responses. |
||||
|
||||
You can find our example `RouteGuide` server in [grpc-common/csharp/route_guide/RouteGuideServer/RouteGuideImpl.cs](https://github.com/grpc/grpc-common/blob/master/csharp/route_guide/RouteGuideServer/RouteGuideServerImpl.cs). Let's take a closer look at how it works. |
||||
|
||||
### Implementing RouteGuide |
||||
|
||||
As you can see, our server has a `RouteGuideImpl` class that implements the generated `RouteGuide.IRouteGuide`: |
||||
|
||||
```csharp |
||||
// RouteGuideImpl provides an implementation of the RouteGuide service. |
||||
public class RouteGuideImpl : RouteGuide.IRouteGuide |
||||
``` |
||||
|
||||
`RouteGuideImpl` implements all our service methods. Let's look at the simplest type first, `GetFeature`, which just gets a `Point` from the client and returns the corresponding feature information from its database in a `Feature`. |
||||
|
||||
```csharp |
||||
public Task<Feature> GetFeature(Grpc.Core.ServerCallContext context, Point request) |
||||
{ |
||||
return Task.FromResult(CheckFeature(request)); |
||||
} |
||||
``` |
||||
|
||||
The method is passed a context for the RPC (which is empty in the alpha release), the client's `Point` protocol buffer request, and returns a `Feature` protocol buffer. In the method we create the `Feature` with the appropriate information, and then return it. To allow asynchronous |
||||
implementation, the method returns `Task<Feature>` rather than just `Feature`. You are free to perform your computations synchronously and return |
||||
the result once you've finished, just as we do in the example. |
||||
|
||||
Now let's look at something a bit more complicated - a streaming RPC. `ListFeatures` is a server-side streaming RPC, so we need to send back multiple `Feature` protocol buffers to our client. |
||||
|
||||
```csharp |
||||
// in RouteGuideImpl |
||||
public async Task ListFeatures(Grpc.Core.ServerCallContext context, Rectangle request, |
||||
Grpc.Core.IServerStreamWriter<Feature> responseStream) |
||||
{ |
||||
int left = Math.Min(request.Lo.Longitude, request.Hi.Longitude); |
||||
int right = Math.Max(request.Lo.Longitude, request.Hi.Longitude); |
||||
int top = Math.Max(request.Lo.Latitude, request.Hi.Latitude); |
||||
int bottom = Math.Min(request.Lo.Latitude, request.Hi.Latitude); |
||||
|
||||
foreach (var feature in features) |
||||
{ |
||||
if (!RouteGuideUtil.Exists(feature)) |
||||
{ |
||||
continue; |
||||
} |
||||
|
||||
int lat = feature.Location.Latitude; |
||||
int lon = feature.Location.Longitude; |
||||
if (lon >= left && lon <= right && lat >= bottom && lat <= top) |
||||
{ |
||||
await responseStream.WriteAsync(feature); |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
As you can see, here the request object is a `Rectangle` in which our client wants to find `Feature`s, but instead of returning a simple response we need to write responses to an asynchronous stream `IServerStreamWriter` using async method `WriteAsync`. |
||||
|
||||
Similarly, the client-side streaming method `RecordRoute` uses an [IAsyncEnumerator](https://github.com/Reactive-Extensions/Rx.NET/blob/master/Ix.NET/Source/System.Interactive.Async/IAsyncEnumerator.cs), to read the stream of requests using async method `MoveNext` and property `Current`. |
||||
|
||||
```csharp |
||||
public async Task<RouteSummary> RecordRoute(Grpc.Core.ServerCallContext context, |
||||
Grpc.Core.IAsyncStreamReader<Point> requestStream) |
||||
{ |
||||
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 (RouteGuideUtil.Exists(CheckFeature(point))) |
||||
{ |
||||
featureCount++; |
||||
} |
||||
if (previous != null) |
||||
{ |
||||
distance += (int) CalcDistance(previous, point); |
||||
} |
||||
previous = point; |
||||
} |
||||
|
||||
stopwatch.Stop(); |
||||
return RouteSummary.CreateBuilder().SetPointCount(pointCount) |
||||
.SetFeatureCount(featureCount).SetDistance(distance) |
||||
.SetElapsedTime((int) (stopwatch.ElapsedMilliseconds / 1000)).Build(); |
||||
} |
||||
``` |
||||
Finally, let's look at our bidirectional streaming RPC `RouteChat`. |
||||
|
||||
```csharp |
||||
public async Task RouteChat(Grpc.Core.ServerCallContext context, |
||||
Grpc.Core.IAsyncStreamReader<RouteNote> requestStream, Grpc.Core.IServerStreamWriter<RouteNote> responseStream) |
||||
{ |
||||
while (await requestStream.MoveNext()) |
||||
{ |
||||
var note = requestStream.Current; |
||||
List<RouteNote> notes = GetOrCreateNotes(note.Location); |
||||
|
||||
List<RouteNote> prevNotes; |
||||
lock (notes) |
||||
{ |
||||
prevNotes = new List<RouteNote>(notes); |
||||
} |
||||
|
||||
foreach (var prevNote in prevNotes) |
||||
{ |
||||
await responseStream.WriteAsync(prevNote); |
||||
} |
||||
|
||||
lock (notes) |
||||
{ |
||||
notes.Add(note); |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
Here the method receives both `requestStream` and `responseStream` as an argument. Reading the requests is done in a same way as in the `RecordRoute` example. Writing the responses is done the same way as in the `ListFeatures` example. |
||||
|
||||
### Starting the server |
||||
|
||||
Once we've implemented all our methods, we also need to start up a gRPC server so that clients can actually use our service. The following snippet shows how we do this for our `RouteGuide` service: |
||||
|
||||
```csharp |
||||
var features = RouteGuideUtil.ParseFeatures(RouteGuideUtil.DefaultFeaturesFile); |
||||
GrpcEnvironment.Initialize(); |
||||
|
||||
Server server = new Server(); |
||||
server.AddServiceDefinition(RouteGuide.BindService(new RouteGuideImpl(features))); |
||||
int port = server.AddListeningPort("localhost", 50052); |
||||
server.Start(); |
||||
|
||||
Console.WriteLine("RouteGuide server listening on port " + port); |
||||
Console.WriteLine("Press any key to stop the server..."); |
||||
Console.ReadKey(); |
||||
|
||||
server.ShutdownAsync().Wait(); |
||||
GrpcEnvironment.Shutdown(); |
||||
``` |
||||
As you can see, we build and start our server using `Grpc.Core.Server` class. To do this, we: |
||||
|
||||
1. Create an instance of `Grpc.Core.Server`. |
||||
1. Create an instance of our service implementation class `RouteGuideImpl`. |
||||
3. Register our service implementation with the server using method `AddServiceDefinition` and the generated method `RouteGuide.BindService`. |
||||
2. Specify the address and port we want to use to listen for client requests using the `AddListeningPort` method. |
||||
4. Call `Start` on the server instance to start an RPC server for our service. |
||||
|
||||
<a name="client"></a> |
||||
## Creating the client |
||||
|
||||
In this section, we'll look at creating a C# client for our `RouteGuide` service. You can see our complete example client code in [grpc-common/csharp/route_guide/RouteGuideClient/Program.cs](https://github.com/grpc/grpc-common/blob/master/csharp/route_guide/RouteGuideClient/Program.cs). |
||||
|
||||
### Creating a stub |
||||
|
||||
To call service methods, we first need to create a *stub*. |
||||
|
||||
First, we need to create a gRPC client channel that will connect to gRPC server. Then, we use the `RouteGuide.NewStub` method of the `RouteGuide` class generated from our .proto. |
||||
|
||||
```csharp |
||||
GrpcEnvironment.Initialize(); |
||||
|
||||
using (Channel channel = new Channel("127.0.0.1:50052")) |
||||
{ |
||||
var client = RouteGuide.NewStub(channel); |
||||
|
||||
// YOUR CODE GOES HERE |
||||
} |
||||
|
||||
GrpcEnvironment.Shutdown(); |
||||
``` |
||||
|
||||
### Calling service methods |
||||
|
||||
Now let's look at how we call our service methods. gRPC C# provides asynchronous versions of each of the supported method types. For convenience, |
||||
gRPC C# also provides a synchronous method stub, but only for simple (single request/single response) RPCs. |
||||
|
||||
#### Simple RPC |
||||
|
||||
Calling the simple RPC `GetFeature` in a synchronous way is nearly as straightforward as calling a local method. |
||||
|
||||
```csharp |
||||
Point request = Point.CreateBuilder().SetLatitude(409146138).SetLongitude(-746188906).Build(); |
||||
Feature feature = client.GetFeature(request); |
||||
``` |
||||
|
||||
As you can see, we create and populate a request protocol buffer object (in our case `Point`), and call the desired method on the client object, passing it the request. If the RPC finishes with success, the response protocol buffer (in our case `Feature`) will be returned. Otherwise, an exception of type `RpcException` will be thrown, indicating the status code of the problem. |
||||
|
||||
Alternatively, if you are in async context, you can call an asynchronous version of the method (and use `await` keyword to await the result): |
||||
```csharp |
||||
Point request = Point.CreateBuilder().SetLatitude(409146138).SetLongitude(-746188906).Build(); |
||||
Feature feature = await client.GetFeatureAsync(request); |
||||
``` |
||||
|
||||
#### Streaming RPCs |
||||
|
||||
Now let's look at our streaming methods. If you've already read [Creating the server](#server) some of this may look very familiar - streaming RPCs are implemented in a similar way on both sides. The difference with respect to simple call is that the client methods return an instance of a call object, that provides access to request/response streams and/or asynchronous result (depending on the streaming type you are using). |
||||
|
||||
Here's where we call the server-side streaming method `ListFeatures`, which has property `ReponseStream` of type `IAsyncEnumerator<Feature>` |
||||
|
||||
```csharp |
||||
using (var call = client.ListFeatures(request)) |
||||
{ |
||||
while (await call.ResponseStream.MoveNext()) |
||||
{ |
||||
Feature feature = call.ResponseStream.Current; |
||||
Console.WriteLine("Received " + feature.ToString()); |
||||
} |
||||
} |
||||
``` |
||||
|
||||
The client-side streaming method `RecordRoute` is similar, except we use the property `RequestStream` to write the requests one by one using `WriteAsync` and eventually signal that no more request will be send using `CompleteAsync`. The method result can be obtained through the property |
||||
`Result`. |
||||
```csharp |
||||
using (var call = client.RecordRoute()) |
||||
{ |
||||
foreach (var point in points) |
||||
{ |
||||
await call.RequestStream.WriteAsync(point); |
||||
} |
||||
await call.RequestStream.CompleteAsync(); |
||||
|
||||
RouteSummary summary = await call.Result; |
||||
} |
||||
``` |
||||
|
||||
Finally, let's look at our bidirectional streaming RPC `RouteChat`. In this case, we write the request to `RequestStream` and receive the responses from `ResponseStream`. As you can see from the example, the streams are independent of each other. |
||||
|
||||
```csharp |
||||
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; |
||||
} |
||||
``` |
||||
|
||||
## Try it out! |
||||
|
||||
Build client and server: |
||||
|
||||
Open the solution `grpc-common/csharp/route_guide/RouteGuide.sln` from Visual Studio (or Monodevelop on Linux) and hit "Build". |
||||
|
||||
Run the server, which will listen on port 50052: |
||||
``` |
||||
> cd RouteGuideServer/bin/Debug |
||||
> RouteGuideServer.exe |
||||
``` |
||||
|
||||
Run the client (in a different terminal): |
||||
``` |
||||
> cd RouteGuideClient/bin/Debug |
||||
> RouteGuideClient.exe |
||||
``` |
||||
|
||||
You can also run the server and client directly from Visual Studio. |
||||
|
||||
On Linux or Mac, use `mono RouteGuideServer.exe` and `mono RouteGuideClient.exe` to run the server and client. |
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,123 @@ |
||||
// Generated by the protocol buffer compiler. DO NOT EDIT! |
||||
// source: route_guide.proto |
||||
#region Designer generated code |
||||
|
||||
using System; |
||||
using System.Threading; |
||||
using System.Threading.Tasks; |
||||
using Grpc.Core; |
||||
|
||||
namespace examples { |
||||
public static class RouteGuide |
||||
{ |
||||
static readonly string __ServiceName = "examples.RouteGuide"; |
||||
|
||||
static readonly Marshaller<global::examples.Point> __Marshaller_Point = Marshallers.Create((arg) => arg.ToByteArray(), global::examples.Point.ParseFrom); |
||||
static readonly Marshaller<global::examples.Feature> __Marshaller_Feature = Marshallers.Create((arg) => arg.ToByteArray(), global::examples.Feature.ParseFrom); |
||||
static readonly Marshaller<global::examples.Rectangle> __Marshaller_Rectangle = Marshallers.Create((arg) => arg.ToByteArray(), global::examples.Rectangle.ParseFrom); |
||||
static readonly Marshaller<global::examples.RouteSummary> __Marshaller_RouteSummary = Marshallers.Create((arg) => arg.ToByteArray(), global::examples.RouteSummary.ParseFrom); |
||||
static readonly Marshaller<global::examples.RouteNote> __Marshaller_RouteNote = Marshallers.Create((arg) => arg.ToByteArray(), global::examples.RouteNote.ParseFrom); |
||||
|
||||
static readonly Method<global::examples.Point, global::examples.Feature> __Method_GetFeature = new Method<global::examples.Point, global::examples.Feature>( |
||||
MethodType.Unary, |
||||
"GetFeature", |
||||
__Marshaller_Point, |
||||
__Marshaller_Feature); |
||||
|
||||
static readonly Method<global::examples.Rectangle, global::examples.Feature> __Method_ListFeatures = new Method<global::examples.Rectangle, global::examples.Feature>( |
||||
MethodType.ServerStreaming, |
||||
"ListFeatures", |
||||
__Marshaller_Rectangle, |
||||
__Marshaller_Feature); |
||||
|
||||
static readonly Method<global::examples.Point, global::examples.RouteSummary> __Method_RecordRoute = new Method<global::examples.Point, global::examples.RouteSummary>( |
||||
MethodType.ClientStreaming, |
||||
"RecordRoute", |
||||
__Marshaller_Point, |
||||
__Marshaller_RouteSummary); |
||||
|
||||
static readonly Method<global::examples.RouteNote, global::examples.RouteNote> __Method_RouteChat = new Method<global::examples.RouteNote, global::examples.RouteNote>( |
||||
MethodType.DuplexStreaming, |
||||
"RouteChat", |
||||
__Marshaller_RouteNote, |
||||
__Marshaller_RouteNote); |
||||
|
||||
// client-side stub interface |
||||
public interface IRouteGuideClient |
||||
{ |
||||
global::examples.Feature GetFeature(global::examples.Point request, CancellationToken token = default(CancellationToken)); |
||||
Task<global::examples.Feature> GetFeatureAsync(global::examples.Point request, CancellationToken token = default(CancellationToken)); |
||||
AsyncServerStreamingCall<global::examples.Feature> ListFeatures(global::examples.Rectangle request, CancellationToken token = default(CancellationToken)); |
||||
AsyncClientStreamingCall<global::examples.Point, global::examples.RouteSummary> RecordRoute(CancellationToken token = default(CancellationToken)); |
||||
AsyncDuplexStreamingCall<global::examples.RouteNote, global::examples.RouteNote> RouteChat(CancellationToken token = default(CancellationToken)); |
||||
} |
||||
|
||||
// server-side interface |
||||
public interface IRouteGuide |
||||
{ |
||||
Task<global::examples.Feature> GetFeature(ServerCallContext context, global::examples.Point request); |
||||
Task ListFeatures(ServerCallContext context, global::examples.Rectangle request, IServerStreamWriter<global::examples.Feature> responseStream); |
||||
Task<global::examples.RouteSummary> RecordRoute(ServerCallContext context, IAsyncStreamReader<global::examples.Point> requestStream); |
||||
Task RouteChat(ServerCallContext context, IAsyncStreamReader<global::examples.RouteNote> requestStream, IServerStreamWriter<global::examples.RouteNote> responseStream); |
||||
} |
||||
|
||||
// client stub |
||||
public class RouteGuideClient : AbstractStub<RouteGuideClient, StubConfiguration>, IRouteGuideClient |
||||
{ |
||||
public RouteGuideClient(Channel channel) : this(channel, StubConfiguration.Default) |
||||
{ |
||||
} |
||||
public RouteGuideClient(Channel channel, StubConfiguration config) : base(channel, config) |
||||
{ |
||||
} |
||||
public global::examples.Feature GetFeature(global::examples.Point request, CancellationToken token = default(CancellationToken)) |
||||
{ |
||||
var call = CreateCall(__ServiceName, __Method_GetFeature); |
||||
return Calls.BlockingUnaryCall(call, request, token); |
||||
} |
||||
public Task<global::examples.Feature> GetFeatureAsync(global::examples.Point request, CancellationToken token = default(CancellationToken)) |
||||
{ |
||||
var call = CreateCall(__ServiceName, __Method_GetFeature); |
||||
return Calls.AsyncUnaryCall(call, request, token); |
||||
} |
||||
public AsyncServerStreamingCall<global::examples.Feature> ListFeatures(global::examples.Rectangle request, CancellationToken token = default(CancellationToken)) |
||||
{ |
||||
var call = CreateCall(__ServiceName, __Method_ListFeatures); |
||||
return Calls.AsyncServerStreamingCall(call, request, token); |
||||
} |
||||
public AsyncClientStreamingCall<global::examples.Point, global::examples.RouteSummary> RecordRoute(CancellationToken token = default(CancellationToken)) |
||||
{ |
||||
var call = CreateCall(__ServiceName, __Method_RecordRoute); |
||||
return Calls.AsyncClientStreamingCall(call, token); |
||||
} |
||||
public AsyncDuplexStreamingCall<global::examples.RouteNote, global::examples.RouteNote> RouteChat(CancellationToken token = default(CancellationToken)) |
||||
{ |
||||
var call = CreateCall(__ServiceName, __Method_RouteChat); |
||||
return Calls.AsyncDuplexStreamingCall(call, token); |
||||
} |
||||
} |
||||
|
||||
// creates service definition that can be registered with a server |
||||
public static ServerServiceDefinition BindService(IRouteGuide serviceImpl) |
||||
{ |
||||
return ServerServiceDefinition.CreateBuilder(__ServiceName) |
||||
.AddMethod(__Method_GetFeature, serviceImpl.GetFeature) |
||||
.AddMethod(__Method_ListFeatures, serviceImpl.ListFeatures) |
||||
.AddMethod(__Method_RecordRoute, serviceImpl.RecordRoute) |
||||
.AddMethod(__Method_RouteChat, serviceImpl.RouteChat).Build(); |
||||
} |
||||
|
||||
// creates a new client stub |
||||
public static IRouteGuideClient NewStub(Channel channel) |
||||
{ |
||||
return new RouteGuideClient(channel); |
||||
} |
||||
|
||||
// creates a new client stub |
||||
public static IRouteGuideClient NewStub(Channel channel, StubConfiguration config) |
||||
{ |
||||
return new RouteGuideClient(channel, config); |
||||
} |
||||
} |
||||
} |
||||
#endregion |
||||
@ -0,0 +1,123 @@ |
||||
// Copyright 2015, Google Inc. |
||||
// All rights reserved. |
||||
// |
||||
// Redistribution and use in source and binary forms, with or without |
||||
// modification, are permitted provided that the following conditions are |
||||
// met: |
||||
// |
||||
// * Redistributions of source code must retain the above copyright |
||||
// notice, this list of conditions and the following disclaimer. |
||||
// * Redistributions in binary form must reproduce the above |
||||
// copyright notice, this list of conditions and the following disclaimer |
||||
// in the documentation and/or other materials provided with the |
||||
// distribution. |
||||
// * Neither the name of Google Inc. nor the names of its |
||||
// contributors may be used to endorse or promote products derived from |
||||
// this software without specific prior written permission. |
||||
// |
||||
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
||||
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
||||
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
||||
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
||||
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
||||
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
||||
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
||||
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
||||
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
||||
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
||||
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
||||
|
||||
// TODO(jtattermusch): as of now, C# protobufs don't officially support |
||||
// proto3. |
||||
syntax = "proto2"; |
||||
|
||||
package examples; |
||||
|
||||
// Interface exported by the server. |
||||
service RouteGuide { |
||||
// A simple RPC. |
||||
// |
||||
// Obtains the feature at a given position. |
||||
// |
||||
// A feature with an empty name is returned if there's no feature at the given |
||||
// position. |
||||
rpc GetFeature(Point) returns (Feature) {} |
||||
|
||||
// A server-to-client streaming RPC. |
||||
// |
||||
// 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) {} |
||||
|
||||
// A client-to-server streaming RPC. |
||||
// |
||||
// Accepts a stream of Points on a route being traversed, returning a |
||||
// RouteSummary when traversal is completed. |
||||
rpc RecordRoute(stream Point) returns (RouteSummary) {} |
||||
|
||||
// A Bidirectional streaming RPC. |
||||
// |
||||
// 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) {} |
||||
} |
||||
|
||||
// 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 { |
||||
optional int32 latitude = 1; |
||||
optional int32 longitude = 2; |
||||
} |
||||
|
||||
// A latitude-longitude rectangle, represented as two diagonally opposite |
||||
// points "lo" and "hi". |
||||
message Rectangle { |
||||
// One corner of the rectangle. |
||||
optional Point lo = 1; |
||||
|
||||
// The other corner of the rectangle. |
||||
optional Point hi = 2; |
||||
} |
||||
|
||||
// A feature names something at a given point. |
||||
// |
||||
// If a feature could not be named, the name is empty. |
||||
message Feature { |
||||
// The name of the feature. |
||||
optional string name = 1; |
||||
|
||||
// The point where the feature is detected. |
||||
optional Point location = 2; |
||||
} |
||||
|
||||
// A RouteNote is a message sent while at a given point. |
||||
message RouteNote { |
||||
// The location from which the message is sent. |
||||
optional Point location = 1; |
||||
|
||||
// The message to be sent. |
||||
optional string message = 2; |
||||
} |
||||
|
||||
// A RouteSummary is received in response to a RecordRoute rpc. |
||||
// |
||||
// It contains the number of individual points received, the number of |
||||
// detected features, and the total distance covered as the cumulative sum of |
||||
// the distance between each point. |
||||
message RouteSummary { |
||||
// The number of points received. |
||||
optional int32 point_count = 1; |
||||
|
||||
// The number of known features passed while traversing the route. |
||||
optional int32 feature_count = 2; |
||||
|
||||
// The distance covered in metres. |
||||
optional int32 distance = 3; |
||||
|
||||
// The duration of the traversal in seconds. |
||||
optional int32 elapsed_time = 4; |
||||
} |
||||
Loading…
Reference in new issue