gRPC & ASP.NET Core 5: Test gRPC endpoints with gRPCurl
Introduction
Do you know Curl? The tool that allows you to transfer data through HTTP (and others such as IMAP, FTP etc.) to the order line? Well know that a tool based on the same principle for gRPC exists: gRPCurl. In this article I will explain how to install and use gRPCurl to test your gRPC endpoints with ASP. NET Core 5.
Install gRPCurl
gRPCurl is coded with the language GO (language developed by Google), to roll it you will have to install GO on your machine, you can download it here: https://golang.org/doc/install. Its installation is really simple you just need to run the installer and you’re done!
Ensure if GO is set installed in your Windows Environments Variables, if you don’t know how to proceed, you can follow a complete tutorial on this web page: https://www.geeksforgeeks.org/how-to-install-go-on-windows/
Once done you can run these two commands in a PowerShell window, I strongly suggest to run it as Administrator to avoid any installation issue:
go get github.com/fullstorydev/grpcurl/...
go install github.com/fullstorydev/grpcurl/cmd/grpcurl
If the installation has been successful you should be able to test by running the following command that shows gRPCurl commands:
grpcurl --help
You should see the following in your PowerShell window:
Setup ASP.NET Core gRPC
To make gRPCurl working, the latter needs to know gRPC message and endpoints definition, there are two possibilities: use Proto files or use Reflection. I’ll show you how to use Reflection because it’s the easiest way to proceed with ASP. NET Core 5. To be able to use Reflection, you have to install Grpc.AspNetCore.Server.Reflection nuget package with the following command:
Install-Package Grpc.AspNetCore.Server.Reflection -Version 2.34.0
Then configure you ASP.NET Core gRPC application with services.AddGrpcReflection() and endpoints.MapGrpcReflectionService() methods. The first one enables the gRPC reflection and the second one is the endpoint that provides to gRPCurl for example endpoints and messages information by reflection:
You’ll need obviously to create your proto files, implements your gRPC service from there proto and run your app. If you need a reminder on how to create a gRPC service with ASP.NET Core, you can read my post here: gRPC & ASP.NET Core 3.1: How to create a gRPC service ? – Anthony Giretti’s .NET blog
Use gRPCurl
gRPCurl allows you to invoke your endpoints, but you can also perform these operations:
List all available gRPC services by running the following command:
grpccurl localhost:5001 list
List all available gRPC endpoints for a given gRPC service by running the following command:
grpccurl localhost:5001 list YourgRPCServiceFullName
Describe an endpoint (get all details from the proto file) by running the following command:
grpccurl localhost:5001 describe YourEndpointFullName
Describe a gRPC service (get all details from the proto file) by running the following command:
grpccurl localhost:5001 describe YourgRPCServiceFullName
Describe an message (get all details from the proto file) by running the following command:
grpccurl localhost:5001 describe YourMessageFullName
Invoke an endpoint without input message by running the following command:
grpcurl localhost:5001 YourEndpointFullName
Invoke an endpoint with an input message (using its JSON representation) by running the following command:
grpcurl localhost:5001 -d ‘JsonRepresentationOfTheMessage’ YourEndpointFullName
If your message is a collection of objects pass to the command a JSON representation of an array of the input message, example:
‘[{\”Id\” : 1}, {\”Id\” : 2}]’
If your input message is streamed, pass a concatened JSON representation of the input message, example:
‘{\”Id\” : 1}{\”Id\” : 2}’
This is a mini tutorial of gRPCurl. gRPCurl has a lot of capabilities, if you want to learn more about I suggest you to read the documentation at this URL: https://github.com/fullstorydev/grpcurl.
Hope you like this tool as I love it 🙂
