Hi, in this tutorial we're going to create agRPC Service and Client using .NET Core. I'm assuming you've already heard about gRPC and want to see some code. In case you haven't, here's an excerpt from Microsoft Docs:
What is gRPC?
gRPC is a modern, high-performance framework that evolves the age-old remote procedure call (RPC) protocol. At the application level, gRPC streamlines messaging between clients and back-end services. Originating from Google, gRPC is open source and part of the Cloud Native Computing Foundation (CNCF) ecosystem of cloud-native offerings.
Wikipedia defines gRPC as:
gRPC (gRPC Remote Procedure Calls) is an open source remote procedure call (RPC) system initially developed at Google in 2015. It uses HTTP/2 for transport, Protocol Buffers as the interface description language, and provides features such as authentication, bidirectional streaming and flow control, blocking or nonblocking bindings, and cancellation and timeouts. It generates cross-platform client and server bindings for many languages. Most common usage scenarios include connecting services in microservices style architecture and connect mobile devices, browser clients to backend services.
Enough with the theory, let's get down with the code:
How to create gRPC (Micro?) Service (and Client) using .NET?
FYI: I'm using Visual Studio 2019 on a Windows 10 Machine.
- Create a new Project using
gRPC template.
Don't worry, we'll create a new gRPC from scratch.
I'm using ASP.NET Core 3.1, but you may use .NET 5 as well
The solution looks like this:
Let's have a look at the existing proto file:
syntax = "proto3";
option csharp_namespace = "HashGrpc";
package greet;
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest {
string name = 1;
}
message HelloReply {
string message = 1;
}
Let's build a Hashing gRPC Service which takes a string input and returns SHA256 hash of the input.
Create the proto contract
- Add a new file under Protos directory:
- Copy this code to the newly created
hash.proto.
syntax = "proto3";
option csharp_namespace = "HashGrpc.Protos";
package hash;
service Hash {
rpc GetHash(HashRequest) returns (HashResponse);
}
message HashRequest {
string input = 1;
}
message HashResponse {
string hash = 1;
}
Let's break it down.
syntax - Tells the version of Protobuf. In our case it's proto3.
option csharp_namespace - While generating C# code, the namespace used would be "HashGrpc.Protos".
package - package name for the service in proto file
service - Service definition. Currently, our contract has only 1 service.
message - Defines the types used in Service. The numbers are unique tag for the fields.
Generate Server stub
Add these lines to the csproj of your project. This lets Visual Studio know that we want to generate Server code for our gRPC service.
<ItemGroup>
<Protobuf Include="Protos\hash.proto" GrpcServices="Server" />
</ItemGroup>
Implement the Service
Under the Services folder, create a new Class named HashService.
Copy this code to the newly created Service.
using Grpc.Core;
using HashGrpc.Protos;
using Microsoft.Extensions.Logging;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
namespace HashGrpc.Services
{
public class HashService : Hash.HashBase
{
private readonly ILogger<HashService> _logger;
public HashService(ILogger<HashService> logger)
{
_logger = logger;
}
public override Task<HashResponse> GetHash(HashRequest request, ServerCallContext context)
{
_logger.LogDebug("Getting hash for {request}", request);
var hashResponse = new HashResponse
{
Hash = GetSha256Hash(request.Input)
};
_logger.LogDebug("Hash generated for {request} is {response}", request, hashResponse);
return Task.FromResult(hashResponse);
}
private static string GetSha256Hash(string plainText)
{
using SHA256 sha256Hash = SHA256.Create();
byte[] bytes = sha256Hash.ComputeHash(Encoding.UTF8.GetBytes(plainText));
StringBuilder stringbuilder = new StringBuilder();
for (int i = 0; i < bytes.Length; i++)
{
stringbuilder.Append(bytes[i].ToString("x2"));
}
return stringbuilder.ToString();
}
}
}
Let's break it down.
Hash.HashBase - This is the base class generated by Visual Studio which includes plumbing required to communicate. DO NOT EDIT IT.
HashService - Just to emphasize that this is just a plain old class, we've added a constructor which takes an ILogger<HashService>, which can be injected by .NET Core's Dependency Injection system.
GetHash method - Remember our protobuf had a method named GetHash? You can now implement this method. In our case, we've calculated the SHA 256 hash of the given input. And that's it. You've just created a fully functional gRPC Service. Now let's create a Client to call this Service.
Consuming the gRPC Service
Creating the Client
Let's create a new Console App Project to test our gRPC Service.
Adding Nuget packages
Install the following NuGet packages:
Google.Protobuf
Grpc.Net.Client
Grpc.Tools
Adding a reference to the .proto
<ItemGroup>
<Protobuf Include="Protos\hash.proto" GrpcServices="Client" />
</ItemGroup>
This lets Visual Studio know that we want to create Client code for the
Creating a channel
- Change the content of
Program.cs as follows:
using Grpc.Net.Client;
using HashGrpc.Protos;
using System;
using System.Threading.Tasks;
using static HashGrpc.Protos.Hash;
namespace HashGrpc.Client
{
class Program
{
static async Task Main(string[] args)
{
Console.WriteLine("Hello World!");
using var channel = GrpcChannel.ForAddress("https://localhost:5001");
var client = new HashClient(channel);
var response = await client.GetHashAsync(new HashRequest { Input = "Test" });
Console.WriteLine($"Hash: {response.Hash}");
}
}
}
Let's break it down:
First, we need to create a gRPC Channel by giving the address where our service is running.
Then we create a client by passing the channel.
Now we can call the method by passing the HashRequest for which we want to get the SHA 256 hash.
Notice the Service had a method GetHash but the client has 2 methods GetHash and GetHashAsync. That's thanks to the tooling which generated both Synchronous and Asynchronous versions of our GetHash method.
Run both Client and Service and you'll see the output something like this:
Client:
Service
gRPC needs HTTP2 under the hood for communication. HTTP2 may not be supported everywhere yet (unfortunately).
Congratulations! You've just created a new gRPC Service and Client.
Source Code
The source code is available on GitHub here.
Next Steps
Read more about:
