aspnetcore/tutorials/grpc/grpc-start/includes/grpc-start7.md
:::moniker range="= aspnetcore-7.0" This tutorial shows how to create a .NET 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:
[!div class="checklist"]
- Create a gRPC Server.
- Create a gRPC client.
- Test the gRPC client with the gRPC Greeter service.
gRPC. Select ASP.NET Core gRPC Service and select Next.GrpcGreeter for Project name. It's important to name the project GrpcGreeter so the namespaces match when you copy and paste code.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.
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.
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.
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 xref:fundamentals/configuration/index.Program.cs, which contains:
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
Follow the instructions in Building a complete .NET solution on macOS using Visual Studio for Mac to create a console app with the name GrpcGreeterClient.
The gRPC client project requires the following NuGet packages:
PrivateAssets="All".Install the packages using either the Package Manager Console (PMC) or Manage NuGet 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
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
Google.Protobuf and Grpc.Tools.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>
GrpcGreeterClient namespace.[!NOTE] The
GrpcGreeterClienttypes 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.
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:
GrpcChannel containing the information for creating the connection to the gRPC service.GrpcChannel to construct the Greeter client:The Greeter client calls the asynchronous SayHello method. The result of the SayHello call is displayed:
Update the appsettings.Development.json file by adding the following highlighted lines:
Ctrl+F5 to start the server without the debugger.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.
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.orThe 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.
:::moniker-end