Tutorial: Create a gRPC client and server in ASP.NET Core

Straipsnis
06/18/2024

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 2022 with the ASP.NET and web development workload.

Create a gRPC service

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 8.0 (Long Term Support) and then select Create.

The tutorial assumes familiarity with VS Code. For more information, see Getting started with VS Code.

Select New Terminal from the Terminal menu to open the integrated terminal.
Change to the directory (cd) that will contain the project.
Run the following commands:
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
The dotnet new command creates a new gRPC service in the GrpcGreeter folder.

The code command opens the GrpcGreeter project folder in the current instance of Visual Studio Code.

Visual Studio Code might display a dialog box that asks: Do you trust the authors of the files in this folder?

If you trust all files in the parent folder, select Trust the authors of all files in the parent folder.
Select Yes, I trust the authors since the project folder has files generated by .NET.
When Visual Studio Code requests that you add assets to build and debug the project, select Yes. If Visual Studio Code doesn't offer to add build and debug assets, select View > Command Palette and type ".NET" into the search box. From the list of commands, select the .NET: Generate Assets for Build and Debug command.

Visual Studio Code adds a .vscode folder with generated launch.json and tasks.json files.

Run the service

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.

Trust the HTTPS development certificate by running the following command:
```
dotnet dev-certs https --trust
```
The preceding command requires .NET 9 SDK or later on Linux. For Linux on .NET 8.0.401 SDK and earlier, see your Linux distribution's documentation for trusting a certificate.

The preceding command displays the following dialog, provided the certificate was not previously trusted:
Select Yes if you agree to trust the development certificate.

For more information, see the Trust the ASP.NET Core HTTPS development certificate section of the Enforcing SSL article.

For information on trusting the Firefox browser, see Firefox SEC_ERROR_INADEQUATE_KEY_USAGE certificate error.

Press Ctrl-F5 to run without the debugger.

Visual Studio Code:
- 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.

Select Debug > Start Without Debugging to launch the app.

Visual Studio for Mac:
- 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.
Visual Studio for Mac displays the following popup:

Select Install and Trust if you trust the development certificate.

The following dialog is displayed:

Enter your password and select Update Settings

Select Yes if you agree to trust the development certificate.

See Trust the ASP.NET Core HTTPS development certificate for more information.
From Visual Studio, press Opt-Cmd-Return to run without the debugger. Alternatively, navigate to the menu bar and go to Run>Start Without Debugging.

Visual Studio starts Kestrel, launches a browser, and navigates to a randomly assigned port such as http://localhost:7042.

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.

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

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 8.0 (Long Term Support) and then select Create.

Open the integrated terminal.
Change directories (cd) to a folder for the project.

Run the following commands:

dotnet new console -o GrpcGreeterClient
code -r GrpcGreeterClient

Visual Studio Code might display a dialog box that asks: Do you trust the authors of the files in this folder?

If you trust all files in the parent folder, select Trust the authors of all files in the parent folder.
Select Yes, I trust the authors since the project folder has files generated by .NET.
When Visual Studio Code requests that you add assets to build and debug the project, select Yes. If Visual Studio Code doesn't offer to add build and debug assets, select View > Command Palette and type ".NET" into the search box. From the list of commands, select the .NET: Generate Assets for Build and Debug command.

Visual Studio Code adds a .vscode folder with generated launch.json and tasks.json files.

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".

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:

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.

Run the following commands from the Integrated Terminal:

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package 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:
```
option csharp_namespace = "GrpcGreeterClient";
```
Edit the GrpcGreeterClient.csproj project file:

Right-click the project and select Edit Project File.

Add an item group with a <Protobuf> element that refers to the greet.proto file:

<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.

using System.Threading.Tasks;
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:

// 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:

// 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:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
      ,"Microsoft.AspNetCore.Hosting": "Information",
      "Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"
    }
  }
}

In the Greeter service, press Ctrl+F5 to start the server without the debugger.
In the GrpcGreeterClient 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:

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:

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 in 78.32260000000001ms 200 application/grpc

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

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 2022 with the ASP.NET and web development workload.

Create a gRPC service

Start Visual Studio 2022 and select Create a 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 6.0 (Long-term support) and then select Create.

The tutorial assumes familiarity with VS Code. For more information, see Getting started with VS Code.

Select New Terminal from the Terminal menu to open the integrated terminal.
Change to the directory (cd) that will contain the project.
Run the following commands:
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
The dotnet new command creates a new gRPC service in the GrpcGreeter folder.

The code command opens the GrpcGreeter project folder in the current instance of Visual Studio Code.

Visual Studio Code might display a dialog box that asks: Do you trust the authors of the files in this folder?

If you trust all files in the parent folder, select Trust the authors of all files in the parent folder.
Select Yes, I trust the authors since the project folder has files generated by .NET.
When Visual Studio Code requests that you add assets to build and debug the project, select Yes. If Visual Studio Code doesn't offer to add build and debug assets, select View > Command Palette and type ".NET" into the search box. From the list of commands, select the .NET: Generate Assets for Build and Debug command.

Visual Studio Code adds a .vscode folder with generated launch.json and tasks.json files.

Run the service

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.

Trust the HTTPS development certificate by running the following command:
```
dotnet dev-certs https --trust
```
The preceding command requires .NET 9 SDK or later on Linux. For Linux on .NET 8.0.401 SDK and earlier, see your Linux distribution's documentation for trusting a certificate.

The preceding command displays the following dialog, provided the certificate was not previously trusted:
Select Yes if you agree to trust the development certificate.

For more information, see the Trust the ASP.NET Core HTTPS development certificate section of the Enforcing SSL article.

For information on trusting the Firefox browser, see Firefox SEC_ERROR_INADEQUATE_KEY_USAGE certificate error.

Press Ctrl-F5 to run without the debugger.

Visual Studio Code:
- 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.

Select Debug > Start Without Debugging to launch the app.

Visual Studio for Mac:
- 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.
Visual Studio for Mac displays the following popup:

Select Install and Trust if you trust the development certificate.

The following dialog is displayed:

Enter your password and select Update Settings

Select Yes if you agree to trust the development certificate.

See Trust the ASP.NET Core HTTPS development certificate for more information.
From Visual Studio, press Opt-Cmd-Return to run without the debugger. Alternatively, navigate to the menu bar and go to Run>Start Without Debugging.

Visual Studio starts Kestrel, launches a browser, and navigates to a randomly assigned port such as http://localhost:7042.

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

macOS doesn't support ASP.NET Core gRPC with TLS. Additional configuration is required to successfully run gRPC services on macOS. For more information, see Unable to start ASP.NET Core gRPC app on macOS.

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

Open a second instance of Visual Studio and select Create a new project.
In the Create a new project dialog, select Console Application, and select Next.
In the Project name text box, enter GrpcGreeterClient and select Next.
In the Additional information dialog, select .NET 6.0 (Long-term support) and then select Create.

Open the integrated terminal.
Change directories (cd) to a folder for the project.

Run the following commands:

dotnet new console -o GrpcGreeterClient
code -r GrpcGreeterClient

Visual Studio Code might display a dialog box that asks: Do you trust the authors of the files in this folder?

If you trust all files in the parent folder, select Trust the authors of all files in the parent folder.
Select Yes, I trust the authors since the project folder has files generated by .NET.
When Visual Studio Code requests that you add assets to build and debug the project, select Yes. If Visual Studio Code doesn't offer to add build and debug assets, select View > Command Palette and type ".NET" into the search box. From the list of commands, select the .NET: Generate Assets for Build and Debug command.

Visual Studio Code adds a .vscode folder with generated launch.json and tasks.json files.

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".

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:

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.

Run the following commands from the Integrated Terminal:

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package 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:
```
option csharp_namespace = "GrpcGreeterClient";
```
Edit the GrpcGreeterClient.csproj project file:

Right-click the project and select Edit Project File.

Add an item group with a <Protobuf> element that refers to the greet.proto file:

<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.

using System.Threading.Tasks;
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:

// 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:

// 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:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
      ,"Microsoft.AspNetCore.Hosting": "Information",
      "Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"
    }
  }
}

In the Greeter service, press Ctrl+F5 to start the server without the debugger.
In the GrpcGreeterClient project, press Ctrl+F5 to start the client without the debugger.

Due to the previously mentioned HTTP/2 TLS issue on macOS workaround, you'll need to update the channel address in the client to match port in launchSetting.json of the GrpcGreeter service "http://localhost:5000". Update line 13 of GrpcGreeterClient/Program.cs to read:
```
using var channel = GrpcChannel.ForAddress("http://localhost:5000");
```
Start the Greeter service.
Start the client.

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:

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 in 78.32260000000001ms 200 application/grpc

Note

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

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 2022 with the ASP.NET and web development workload.
.NET 6.0 SDK

Create a gRPC service

Start Visual Studio 2022 and select Create a 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 6.0 (Long-term support) and then select Create.

The tutorial assumes familiarity with VS Code. For more information, see Getting started with VS Code.

Select New Terminal from the Terminal menu to open the integrated terminal.
Change to the directory (cd) that will contain the project.
Run the following commands:
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
The dotnet new command creates a new gRPC service in the GrpcGreeter folder.

The code command opens the GrpcGreeter project folder in the current instance of Visual Studio Code.

Visual Studio Code might display a dialog box that asks: Do you trust the authors of the files in this folder?

If you trust all files in the parent folder, select Trust the authors of all files in the parent folder.
Select Yes, I trust the authors since the project folder has files generated by .NET.
When Visual Studio Code requests that you add assets to build and debug the project, select Yes. If Visual Studio Code doesn't offer to add build and debug assets, select View > Command Palette and type ".NET" into the search box. From the list of commands, select the .NET: Generate Assets for Build and Debug command.

Visual Studio Code adds a .vscode folder with generated launch.json and tasks.json files.

Run the service

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.

Trust the HTTPS development certificate by running the following command:
```
dotnet dev-certs https --trust
```
The preceding command requires .NET 9 SDK or later on Linux. For Linux on .NET 8.0.401 SDK and earlier, see your Linux distribution's documentation for trusting a certificate.

The preceding command displays the following dialog, provided the certificate was not previously trusted:
Select Yes if you agree to trust the development certificate.

For more information, see the Trust the ASP.NET Core HTTPS development certificate section of the Enforcing SSL article.

For information on trusting the Firefox browser, see Firefox SEC_ERROR_INADEQUATE_KEY_USAGE certificate error.

Press Ctrl-F5 to run without the debugger.

Visual Studio Code:
- 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.

Select Debug > Start Without Debugging to launch the app.

Visual Studio for Mac:
- 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.
Visual Studio for Mac displays the following popup:

Select Install and Trust if you trust the development certificate.

The following dialog is displayed:

Enter your password and select Update Settings

Select Yes if you agree to trust the development certificate.

See Trust the ASP.NET Core HTTPS development certificate for more information.
From Visual Studio, press Opt-Cmd-Return to run without the debugger. Alternatively, navigate to the menu bar and go to Run>Start Without Debugging.

Visual Studio starts Kestrel, launches a browser, and navigates to a randomly assigned port such as http://localhost:7042.

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

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

Open a second instance of Visual Studio and select Create a new project.
In the Create a new project dialog, select Console Application, and select Next.
In the Project name text box, enter GrpcGreeterClient and select Next.
In the Additional information dialog, select .NET 6.0 (Long-term support) and then select Create.

Open the integrated terminal.
Change directories (cd) to a folder for the project.

Run the following commands:

dotnet new console -o GrpcGreeterClient
code -r GrpcGreeterClient

Visual Studio Code might display a dialog box that asks: Do you trust the authors of the files in this folder?

If you trust all files in the parent folder, select Trust the authors of all files in the parent folder.
Select Yes, I trust the authors since the project folder has files generated by .NET.
When Visual Studio Code requests that you add assets to build and debug the project, select Yes. If Visual Studio Code doesn't offer to add build and debug assets, select View > Command Palette and type ".NET" into the search box. From the list of commands, select the .NET: Generate Assets for Build and Debug command.

Visual Studio Code adds a .vscode folder with generated launch.json and tasks.json files.

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".

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:

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.

Run the following commands from the Integrated Terminal:

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package 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:
```
option csharp_namespace = "GrpcGreeterClient";
```
Edit the GrpcGreeterClient.csproj project file:

Right-click the project and select Edit Project File.

Add an item group with a <Protobuf> element that refers to the greet.proto file:

<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.

using System.Threading.Tasks;
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:

// 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:

// 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

In the Greeter service, press Ctrl+F5 to start the server without the debugger.
In the GrpcGreeterClient project, press Ctrl+F5 to start the client without the debugger.

Due to the previously mentioned HTTP/2 TLS issue on macOS workaround, you'll need to update the channel address in the client to match port in launchSetting.json of the GrpcGreeter service "http://localhost:5000". Update line 13 of GrpcGreeterClient/Program.cs to read:
```
using var channel = GrpcChannel.ForAddress("http://localhost:5000");
```
Start the Greeter service.
Start the client.

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:

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 in 78.32260000000001ms 200 application/grpc

Update the appsettings.Development.json file by adding the following lines:

"Microsoft.AspNetCore.Hosting": "Information",
"Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"

Note

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

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.

View or download sample code (how to download).

In this tutorial, you:

Create a gRPC Server.
Create a gRPC client.
Test the gRPC client with the gRPC Greeter service.

Prerequisites

Visual Studio 2019 16.8 or later with the ASP.NET and web development workload
.NET 5.0 SDK

Create a gRPC service

Start Visual Studio and select Create a new project.
In the Create a new project dialog, select 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 5.0 in the Target Framework dropdown.
Select Create.

The tutorial assumes familiarity with VS Code. For more information, see Getting started with VS Code.

Select New Terminal from the Terminal menu to open the integrated terminal.
Change to the directory (cd) that will contain the project.
Run the following commands:
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
The dotnet new command creates a new gRPC service in the GrpcGreeter folder.

The code command opens the GrpcGreeter project folder in the current instance of Visual Studio Code.

Visual Studio Code might display a dialog box that asks: Do you trust the authors of the files in this folder?

If you trust all files in the parent folder, select Trust the authors of all files in the parent folder.
Select Yes, I trust the authors since the project folder has files generated by .NET.
When Visual Studio Code requests that you add assets to build and debug the project, select Yes. If Visual Studio Code doesn't offer to add build and debug assets, select View > Command Palette and type ".NET" into the search box. From the list of commands, select the .NET: Generate Assets for Build and Debug command.

Visual Studio Code adds a .vscode folder with generated launch.json and tasks.json files.

Run the service

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 IIS Express and runs the app. The address bar shows localhost:port# and not something like example.com. That's because localhost is the standard hostname for the local computer. Localhost only serves web requests from the local computer. When Visual Studio creates a web project, a random port is used for the web server.

Trust the HTTPS development certificate by running the following command:
```
dotnet dev-certs https --trust
```
The preceding command requires .NET 9 SDK or later on Linux. For Linux on .NET 8.0.401 SDK and earlier, see your Linux distribution's documentation for trusting a certificate.

The preceding command displays the following dialog, provided the certificate was not previously trusted:
Select Yes if you agree to trust the development certificate.

For more information, see the Trust the ASP.NET Core HTTPS development certificate section of the Enforcing SSL article.

For information on trusting the Firefox browser, see Firefox SEC_ERROR_INADEQUATE_KEY_USAGE certificate error.

Press Ctrl-F5 to run without the debugger.

Visual Studio Code starts Kestrel, launches a browser, and navigates to http://localhost:5001. The address bar shows localhost:port# and not something like example.com. That's because localhost is the standard hostname for local computer. Localhost only serves web requests from the local computer.

Select Run > Start Without Debugging to launch the app.

Visual Studio for Mac:
- Starts Kestrel server.
- Launches a browser.
- Navigates to http://localhost:port, where port is a randomly chosen port number.
Visual Studio for Mac displays the following popup:

Select Yes if you trust the development certificate.

The following dialog is displayed:

Enter your password and select OK

Select Yes if you agree to trust the development certificate.

See Trust the ASP.NET Core HTTPS development certificate for more information.
From Visual Studio, press Opt-Cmd-Return to run without the debugger. Alternatively, navigate to the menu bar and go to Run>Start Without Debugging.

Visual Studio starts Kestrel, launches a browser, and navigates to http://localhost:5001.

The logs show the service listening on https://localhost:5001.

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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.

Examine the project files

GrpcGreeter project files:

greet.proto: The Protos/greet.proto file 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 protocol used by Kestrel. For more information, see Configuration in ASP.NET Core.
Program.cs: Contains the entry point for the gRPC service. For more information, see .NET Generic Host in ASP.NET Core.
Startup.cs: Contains code that configures app behavior. For more information, see App startup.

Create the gRPC client in a .NET console app

Open a second instance of Visual Studio and select Create a new project.
In the Create a new project dialog, select Console App (.NET Core) and select Next.
In the Project name text box, enter GrpcGreeterClient and select Create.

Open the integrated terminal.
Change directories (cd) to a folder for the project.

Run the following commands:

dotnet new console -o GrpcGreeterClient
code -r GrpcGreeterClient

Visual Studio Code requests that you add assets to build and debug the project, select Yes.

Visual Studio Code adds a .vscode folder with generated launch.json and tasks.json files.

Add required packages

The gRPC client project requires the following packages:

Grpc.Net.Client, which contains the .NET Core client.
Google.Protobuf, which contains protobuf message APIs for C#.
Grpc.Tools, which contains C# tooling support for protobuf files. The tooling package isn't required at runtime, so the dependency is marked with PrivateAssets="All".

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:

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.

Run the following commands from the Integrated Terminal:

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package 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:
```
option csharp_namespace = "GrpcGreeterClient";
```
Edit the GrpcGreeterClient.csproj project file:
Right-click the project and select Edit Project File.

Select the GrpcGreeterClient.csproj file.

Right-click the project and select Edit Project File.

Add an item group with a <Protobuf> element that refers to the greet.proto file:

<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:

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Grpc.Net.Client;

namespace GrpcGreeterClient
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // The port number(5001) must match the port of the gRPC server.
            using var channel = GrpcChannel.ForAddress("https://localhost:5001");
            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();
        }
    }
}

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:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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

In the Greeter service, press Ctrl+F5 to start the server without the debugger.
In the GrpcGreeterClient project, press Ctrl+F5 to start the client without the debugger.

Due to the previously mentioned HTTP/2 TLS issue on macOS workaround, you'll need to update the channel address in the client to "http://localhost:5000". Update line 13 of GrpcGreeterClient/Program.cs to read:
```
using var channel = GrpcChannel.ForAddress("http://localhost:5000");
```
Start the Greeter service.
Start the client.

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:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:5001/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 in 78.32260000000001ms 200 application/grpc

Note

Next steps

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.

View or download sample code (how to download).

In this tutorial, you:

Create a gRPC Server.
Create a gRPC client.
Test the gRPC client with the gRPC Greeter service.

Prerequisites

Visual Studio 2019 16.4 or later with the ASP.NET and web development workload
.NET Core 3.1 SDK

Create a gRPC service

Start Visual Studio and select Create a new project. Alternatively, from the Visual Studio File menu, select New > Project.
In the Create a new project dialog, select gRPC Service and select Next:
Name the project GrpcGreeter. It's important to name the project GrpcGreeter so the namespaces match when you copy and paste code.
Select Create.
In the Create a new gRPC service dialog:
- The gRPC Service template is selected.
- Select Create.

Open the integrated terminal.
Change directories (cd) to a folder for the project.
Run the following commands:
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
- The dotnet new command creates a new gRPC service in the GrpcGreeter folder.
- The code command opens the GrpcGreeter folder in a new instance of Visual Studio Code.
A dialog box appears with Required assets to build and debug are missing from 'GrpcGreeter'. Add them?
Select Yes.

Run the service

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 IIS Express and runs the app. The address bar shows localhost:port# and not something like example.com. That's because localhost is the standard hostname for the local computer. Localhost only serves web requests from the local computer. When Visual Studio creates a web project, a random port is used for the web server.

Trust the HTTPS development certificate by running the following command:
```
dotnet dev-certs https --trust
```
The preceding command requires .NET 9 SDK or later on Linux. For Linux on .NET 8.0.401 SDK and earlier, see your Linux distribution's documentation for trusting a certificate.

The preceding command displays the following dialog, provided the certificate was not previously trusted:
Select Yes if you agree to trust the development certificate.

For more information, see the Trust the ASP.NET Core HTTPS development certificate section of the Enforcing SSL article.

For information on trusting the Firefox browser, see Firefox SEC_ERROR_INADEQUATE_KEY_USAGE certificate error.

Press Ctrl-F5 to run without the debugger.

Visual Studio Code starts Kestrel, launches a browser, and navigates to http://localhost:5001. The address bar shows localhost:port# and not something like example.com. That's because localhost is the standard hostname for local computer. Localhost only serves web requests from the local computer.

Select Run > Start Without Debugging to launch the app.

Visual Studio for Mac:
- Starts Kestrel server.
- Launches a browser.
- Navigates to http://localhost:port, where port is a randomly chosen port number.
Visual Studio for Mac displays the following popup:

Select Yes if you trust the development certificate.

The following dialog is displayed:

Enter your password and select OK

Select Yes if you agree to trust the development certificate.

See Trust the ASP.NET Core HTTPS development certificate for more information.
From Visual Studio, press Opt-Cmd-Return to run without the debugger. Alternatively, navigate to the menu bar and go to Run>Start Without Debugging.

Visual Studio starts Kestrel, launches a browser, and navigates to http://localhost:5001.

The logs show the service listening on https://localhost:5001.

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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.

Examine the project files

GrpcGreeter project files:

greet.proto: The Protos/greet.proto file 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 protocol used by Kestrel. For more information, see Configuration in ASP.NET Core.
Program.cs: Contains the entry point for the gRPC service. For more information, see .NET Generic Host in ASP.NET Core.
Startup.cs: Contains code that configures app behavior. For more information, see App startup.

Create the gRPC client in a .NET console app

Open a second instance of Visual Studio and select Create a new project.
In the Create a new project dialog, select Console App (.NET Core) and select Next.
In the Project name text box, enter GrpcGreeterClient and select Create.

Add required packages

The gRPC client project requires the following packages:

Grpc.Net.Client, which contains the .NET Core client.
Google.Protobuf, which contains protobuf message APIs for C#.
Grpc.Tools, which contains C# tooling support for protobuf files. The tooling package isn't required at runtime, so the dependency is marked with PrivateAssets="All".

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:

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.

Run the following commands from the Integrated Terminal:

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package 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:
```
option csharp_namespace = "GrpcGreeterClient";
```
Edit the GrpcGreeterClient.csproj project file:
Right-click the project and select Edit Project File.

Select the GrpcGreeterClient.csproj file.

Right-click the project and select Edit Project File.

Add an item group with a <Protobuf> element that refers to the greet.proto file:

<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:

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Grpc.Net.Client;

namespace GrpcGreeterClient
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // The port number(5001) must match the port of the gRPC server.
            using var channel = GrpcChannel.ForAddress("https://localhost:5001");
            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();
        }
    }
}

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:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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

In the Greeter service, press Ctrl+F5 to start the server without the debugger.
In the GrpcGreeterClient project, press Ctrl+F5 to start the client without the debugger.

Due to the previously mentioned HTTP/2 TLS issue on macOS workaround, you'll need to update the channel address in the client to "http://localhost:5000". Update line 13 of GrpcGreeterClient/Program.cs to read:
```
using var channel = GrpcChannel.ForAddress("http://localhost:5000");
```
Start the Greeter service.
Start the client.

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:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:5001/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 in 78.32260000000001ms 200 application/grpc

Note

Bendrinti naudojant

Tutorial: Create a gRPC client and server in ASP.NET Core

Prerequisites

Create a gRPC service

Run the service

Examine the project files

Create the gRPC client in a .NET console app

Add required NuGet packages

PMC option to install packages

Manage NuGet Packages option to install packages

Add greet.proto

Create the Greeter client

Test the gRPC client with the gRPC Greeter service

Next steps

Prerequisites

Create a gRPC service

Run the service

Examine the project files

Create the gRPC client in a .NET console app

Add required NuGet packages

PMC option to install packages

Manage NuGet Packages option to install packages

Add greet.proto

Create the Greeter client

Test the gRPC client with the gRPC Greeter service

Next steps

Prerequisites

Create a gRPC service

Run the service

Examine the project files

Create the gRPC client in a .NET console app

Add required NuGet packages

PMC option to install packages

Manage NuGet Packages option to install packages

Add greet.proto

Create the Greeter client

Test the gRPC client with the gRPC Greeter service

Next steps

Prerequisites

Create a gRPC service

Run the service

Examine the project files

Create the gRPC client in a .NET console app

Add required packages

PMC option to install packages

Manage NuGet Packages option to install packages

Add greet.proto

Create the Greeter client

Test the gRPC client with the gRPC Greeter service

Next steps

Prerequisites

Create a gRPC service

Run the service

Examine the project files

Create the gRPC client in a .NET console app

Add required packages

PMC option to install packages

Manage NuGet Packages option to install packages

Add greet.proto

Create the Greeter client

Test the gRPC client with the gRPC Greeter service

Next steps

Papildomi ištekliai