daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/tutorials/grpc/grpc-start.md

11 KiB
Raw Blame History

title author description monikerRange ms.author ms.date uid
Create a .NET Core gRPC client and server in ASP.NET Core juntaoluo This tutorial shows how to create a gRPC Service and gRPC client on ASP.NET Core. Learn how to create a gRPC Service project, edit a proto file, and add a duplex streaming call. >= aspnetcore-3.0 johluo 06/05/2019 tutorials/grpc/grpc-start

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

By John Luo

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:

[!div class="checklist"]

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

[!INCLUDE]

Create a gRPC service

Visual Studio

  • From the Visual Studio File menu, select New > Project.
  • In the Create a new project dialog, select ASP.NET Core Web Application.
  • Select Next
  • Name the project GrpcGreeter. It's important to name the project GrpcGreeter so the namespaces will match when you copy and paste code.
  • Select Create
  • In the Create a new ASP.NET Core Web Application dialog:
    • Select .NET Core and ASP.NET Core 3.0 in the dropdown menus.
    • Select the gRPC Service template.
    • Select Create

Visual Studio Code

  • Open the integrated terminal.

  • Change directories (cd) to a folder which 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 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

Visual Studio for Mac

From a terminal, run the following commands:

  dotnet new grpc -o GrpcGreeter
  cd GrpcGreeter

The preceding commands use the .NET Core CLI to create a gRPC service.

Open the project

From Visual Studio, select File > Open, and then select the GrpcGreeter.sln file.

Run the service

Visual Studio

  • Press Ctrl+F5 to run the gRPC service without the debugger.

    Visual Studio runs the service in a command prompt.

Visual Studio Code / Visual Studio for Mac

  • Run the gRPC Greeter project GrpcGreeter from the command line using dotnet run.

The logs show the service listening on http://localhost:50051.

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

Examine the project files

GrpcGreeter 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 xref:fundamentals/configuration/index.
  • Program.cs: Contains the entry point for the gRPC service. For more information, see xref:fundamentals/host/web-host.
  • Startup.cs: Contains code that configures app behavior. For more information, see App startup.

Create the gRPC client in a .NET console app

Visual Studio

  • Select File > New > Project from the menu bar.
  • In the Create a new project dialog, select Console App (.NET Core).
  • Select Next
  • In the Name text box, enter "GrpcGreeterClient".
  • Select Create.

Visual Studio Code

  • Open the integrated terminal.
  • Change directories (cd) to a folder which will contain the project.
  • Run the following commands:
dotnet new console -o GrpcGreeterClient
code -r GrpcGreeterClient

Visual Studio for Mac

Follow the instructions here to create a console app with the name GrpcGreeterClient.

Add required packages

Add the following packages to the gRPC client project:

  • Grpc.Core, which contains the C# API for the C-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".

Visual Studio

Install the packages using either the Package Manager Console (PMC) or Manage NuGet Package

PMC option to install packages

  • From Visual Studio, select Tools > NuGet Package Manager > Package Manager Console
  • From the Package Manager Console window, navigate to the directory in which the GrpcGreeterClient.csproj file exists.
  • Run the following commands:
Install-Package Grpc.Core
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.Core in the search box.
  • Select the Grpc.Core package from the Browse tab and select Install.
  • Repeat for Google.Protobuf and Grpc.Tools.

Visual Studio Code

Run the following commands from the Integrated Terminal:

dotnet add GrpcGreeterClient.csproj package Grpc.Core
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package Grpc.Tools

Visual Studio for Mac

  • Right-click the Packages folder in Solution Pad > Add Packages
  • Enter Grpc.Core in the search box.
  • Select the Grpc.Core package from the results pane and select Add Package
  • 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 gRPC client project.

  • Edit the GrpcGreeterClient.csproj project file:

    Visual Studio

    Right-click the project and select the Edit GrpcGreeterClient.csproj.

    Visual Studio Code

    Select the GrpcGreeterClient.csproj file.

    Visual Studio for Mac

    Right click the project and select Tools > Edit File.

  • Add the greet.proto file to the <Protobuf> item group of the GrpcGreeterClient project file:

    <ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
</ItemGroup>

Build the client project to trigger the generation of the C# client assets.

Create the Greeter client

Build the project to create the types in the Greeter namespace. The Greeter types are generated automatically by the build process.

Update the gRPC client Program.cs file with the following code:

[!code-cs]

Program.cs contains the entry point and logic for the gRPC client.

The Greeter client is created by:

  • Instantiating a Channel containing the information for creating the connection to the gRPC service.
  • Using the Channel to construct the Greeter client:

[!code-cs]

The Greeter client calls the asynchronous SayHello method. The result of the SayHello call is displayed:

[!code-cs]

Shut down the Channel used by the client when operations have finished to release all resources.

Test the gRPC client with the gRPC Greeter service

Visual Studio

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

Visual Studio Code / Visual Studio for Mac

  • 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: http://localhost:50051
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 http://localhost:50051/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

Next steps