In this article, we will look at how to build a simple web service with gRPC in .NET. We will keep our changes to minimal and leverage the same Protocol Buffer IDL we used in my previous post. We will also go through some common problems that you might face when building a gRPC server in .NET.
For this article also we will be using the Online Bookshop example and leveraging the same Protobufs as we saw before. For those who aren’t familiar with or missed this series, you can find them from here.
Introduction to gRPC
Building a gRPC server with Go
Building a gRPC server with .NET (You are here)
Building a gRPC client with Go
Building a gRPC client with .NET
We will be covering steps 1 and 2 in the following diagram.
So this is what we are trying to achieve.
Generate the .proto IDL stubs.
Write the business logic for our service methods.
Spin up a gRPC server on a given port.
In a nutshell, we will be covering the following items on our initial diagram.
? As always, all the code samples documentation can be found at: https://github.com/sahansera/dotnet-grpc
.NET 6 SDK
Visual Studio Code or IDE of your choice
Please note that I’m using some of the commands that are macOS specific. Please follow this link to set it up if you are on a different OS.
To install Protobuf compiler:
We can use the the .NET’s tooling to generate a sample gRPC project. Run the following command in at the root of your workspace.
Once you run the above command, you will see the following structure.
We also need to configure the SSL trust:
As you might have guessed, this is like a default template and it already has a lot of things wired up for us like the Protos folder.
Generating the server stubs
Usually, we would have to invoke the protocol buffer compiler to generate the code for the target language (as we saw in my previous article). However, for .NET they have streamlined the code generation process. They use the Grpc.Tools NuGet package with MSBuild to provide automatic code generation, which is pretty neat! ?
If you open up the Bookshop.csproj file you will find the following lines:
<Protobuf Include=“Protosgreet.proto“ GrpcServices=“Server“ />
We are going to replace greet.proto with our Bookshop.proto file.
We will also update our csproj file like so:
<Protobuf Include=“../proto/bookshop.proto“ GrpcServices=“Server“ />
Implementing the Server
The implementation part is easy! Let’s clean up the GreeterService that comes default and add a new file called InventoryService.cs
This is what our service is going to look like.
Let’s go through the code step by step.
Inventory.InventoryBase is an abstract class that got auto-generated (in your obj/debug folder) from our protobuf file.
GetBookList method’s stub is already generated for us in the InventoryBase class and that’s why we are overriding it. Again, this is the RPC call we defined in our protobuf definition. This method takes in a GetBookListRequest which defines what the request looks like and a ServerCallContext param which contains the headers, auth context etc.
Rest of the code is pretty easy – we prepare the response and return it back to the caller/client. It’s worth noting that we never defined the GetBookListRequest GetBookListResponse types ourselves, manually. The gRPC tooling for .NET has already created these for us under the Bookshop namespace.
Make sure to update the Program.cs to reflect the new service as well.
And then we can run the server with the following command.
We are almost there! Remember we can’t access the service yet through the browser since browsers don’t understand binary protocols. In the next step, we will to test our service ?
A common error you’d find on macOS systems with .NET is HTTP/2 and TLS issue shown below.
gRPC template uses TLS by default and Kestrel doesn’t support HTTP/2 with TLS on macOS systems. We need to turn off TLS (ouch!) in order for our demo to work.
? Please don’t do this in production! This is intended for local development purposes only.
On local development
// Setup a HTTP/2 endpoint without TLS.
options.ListenLocalhost(5000, o => o.Protocols =
Testing the service
Usually, when interacting with the HTTP/1.1-like server, we can use cURL to make requests and inspect the responses. However, with gRPC, we can’t do that. (you can make requests to HTTP/2 services, but those won’t be readable). We will be using gRPCurl for that.
Once you have it up and running, you can now interact with the server we just built.
? Note: gRPC defaults to TLS for transport. However, to keep things simple, I will be using the `-plaintext` flag with `grpcurl` so that we can see a human-readable response.
How do we figure out the endpoints of the service? There are two ways to do this. One is by providing a path to the proto files, while the other option enables reflection through the code.
Using proto files
If you don’t want to enable reflection, we can use the Protobuf files to let gRPCurl know which methods are available. Normally, when a team makes a gRPC service they will make the protobuf files available if you are integrating with them. So, without having to ask them or doing trial-and-error you can use these proto files to introspect what kind of endpoints are available for consumption.
Now, let’s say we didn’t have reflection enabled and try to call a method on the server.
We can expect that it will error out. Cool!
While in the BookshopServer folder run the following command to install the reflection package.
Add the following to the Program.cs file. Note that we are using the new Minimal API approach to configure these services
// Enable reflection in Debug mode.
As we have seen, similar to the Go implementation, we can use the same Protocol buffer files to generate the server implementation in .NET. In my opinion .NET’s new tooling makes it easier to generate the server stubs when a change happens in your Protobufs. However, setting up the local developer environment could be a bit challenging especially for macOS.
Feel free to let me know if you have any questions or feedback. Until next time! ?