This content originally appeared on DEV Community and was authored by DEV Community
Introduction
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.
Motivation
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.
Plan
So this is what we are trying to achieve.
- Generate the
.protoIDL 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
Prerequisites
- .NET 6 SDK
- Visual Studio Code or IDE of your choice
- gRPC compiler
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:
brew install protobuf
Project Structure
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.
dotnet new grpc -o BookshopServer
Once you run the above command, you will see the following structure.
We also need to configure the SSL trust:
dotnet dev-certs https --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:
...
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
...
We are going to replace greet.proto with our Bookshop.proto file.
We will also update our csproj file like so:
<ItemGroup>
<Protobuf Include="../proto/bookshop.proto" GrpcServices="Server" />
</ItemGroup>
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
rm BookshopServer/Services/GreeterService.cs
code BookshopServer/Services/InventoryService.cs
This is what our service is going to look like.
Let’s go through the code step by step.
-
Inventory.InventoryBaseis an abstract class that got auto-generated (in yourobj/debugfolder) from our protobuf file. -
GetBookListmethod’s stub is already generated for us in theInventoryBaseclass and that’s why we are overriding it. Again, this is the RPC call we defined in our protobuf definition. This method takes in aGetBookListRequestwhich defines what the request looks like and aServerCallContextparam 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
GetBookListRequestGetBookListResponsetypes ourselves, manually. The gRPC tooling for .NET has already created these for us under theBookshopnamespace.
Make sure to update the Program.cs to reflect the new service as well.
// ...
app.MapGrpcService<InventoryService>();
// ...
And then we can run the server with the following command.
dotnet run --project BookshopServer/BookshopServer.csproj
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 🎉
Common Errors
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
// Turn off TLS
builder.WebHost.ConfigureKestrel(options =>
{
// Setup a HTTP/2 endpoint without TLS.
options.ListenLocalhost(5000, o => o.Protocols =
HttpProtocols.Http2);
});
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.
grpcurl -plaintext localhost:8080 Inventory/GetBookList
💡 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.
grpcurl -import-path Proto -proto bookshop.proto -plaintext localhost:5000 Inventory/GetBookList
Now, let’s say we didn’t have reflection enabled and try to call a method on the server.
grpcurl -plaintext localhost:5000 Inventory/GetBookList
We can expect that it will error out. Cool!
Enabling reflection
While in the BookshopServer folder run the following command to install the reflection package.
dotnet add package Grpc.AspNetCore.Server.Reflection
Add the following to the Program.cs file. Note that we are using the new Minimal API approach to configure these services
// Register services that enable reflection
builder.Services.AddGrpcReflection();
// Enable reflection in Debug mode.
if (app.Environment.IsDevelopment())
{
app.MapGrpcReflectionService();
}
Conclusion
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! 👋
References
- https://docs.microsoft.com/en-us/aspnet/core/tutorials/grpc/grpc-start?view=aspnetcore-6.0&tabs=visual-studio-code
- https://grpc.io/docs/languages/csharp/quickstart/
- https://docs.microsoft.com/en-us/aspnet/core/grpc/troubleshoot?view=aspnetcore-6.0#unable-to-start-aspnet-core-grpc-app-on-macos
- [https://docs.microsoft.com/en-us/aspnet/core/migration/50-to-60-
This content originally appeared on DEV Community and was authored by DEV Community
DEV Community | Sciencx (2022-03-05T21:58:00+00:00) Building a gRPC Server in .NET. Retrieved from https://www.scien.cx/2022/03/05/building-a-grpc-server-in-net/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.