How to implement gRPC in ASP.NET Core

gRPC is a modern, open source, high performance, RPC framework that can run in any environment. It is developed by Google and is included from ASP.NET Core 3.0 version. In this tutorial we will create 2 apps:

1. .NET gRPC Service – it will be a gRPC server which will serve random jokes.
2. ASP.NET Core gRPC Client – that will call the gRPC Service to get random jokes.

gRPC has different types of methods and this tutorial will teach all of them in details. The gRPC method types are:

• Unary
• Server Streaming
• Client Streaming
• Bi-directional Streaming

Create a .NET gRPC Service

• First start the Visual Studio and select Create a new project.
• In the Create a new project dialog, select gRPC Service and select Next.
• Name the project as GrpcService.

Once the project is created examine the different project files, these are:

• greet.proto – this file is created inside the Protos folder. It is the protobuf file that defines the contract (like models, methods, etc) exposed by this gRPC Service. Protobuf is just a serialization/deserialization tool like JSON but is up to 6 times faster than JSON.
• GreeterService.cs – this file is created inside the ‘Services’ folder and contains the implementation of the gRPC service.
• appsettings.json – contains configuration data, such as protocol, used by Kestrel.
• Program.cs – contains the entry point for the gRPC service.
• Startup.cs – contains code that configures app behavior.

Note: in .NET 6.0 version or later, there will not be Startup.cs file. So all the gRPC configurations are going to be in Program.cs file.

Let us discuss each of these files one by one.

greet.proto

In the greet.proto file we define the gRPC service and all the methods which this service will contain. Since the contracts are defined in non C# syntaxes therefore in order to communicate with it, the .NET framework converts it to a C# based file.

You may ask how? The answer is when you build your solution in Visual Studio then a new file called Greet.cs is created at \obj\Debug\net6.0\Protos\Greet.cs. This file is auto generated by the compiler and contains implementation of greet.proto methods in C# syntaxes. We have shown the screenshot of this Greet.cs file below:

Now open the greet.proto file and find the default implementation of the service as:

syntax = "proto3";

option csharp_namespace = "GrpcService";

package greet;

// 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;
}

Notice the gRPC service is named as Greeter and contains just one method by the name of SayHello.

rpc SayHello (HelloRequest) returns (HelloReply);

This SayHello method accepts a parameter of HelloRequest type and returns data of HelloReply type. The HelloRequest and HelloReply types are defined as:

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

HelloRequest has just one member called ‘name’ of type string while HelloReply also has a single member called ‘message’ of type string.

This makes it quite clear that when we add a new method to the gRPC service make sure to add it inside the service Greeter {...} block and define it’s parameter and return type after the block.

Example: The code to add a new method called ‘DoWork’ is shown below:

service Greeter {
  rpc DoWork (SomeInput) returns (SomeOutput);
}

message SomeInput {
  …
}

message SomeOutput {
  …
}

You will understand more about this once you will create gRPC methods like Unary, Server and client streaming, Bi-directional streaming later in this tutorial.

GreeterService.cs

As stated earlier this class is created inside the ‘Services’ folder and contains the implementation of the gRPC service in C#. Whatever methods we define in the greet.proto file, we need to implement them in this class in C#.

Open this to find the SayHello method whose code is shown below:

public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
{
    return Task.FromResult(new HelloReply
    {
        Message = "Hello " + request.Name
    });
}

It’s just a simple method which returns a simple string message. Now suppose we need to implement a new method called ‘DoWork’. You do this by adding the below code to this class as shown below:

public override Task<SomeOutput> DoWork(SomeInput request, ServerCallContext context)
{
    //… return SomeOutput type
}

I will explain all about this later in the tutorial.

appsettings.json

Right now gRPC service can only be hosted in Kestrel and requires HTTP/2 protocol secured with TLS. In appsettings.json we define the Kestrel configuration.

In development we don’t have to modify anything in the appsettings.json file. But remember – when we host the gRPC service in Production then the Kestrel endpoints used for gRPC should be secured with TLS certificate. So the production appsettings.json file will look something like shown below:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://www.someurl.com",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
} 

Program.cs

When we use .NET 6.0 or later versions, all gRPC configurations are kept inside the “Program.cs” file since “Startup.cs” class is not there in these version. The Program file code will look as shown below:

using GrpcService.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS,
// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints");

app.Run();

Here the gRPC is added to the service collection through the code –

builder.Services.AddGrpc();

Then the mappings of incoming request is done by the code:

app.MapGrpcService<GreeterService>();

Startup.cs

In .NET 5 or earlier versions the gRPC configurations are kept in Startup.cs file. Open this file and see –

• In the ConfigureServices method the gRPC is enabled with the AddGrpc method.
• In the Configure method the gRPC service is added to the routing pipeline through the MapGrpcService method.

See the below code where these methods are shown:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // after app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGrpcService<GreeterService>();

        endpoints.MapGet("/", async context =>
        {
            await context.Response.WriteAsync("Communication with gRPC endpoints");
        });
    });
}

We have now completely understood how gRPC works in .NET so now move forward and do some real building of gRPC stuffs.

In this tutorial we will build a gRPC Service .NET core app that will return random JOKES to the client. It will have 4 methods of types:

• Unary Call
• Server Streaming Call
• Client Streaming Call
• Bi-directional Streaming Call

This gRPC service will be called from a client project (we will build client app in just a moment). The gRPC Client app will be an ASP.NET Core Web Application.

Unary Call example

A simplest gRPC method type is a Unary Call which starts with the client sending a request message. A response message is returned by the gRPC service.

Let us create a gRPC Unary Call method that will return a JOKE to the client. Here the client will send the JOKE number to the gRPC service.

So in the “GrpcService” application, go to the greet.proto file and add a new service method called SendJoke and define it’s parameters and return type like:

// The service definition.
service Greeter {
  rpc SendJoke (JRequest) returns (JResponse);
}

// Joke request
message JRequest {
  int32 no = 1;
}

// Joke response
message JResponse {
  repeated Joke Joke = 1;
}

// Joke
message Joke {
  string author = 1;
  string description = 2;
}

 The work of the SendJoke gRPC method is to send a JOKE to the client based on the JOKE number which the client sends to the service. So we have defined the JOKE number as a member of the “JRequest”.

message JRequest {
  int32 no = 1;
}

// Joke response
message JResponse {
  repeated Joke Joke = 1;
}

// Joke
message Joke {
  string author = 1;
  string description = 2;
}

Now build the app by pressing the F6 key so that Greet.cs is auto updated by the compiler, and the SendJoke method is generated in that file.

Next, open the GreeterService.cs file and implement the SendJoke method. The code which needs to add to it is given below:

public override Task<JResponse> SendJoke(JRequest request, ServerCallContext context)
{
    List<Joke> jokeList = JokeRepo();

    JResponse jRes = new JResponse();
    jRes.Joke.AddRange(jokeList.Skip(request.No-1).Take(1));

    return Task.FromResult(jRes);
}

public List<Joke> JokeRepo()
{
    List<Joke> jokeList = new List<Joke> 
    {
        new Joke { Author = "Random", Description = "I ate a clock yesterday, it was very time-consuming"},
        new Joke { Author = "Xeno", Description = "Have you played the updated kids' game? I Spy With My Little Eye ... Phone"},
        new Joke { Author = "Jak", Description = "A perfectionist walked into a bar...apparently, the bar wasn’t set high enough"},
        new Joke { Author = "Peta", Description = "To be or not to be a horse rider, that is equestrian"},
        new Joke { Author = "Katnis", Description = "What does a clam do on his birthday? He shellabrates"}
    };

    return jokeList;
}

The SendJoke() method that has 2 parameters:

• 1. JRequest request
• 2. ServerCallContext context – The ServerCallContext argument is passed to each gRPC method and provides access to some HTTP/2 message data, such as the method, host, header, and trailers.

W eaccess the joke number from the JRequest object and fetch the joke from a Joke repository. The joke is first adding it to a JResponse object and then returned at the end of the code:

List<Joke> jokeList = JokeRepo();
JResponse jRes = new JResponse();
jRes.Joke.AddRange(jokeList.Skip(request.No-1).Take(1));
return Task.FromResult(jRes);

Create ASP.NET Core gRPC Client

Let us now make a client app that will call the gRPC service. Open a new instance of Visual Studio and create a new ASP.NET Core (Model-View-Controller) Web app. Name this app as GrpcClient.

Now install the following NuGet packages on this app.

• Grpc.Net.Client, which contains the .NET Core client.
• Google.Protobuf, which contains protobuf message APIs for C#.
• Grpc.Tools, which contains C# tooling support for protobuf files.

Simpley run these 3 powershell commands to install these packages:

Install-Package Grpc.Net.Client
Install-Package Google.Protobuf
Install-Package Grpc.Tools	

After this edit the project file (by right clicking the project name on the Solution explorer and select ‘Edit Project File’), and then add an item group with a Protobuf element that refers to the greet.proto file:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
</ItemGroup>

We also have to provide this client app with the greet.proto file. It should be exactly same to that of the gRPC service app so simply copy the ‘Protos’ folder that contains the greet.proto file from the gRPC service app and paste it to the root of this client app.

With this the client is ready to make the gRPC call to the service app. So go to the controller (I am using HomeController.cs in my case) and add the following namespaces to it.

using Grpc.Net.Client;
using GrpcService;

Then add an action method called Unary, and a function called ChangetoDictionary to the home controller. Check the below code:

public async Task<IActionResult> Unary()
{
    var channel = GrpcChannel.ForAddress("https://localhost:7199");
    var client = new Greeter.GreeterClient(channel);
    var reply = await client.SendJokeAsync(new JRequest { No = 3 });

    return View("ShowJoke", (object)ChangetoDictionary(reply));
}

private Dictionary<string, string> ChangetoDictionary(JResponse response)
{
    Dictionary<string, string> jokeDict = new Dictionary<string, string>();
    foreach (Joke joke in response.Joke)
        jokeDict.Add(joke.Author, joke.Description);
    return jokeDict;
} 

A gRPC client is created from a channel. The method called GrpcChannel.ForAddress is used to create a channel, and then this channel is used to create a gRPC client. We provided the address of the gRPC Service which is https://localhost:7199. After this the call to the service is made asynchronously as shown below:

var reply = await client.SendJokeAsync(new JRequest { No = 3 });

Note tha in the above code we requested the Joke Number 3 from the gRPC Service.

The work of the ChangetoDictionary method is to convert the JResponse object sent by the gRPC service to the Dictionary<string, string>() type.

In the last line we returned this dictionary that contains jokes to the view called ‘ShowJoke’. The view will display these jokes on the browser.

return View("ShowJoke", (object)ChangetoDictionary(reply));

Next, create ShowJoke razor view inside the Views/Shared folder and add the following code to it:

@{
    ViewData["Title"] = "ShowJoke";
}

<h1>ShowJoke</h1>

@model Dictionary<string, string>

<table class="table table-bordered table-sm table-striped">
    <thead>
        <tr>
            <th>Author</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        @foreach (var p in Model)
        {
            <tr>
                <td>@p.Key</td>
                <td>@p.Value</td>
            </tr>
        }
    </tbody>
</table>

It’s time to run and see how the client performs. So first make sure your gRPC service app is in running state. Then run the client app and open the URL https://localhost:7064/Home/Unary to initiate the ShowJoke action.

We will see the Joke number 3 is fetched and displayed as shown in the below image:

Congrats we successfully created Unary gRPC method and called it from ASP.NET Core client app. Next we will cover:

• Server Streaming Call
• Client Streaming Call
• Bi-directional Streaming Call

Server Streaming Call example

The server streaming call works like this way:

• The client sends a request to the server and receives a stream of messages in return.
• The number of messages which will be streamed is determined by the server.
• The gRPC guarantees that the client receives the messages in the same order as they are sent from the server.

To understand it let us create a method for implementing the Server Streaming Call. So, go to the greet.proto file of the “GrpcService” project and add a new method called SendJokeSS.

service Greeter {
  rpc SendJoke (JRequest) returns (JResponse);
  rpc SendJokeSS (JRequest) returns (stream JResponse);
}

Note – since it is a server streaming case so we added the stream keyword for the JResponse return type.

Next, go to the GreeterService.cs file and do this method’s implementation by adding the following code to it.

public override async Task SendJokeSS(JRequest request, IServerStreamWriter<JResponse> responseStream, ServerCallContext context)
{
    List<Joke> jokeList = JokeRepo();
    JResponse jRes;

    var i = 0;
    while (!context.CancellationToken.IsCancellationRequested)
    {
        jRes = new JResponse();
        jRes.Joke.Add(jokeList.Skip(i).Take(request.No));
        await responseStream.WriteAsync(jRes);
        i++;
        // Gotta look busy (not needed in production)
        await Task.Delay(1000);
    }
}

This method has 3 parameters which are:

• JRequest – which will be send by the client.
• IServerStreamWriter – A writable stream of messages that is used in server-side and will be send to the client.
• ServerCallContext – to provides access to some HTTP/2 message data, such as the method, host, header, and trailers

The main part is inside the while loop which loops until the cancellation has been requested by the client. The while loop examines the CancellationToken on the ServerCallContext object.

This token represents the state of the call. If the client were to cancel their request they signal that they no longer plan to read from the stream, and this cause the while loop to break.

Inside the while loop the code will send all the jokes from joke number 1 till the joke number send by the client. We write the jokes to the responseStream object one by one:

await responseStream.WriteAsync(jRes);

Now let us call this Server Streaming method from the client app, so go to the “GrpcClient” app and in it’s greet.proto file, define this method:

service Greeter {
  rpc SendJoke (JRequest) returns (JResponse);
  rpc SendJokeSS (JRequest) returns (stream JResponse);
}

Next, go to the Home Controller and add the following namespaces:

using Grpc.Core;

Then add a new action method called ServerStreaming in which the Server Streaming call to the gRPC service will be performed. The code for this method is given below:

public async Task<IActionResult> ServerStreaming()
{
    var channel = GrpcChannel.ForAddress("https://localhost:7199");
    var client = new Greeter.GreeterClient(channel);

    Dictionary<string, string> jokeDict = new Dictionary<string, string>();

    var cts = new CancellationTokenSource();
    cts.CancelAfter(TimeSpan.FromSeconds(5));

    using (var call = client.SendJokeSS(new JRequest { No = 5 }, cancellationToken: cts.Token))
    {
        try
        {
            await foreach (var message in call.ResponseStream.ReadAllAsync())
            {
                jokeDict.Add(message.Joke[0].Author, message.Joke[0].Description);
            }
        }
        catch (RpcException ex) when (ex.StatusCode == Grpc.Core.StatusCode.Cancelled)
        {
            // Log Stream cancelled
        }
    }

    return View("ShowJoke", (object)jokeDict);
}

In this method we created a cancellation token that will be automatically cancelled after 5 seconds. Then the SendJokeSS method of the gRPC service is called and passed 2 things to it –

• 1. Joke number 5
• 2. The cancellation token

using (var call = client.SendJokeSS(new JRequest { No = 5 }, cancellationToken: cts.Token))
{
//…
}

We used the await foreach syntax to read the response given by the service. Test it by invoking the URL of the ServerStreaming action method which in my case is – https://localhost:7064/Home/ServerStreaming

You will see 5 jokes displayed on the View. This is shown by the below image:

Client Streaming Call example

In Client Streaming Call, the client writes a sequence of messages and sends them to the gRPC Service via a stream. Once the client has finished writing the messages, it waits for the server to read them and return a response.

In the greet.proto file of the “GrpcService” project, add a new method called SendJokesCS and make sure this method has a stream type parameter.

service Greeter {
  // other methods
  rpc SendJokesCS (stream JRequest) returns (JResponse);
}

Next, implement this method in the GreeterService.cs file as shown below.

public override async Task<JResponse> SendJokesCS(IAsyncStreamReader<JRequest> requestStream, ServerCallContext context)
{
    List<Joke> jokeList = JokeRepo();
    JResponse jRes = new JResponse();

    await foreach (var message in requestStream.ReadAllAsync())
    {
        jRes.Joke.Add(jokeList.Skip(message.No - 1).Take(1));
    }
    return jRes;
}

The parameter of this method includes an IAsyncStreamReader object to read a stream of messages sent by the client. In our case the client will send some joke number, and this method will send back the Jokes to the client.

Now let us call this method from the client. So in the greet.proto file of the client app (GrpcClient) add a new method called SendJokesCS.

service Greeter {
  // other methods
  rpc SendJokesCS (stream JRequest) returns (JResponse);
}

Then in the home controller, add a new action method and name it ‘ClientStreaming’. It’s code is given below:

public async Task<IActionResult> ClientStreaming()
{
    var channel = GrpcChannel.ForAddress("https://localhost:7199");
    var client = new Greeter.GreeterClient(channel);

    Dictionary<string, string> jokeDict = new Dictionary<string, string>();
    int[] jokes = { 3, 2, 4 };

    using (var call = client.SendJokesCS())
    {
        foreach (var jT in jokes)
        {
            await call.RequestStream.WriteAsync(new JRequest { No = jT });
        }
        await call.RequestStream.CompleteAsync();

        JResponse jRes = await call.ResponseAsync;

        foreach (Joke joke in jRes.Joke)
            jokeDict.Add(joke.Author, joke.Description);
    }

    return View("ShowJoke", (object)jokeDict);
}

This method is fairly simple and start with adding 3, 2, 4 to a int array:

int[] jokes = { 3, 2, 4 };

The client can choose to send messages with RequestStream.WriteAsync. So we send the joke number to the gRPC service in client streaming way like:

foreach (var jT in jokes)
{
    await call.RequestStream.WriteAsync(new JRequest { No = jT });
}

When the client has finished sending messages, RequestStream.CompleteAsync should be called to notify the service. The call is finished when the service returns a response message. So we close the stream as:

await call.RequestStream.CompleteAsync();

Finally adding the Jokes returned by the service in a dictionary object:

foreach (Joke joke in jRes.Joke)
    jokeDict.Add(joke.Author, joke.Description);

Test it by invoking the URL of the ClientStreaming action method which in our case is – https://localhost:7064/Home/ClientStreaming

We will see jokes no 3, 2 and 4 displayed on the browser. This is shown by the below image:

Bi-directional Streaming Call example

During a bi-directional Streaming Call, the client and service can send messages to each other at any time. So both the request and response should be of stream type.

We will create a bi-directional streaming call method for exchanging jokes by a joke number.

Start by adding a new method, by the name of SendJokesBD, on the “greet.proto” file of both service and client projects.

service Greeter {
  // other methods
  rpc SendJokesBD (stream JRequest) returns (stream JResponse);
}

Notice the use of stream keyword for both request and response objects.

Next, in the “GreeterService.cs” file add the implementation of this bi-directional call method:

public override async Task SendJokesBD(IAsyncStreamReader<JRequest> requestStream, IServerStreamWriter<JResponse> responseStream, ServerCallContext context)
{
    List<Joke> jokeList = JokeRepo();
    JResponse jRes;

    await foreach (var message in requestStream.ReadAllAsync())
    {
        jRes = new JResponse();
        jRes.Joke.Add(jokeList.Skip(message.No - 1).Take(1));
        await responseStream.WriteAsync(jRes);
    }
}

The bi-directional streaming method has 3 parameters which are:

• IAsyncStreamReader – for reading a stream of messages sent by the client.
• IServerStreamWriter – a writable stream of messages to be sent to the client.
• ServerCallContext – provides access to some HTTP/2 message data, such as the method, host, header, and trailers

The main work is done inside the for loop where we read the entire joke numbers send in the stream and writing them in the response stream one by one.

await foreach (var message in requestStream.ReadAllAsync())
{
    jRes = new JResponse();
    jRes.Joke.Add(jokeList.Skip(message.No - 1).Take(1));
    await responseStream.WriteAsync(jRes);
}

Now let us make the call to this method from the client. So, go to the home controller of your client project and add a new action method by the name of BiDirectionalStreaming. It’s full code is given below:

public async Task<IActionResult> BiDirectionalStreaming()
{
    var channel = GrpcChannel.ForAddress("https://localhost:7199");
    var client = new Greeter.GreeterClient(channel);

    Dictionary<string, string> jokeDict = new Dictionary<string, string>();

    using (var call = client.SendJokesBD())
    {
        var responseReaderTask = Task.Run(async () =>
        {
            while (await call.ResponseStream.MoveNext())
            {
                var response = call.ResponseStream.Current;
                foreach (Joke joke in response.Joke)
                    jokeDict.Add(joke.Author, joke.Description);
            }
        });

        int[] jokeNo = { 3, 2, 4 };
        foreach (var jT in jokeNo)
        {
            await call.RequestStream.WriteAsync(new JRequest { No = jT });
        }

        await call.RequestStream.CompleteAsync();
        await responseReaderTask;
    }
    return View("ShowJoke", (object)jokeDict);
}

In this case, we write the request to RequestStream and receive the responses from ResponseStream. When the connection is opened, we perform an async operation to wait for the response stream from the gRPC service.

var responseReaderTask = Task.Run(async () =>
{
    while (await call.ResponseStream.MoveNext())
    {
        var response = call.ResponseStream.Current;
        foreach (Joke joke in response.Joke)
            jokeDict.Add(joke.Author, joke.Description);
    }
});

The for loop is just taking the joke numbers 3,2, 4 and sends them to the gRPC bi-directional call as a stream.

foreach (var jT in jokeNo)
{
    await call.RequestStream.WriteAsync(new JRequest { No = jT });
}

Test it by invoking the URL of the BiDirectionalStreaming action method which in our case is – https://localhost:7064/Home/BiDirectionalStreaming.

You will see jokes number 3, 2 and 4 displayed on the View. This is shown by the below image:

You can download the full source codes from the below links:

Download

This was all about creating your gRPC Service using C# and ASP.NET Core. You can now create any type of gRPC service – simple to complex without any external help. I covered a fair amount of code in this post. Hope you enjoyed reading it so please share it on your facebook, twitter and linked account for your friends. Remember gRPC is upto 6 times faster than REST APIs.