This guide gets you started with gRPC in C# with a simple working example.
Whether you’re using Windows, OS X, or Linux, you can follow this example by using either an IDE and its build tools, or by using the the .NET Core SDK command line tools.
Using the .NET Core SDK on Windows, OS X, or Linux, you’ll need:
On Windows, using Visual Studio, you’ll need:
On OS X, using Xamarin Studio, you’ll need:
On Linux, using the Monodevelop IDE, you’ll need:
You’ll need a local copy of the example code to work through this quickstart. Download the example code from our Github repository (the following command clones the entire repository, but you just need the examples for this quickstart and other tutorials):
$ # Clone the repository to get the example code:
$ git clone -b v1.8.x https://github.com/grpc/grpc
$ cd grpc
examples/csharp/helloworld
.examples/csharp/helloworld-from-cli
.The example in this walkthrough already adds the necessary dependencies for you (Grpc, Grpc.Tools and Google.Protobuf NuGet packages).
Greeter.sln
with Visual Studio.Greeter.sln
with Xamarin Studio.From the examples/csharp/helloworld-from-cli
directory:
> dotnet restore
> dotnet build **/project.json
Using the Monodevelop IDE, you can build and edit a solution that uses gRPC without issues, but unfortunately a workaround is necessary in order to initially restore a NuGet dependency on C# gRPC.
The problem is that C# gRPC package currently depends on System.Interactive.Async 3.0.0, which requires NuGet 2.12+ to install. The NuGet included on the latest versions of Monodevelop is too old to install gRPC C#.
If you don’t want to change the version of NuGet that you’re using, a possible workaround to get these files is to download the NuGet package and unzip without a NuGet client, as follows.
examples/csharp/helloworld
directory, run /path/to/nuget restore
.From the examples/csharp/helloworld
directory:
> cd GreeterServer/bin/Debug
> GreeterServer.exe
> cd GreeterClient/bin/Debug
> GreeterClient.exe
You’ll need to run the above executables with “mono” if building on Xamarin Studio for OS X.
> cd GreeterServer
> dotnet run
> cd GreeterClient
> dotnet run
Congratulations! You’ve just run a client-server application with gRPC.
Now let’s look at how to update the application with an extra method on the
server for the client to call. Our gRPC service is defined using protocol
buffers; you can find out lots more about how to define a service in a .proto
file in gRPC Basics: C#. For now all you need to know is that both the
server and the client “stub” have a SayHello
RPC method that takes a
HelloRequest
parameter from the client and returns a HelloResponse
from the
server, and that this method is defined like this:
// The greeting service definition.
service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply) {}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings
message HelloReply {
string message = 1;
}
Let’s update this so that the Greeter
service has two methods. Edit
examples/protos/helloworld.proto
and update it with a new SayHelloAgain
method, with the same request and response types:
// The greeting service definition.
service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply) {}
// Sends another greeting
rpc SayHelloAgain (HelloRequest) returns (HelloReply) {}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings
message HelloReply {
string message = 1;
}
(Don’t forget to save the file!)
Next we need to update the gRPC code used by our application to use the new service definition.
The Grpc.Tools
NuGet package contains the protoc and protobuf C# plugin binaries you will need to generate the code.
This example project already depends on the Grpc.Tools.1.8.x
NuGet package, so it should be included in examples/csharp/helloworld/packages
when the Greeter.sln
solution is built from your IDE,
or when you restore packages via /path/to/nuget restore
on the command line.
$ mkdir packages && cd packages
$ /path/to/nuget install Grpc.Tools
NuGet 2.12 does not install the files from the Grpc.Tools
package necessary on Linux and OS X.
Without changing the version of NuGet that you’re using, a possible workaround to obtaining the binaries included in the Grpc.Tools
package
is by simply downloading the NuGet package and unzipping without a NuGet client, as follows.
From your example directory:
$ temp_dir=packages/Grpc.Tools.1.8.x/tmp
$ curl_url=https://www.nuget.org/api/v2/package/Grpc.Tools/
$ mkdir -p $temp_dir && cd $temp_dir && curl -sL $curl_url > tmp.zip; unzip tmp.zip && cd .. && cp -r tmp/tools . && rm -rf tmp && cd ../..
Note that you may have to change the platform_architecture
directory names (e.g. windows_x86, linux_x64) in the commands below based on your environment.
Note that you may also have to change the permissions of the protoc and protobuf
binaries in the Grpc.Tools
package under examples/csharp/helloworld/packages
to executable in order to run the commands below.
From the examples/csharp/helloworld
directory, or the examples/csharp/helloworld-from-cli
directory if using the .NET Core SDK:
Windows
> packages\Grpc.Tools.1.8.x\tools\windows_x86\protoc.exe -I../../protos --csharp_out Greeter --grpc_out Greeter ../../protos/helloworld.proto --plugin=protoc-gen-grpc=packages/Grpc.Tools.1.8.x/tools/windows_x86/grpc_csharp_plugin.exe
Linux (or OS X by using macosx_x64 directory)
$ packages/Grpc.Tools.1.8.x/tools/linux_x64/protoc -I../../protos --csharp_out Greeter --grpc_out Greeter ../../protos/helloworld.proto --plugin=protoc-gen-grpc=packages/Grpc.Tools.1.8.x/tools/linux_x64/grpc_csharp_plugin
Running the appropriate command for your OS regenerates the following files in the directory:
We now have new generated server and client code, but we still need to implement and call the new method in the human-written parts of our example application.
With the Greeter.sln
open in your IDE, open GreeterServer/Program.cs
.
Implement the new method by editing the GreeterImpl class like this:
class GreeterImpl : Greeter.GreeterBase
{
// Server side handler of the SayHello RPC
public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply { Message = "Hello " + request.Name });
}
// Server side handler for the SayHelloAgain RPC
public override Task<HelloReply> SayHelloAgain(HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply { Message = "Hello again " + request.Name });
}
}
With the same Greeter.sln
open in your IDE, open GreeterClient/Program.cs
.
Call the new method like this:
public static void Main(string[] args)
{
Channel channel = new Channel("127.0.0.1:50051", ChannelCredentials.Insecure);
var client = new Greeter.GreeterClient(channel);
String user = "you";
var reply = client.SayHello(new HelloRequest { Name = user });
Console.WriteLine("Greeting: " + reply.Message);
var secondReply = client.SayHelloAgain(new HelloRequest { Name = user });
Console.WriteLine("Greeting: " + secondReply.Message);
channel.ShutdownAsync().Wait();
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
}
Rebuild the newly modified example just like we first built the original example:
Just like we did before, from the examples/csharp/helloworld
directory:
> cd GreeterServer/bin/Debug
> GreeterServer.exe
> cd GreeterClient/bin/Debug
> GreeterClient.exe
Or if using the .NET Core SDK, from the examples/csharp/helloworld-from-cli
directory:
> cd GreeterServer
> dotnet run
> cd GreeterClient
> dotnet run