Tutorial: Create a gRPC client and server in
ASP.NET Core
02/01/2025
This tutorial shows how to create a .NET Core gRPC client and an ASP.NET Core gRPC Server.
At the end, you'll have a gRPC client that communicates with the gRPC Greeter service.
In this tutorial, you:
＂ Create a gRPC Server.
＂ Create a gRPC client.
＂ Test the gRPC client with the gRPC Greeter service.
Prerequisites
Visual Studio
Visual Studio 2022 with the ASP.NET and web development workload.
Create a gRPC service
Visual Studio
Start Visual Studio 2022 and select New Project.
In the Create a new project dialog, search for gRPC . Select ASP.NET Core gRPC
Service and select Next.
In the Configure your new project dialog, enter GrpcGreeter for Project name. It's
important to name the project GrpcGreeter so the namespaces match when you copy
and paste code.
Select Next.
In the Additional information dialog, select .NET 9.0 (Standard Term Support) and
then select Create.
Run the service
Visual Studio
Press Ctrl+F5 to run without the debugger.
Visual Studio displays the following dialog when a project is not yet configured to
use SSL:
Select Yes if you trust the IIS Express SSL certificate.
The following dialog is displayed:
Select Yes if you agree to trust the development certificate.
For information on trusting the Firefox browser, see Firefox
SEC_ERROR_INADEQUATE_KEY_USAGE certificate error.
Visual Studio:
Starts Kestrel server.
Launches a browser.
Navigates to http://localhost:port , such as http://localhost:7042 .
port: A randomly assigned port number for the app.
localhost : The standard hostname for the local computer. Localhost only
serves web requests from the local computer.
The logs show the service listening on https://localhost:<port> , where <port> is the
localhost port number randomly assigned when the project is created and set in
Properties/launchSettings.json .
Console
info: Microsoft.Hosting.Lifetime[0]
Now listening on: https://localhost:<port>
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
７ Note
The gRPC template is configured to use Transport Layer Security (TLS) . gRPC clients
need to use HTTPS to call the server. The gRPC service localhost port number is randomly
assigned when the project is created and set in the Properties\launchSettings.json file of
the gRPC service project.
Examine the project files
GrpcGreeter project files:
Protos/greet.proto : defines the Greeter gRPC and is used to generate the gRPC server
assets. For more information, see Introduction to gRPC.
Services folder: Contains the implementation of the Greeter service.
appSettings.json : Contains configuration data such as the protocol used by Kestrel. For
more information, see Configuration in ASP.NET Core.
Program.cs , which contains:
The entry point for the gRPC service. For more information, see .NET Generic Host in
ASP.NET Core.
Code that configures app behavior. For more information, see App startup.
Create the gRPC client in a .NET console app
Visual Studio
Open a second instance of Visual Studio and select New Project.
In the Create a new project dialog, select Console App, and select Next.
In the Project name text box, enter GrpcGreeterClient and select Next.
In the Additional information dialog, select .NET 9.0 (Standard Term Support) and
then select Create.
Add required NuGet packages
The gRPC client project requires the following NuGet packages:
Grpc.Net.Client , which contains the .NET Core client.
Google.Protobuf , which contains protobuf message APIs for C#.
Grpc.Tools , which contain C# tooling support for protobuf files. The tooling package
isn't required at runtime, so the dependency is marked with PrivateAssets="All" .
Visual Studio
Install the packages using either the Package Manager Console (PMC) or Manage NuGet
Packages.
PMC option to install packages
From Visual Studio, select Tools > NuGet Package Manager > Package Manager
Console
From the Package Manager Console window, run cd GrpcGreeterClient to change
directories to the folder containing the GrpcGreeterClient.csproj files.
Run the following commands:
PowerShell
Install-Package Grpc.Net.Client
Install-Package Google.Protobuf
Install-Package Grpc.Tools
Manage NuGet Packages option to install packages
Right-click the project in Solution Explorer > Manage NuGet Packages.
Select the Browse tab.
Enter Grpc.Net.Client in the search box.
Select the Grpc.Net.Client package from the Browse tab and select Install.
Repeat for Google.Protobuf and Grpc.Tools .
Add greet.proto
Create a Protos folder in the gRPC client project.
Copy the Protos\greet.proto file from the gRPC Greeter service to the Protos folder in the
gRPC client project.
Update the namespace inside the greet.proto file to the project's namespace:
JSON
option csharp_namespace = "GrpcGreeterClient";
Edit the GrpcGreeterClient.csproj project file:
Visual Studio
Right-click the project and select Edit Project File.
Add an item group with a <Protobuf> element that refers to the greet.proto file:
XML
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
</ItemGroup>
Create the Greeter client
Build the client project to create the types in the GrpcGreeterClient namespace.
７ Note
The GrpcGreeterClient types are generated automatically by the build process. The
tooling package Grpc.Tools generates the following files based on the greet.proto file:
GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\Greet.cs : The protocol
buffer code which populates, serializes and retrieves the request and response
message types.
GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\GreetGrpc.cs : Contains the
generated client classes.
For more information on the C# assets automatically generated by Grpc.Tools , see
gRPC services with C#: Generated C# assets.
Update the gRPC client Program.cs file with the following code.
C#
using Grpc.Net.Client;
using GrpcGreeterClient;
// The port number must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:7042");
var client = new Greeter.GreeterClient(channel);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
In the preceding highlighted code, replace the localhost port number 7042 with the
HTTPS port number specified in Properties/launchSettings.json within the GrpcGreeter
service project.
Program.cs contains the entry point and logic for the gRPC client.
The Greeter client is created by:
Instantiating a GrpcChannel containing the information for creating the connection to the
gRPC service.
Using the GrpcChannel to construct the Greeter client:
C#
// The port number must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:7042");
var client = new Greeter.GreeterClient(channel);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
The Greeter client calls the asynchronous SayHello method. The result of the SayHello call is
displayed:
C#
// The port number must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:7042");
var client = new Greeter.GreeterClient(channel);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
Test the gRPC client with the gRPC Greeter service
Update the appsettings.Development.json file by adding the following highlighted lines:
C#
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"Microsoft.AspNetCore.Hosting": "Information",
"Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"
}
}
}
Visual Studio
In the GrpcGreeter service project, press Ctrl+F5 to start the server without the
debugger.
In the GrpcGreeterClient console project, press Ctrl+F5 to start the client without
the debugger.
The client sends a greeting to the service with a message containing its name, GreeterClient.
The service sends the message "Hello GreeterClient" as a response. The "Hello GreeterClient"
response is displayed in the command prompt:
Console
Greeting: Hello GreeterClient
Press any key to exit...
The gRPC service records the details of the successful call in the logs written to the command
prompt:
Console
info: Microsoft.Hosting.Lifetime[0]
Now listening on: https://localhost:<port>
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
Content root path: C:\GH\aspnet\docs\4\Docs\aspnetcore\tutorials\grpc\grpc-
start\sample\GrpcGreeter
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/2 POST https://localhost:<port>/greet.Greeter/SayHello
application/grpc
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
Executing endpoint 'gRPC - /greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
Executed endpoint 'gRPC - /greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished HTTP/2 POST https://localhost:7042/greet.Greeter/SayHello -
200 - application/grpc 40.4615ms
７ Note
The code in this article requires the ASP.NET Core HTTPS development certificate to
secure the gRPC service. If the .NET gRPC client fails with the message The remote
certificate is invalid according to the validation procedure. or The SSL connection
could not be established. , the development certificate isn't trusted. To fix this issue, see
Call a gRPC service with an untrusted/invalid certificate.
Next steps
View or download the completed sample code for this tutorial (how to download).
Overview for gRPC on .NET
gRPC services with C#
Migrate gRPC from C-core to gRPC for .NET
