教程：在 ASP.NET Core 中创建 gRPC 客户端和服务器

项目
11/30/2023

本教程演示了如何创建 .NET Core gRPC 客户端和 ASP.NET Core gRPC 服务器。最后会生成与 gRPC Greeter 服务进行通信的 gRPC 客户端。

在本教程中，你将了解：

创建 gRPC 服务器。
创建 gRPC 客户端。
使用 gRPC Greeter 服务测试 gRPC 客户端。

先决条件

带有 ASP.NET 和 Web 开发工作负载的 Visual Studio 2022。

创建 gRPC 服务

启动 Visual Studio 2022 并选择“新建项目”。
在“创建新项目”对话框中，搜索 gRPC。选择“ASP.NET Core gRPC 服务”，并选择“下一步” 。
在“配置新项目”对话框中，为“项目名称”输入 GrpcGreeter。将项目命名为“GrpcGreeter”非常重要，这样在复制和粘贴代码时命名空间就会匹配。
选择下一步。
在“其他信息”对话框中，选择“.NET 8.0 (长期支持)”，然后选择“创建”。

本教程假定用户熟悉 VS Code。有关详细信息，请参阅 VS Code入门。

从“终端”菜单中选择“新建终端”以打开集成终端。
更改为将包含项目的目录 (cd)。
运行以下命令：
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
dotnet new 命令将在 GrpcGreeter 文件夹中创建一个新 gRPC 服务。

code 命令会在 Visual Studio Code 的当前实例中打开“GrpcGreeter”项目文件夹。

Visual Studio Code 可能会显示一个对话框，询问：“你是否信任此文件夹中的文件作者?”

如果你信任父文件夹中的所有文件，请选择“信任父文件夹中所有文件的作者”。
选择“是，我信任所有作者”，因为项目文件夹包含 .NET 生成的文件。
当 Visual Studio Code 请求你添加资产来生成和调试项目时，请选择“是”。如果 Visual Studio Code 不提供添加生成和调试资产的功能，请选择“视图”>“命令面板”，然后在搜索框中输入“.NET”。从命令列表中选择 .NET: Generate Assets for Build and Debug 命令。

Visual Studio Code 添加一个包含生成的 launch.json 和 tasks.json 文件的 .vscode 文件夹。

运行服务

按 Ctrl+F5 以在不使用调试程序的情况下运行。

如果尚未将项目配置为使用 SSL，Visual Studio 显示以下对话：

如果信任 IIS Express SSL 证书，请选择“是”。

将显示以下对话框：

如果你同意信任开发证书，请选择“是”。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

Visual Studio：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，如 http://localhost:7042。
  - 端口：随机分配给应用的端口号。
  - localhost：本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。

通过运行以下命令来信任 HTTPS 开发证书：
```
dotnet dev-certs https --trust
```
上述命令在 Linux 上无效。有关信任证书的详细信息，请参阅 Linux 发行版的文档。

如果证书以前不受信任，上述命令显示以下对话：
如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

按 Ctrl-F5 以在不使用调试程序的情况下运行。

Visual Studio Code：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，如 http://localhost:7042。
  - 端口：随机分配给应用的端口号。
  - localhost：本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。

选择“调试”>“在不调试的情况下启动”以启动应用。

Visual Studio for Mac：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，如 http://localhost:7042。
  - 端口：随机分配给应用的端口号。
  - localhost：本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。
Visual Studio for Mac 会显示以下弹出窗口：

如果你信任开发证书，请选择“安装并信任”。

将显示以下对话框：

输入你的密码，然后选择“更新设置”

如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。
在 Visual Studio 中，按“Opt-Cmd-Return”可在不使用调试器的情况下运行。或者，导航到菜单栏，转到“运行”>“在不调试的情况下启动”。

Visual Studio 启动 Kestrel，启动浏览器，并导航到随机分配的端口（例如 http://localhost:7042）。

日志显示在 https://localhost:<port> 上侦听的服务，其中 <port> 是在 Properties/launchSettings.json 中创建和设置项目时随机分配的 localhost 端口号。

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

注意

gRPC 模板配置为使用传输层安全性 (TLS)。 gRPC 客户端需要使用 HTTPS 调用服务器。在 gRPC 服务项目的 Properties\launchSettings.json 文件中创建和设置项目时，将随机分配 gRPC 服务 localhost 端口号。

检查项目文件

GrpcGreeter 项目文件：

Protos/greet.proto：定义 Greeter gRPC，并用于生成 gRPC 服务器资产。有关详细信息，请参阅 gRPC 介绍。
Services 文件夹：包含 Greeter 服务的实现。
appSettings.json：包含配置数据，如 Kestrel 使用的协议。有关详细信息，请参阅 ASP.NET Core 中的配置。
Program.cs，其中包含：
- gRPC 服务的入口点。有关详细信息，请参阅 ASP.NET Core 中的 .NET 通用主机。
- 配置应用行为的代码。有关详细信息，请参阅应用启动。

在 .NET 控制台应用中创建 gRPC 客户端

打开 Visual Studio 的第二个实例并选择“新建项目”。
在“创建新项目”对话框中，选择“控制台应用”，然后选择“下一步”。
在“项目名称”文本框中，输入“GrpcGreeterClient”，然后选择“下一步” 。
在“其他信息”对话框中，选择“.NET 8.0 (长期支持)”，然后选择“创建”。

打开集成终端。
将目录 (cd) 更改为项目的文件夹。

运行以下命令：

dotnet new console -o GrpcGreeterClient
code -r GrpcGreeterClient

Visual Studio Code 可能会显示一个对话框，询问：“你是否信任此文件夹中的文件作者?”

如果你信任父文件夹中的所有文件，请选择“信任父文件夹中所有文件的作者”。
选择“是，我信任所有作者”，因为项目文件夹包含 .NET 生成的文件。
当 Visual Studio Code 请求你添加资产来生成和调试项目时，请选择“是”。如果 Visual Studio Code 不提供添加生成和调试资产的功能，请选择“视图”>“命令面板”，然后在搜索框中输入“.NET”。从命令列表中选择 .NET: Generate Assets for Build and Debug 命令。

Visual Studio Code 添加一个包含生成的 launch.json 和 tasks.json 文件的 .vscode 文件夹。

添加所需的 NuGet 包

gRPC 客户端项目需要以下 NuGet 包：

Grpc.Net.Client，其中包含 .NET Core 客户端。
Google.Protobuf 包含适用于 C# 的 Protobuf 消息。
Grpc.Tools，其中包含适用于 Protobuf 文件的 C# 工具支持。运行时不需要工具包，因此依赖项标记为 PrivateAssets="All"。

通过包管理器控制台 (PMC) 或管理 NuGet 包来安装包。

用于安装包的 PMC 选项

从 Visual Studio 中，依次选择“工具”>“NuGet 包管理器”>“包管理器控制台”
从“包管理器控制台”窗口中，运行 cd GrpcGreeterClient 以将目录更改为包含 GrpcGreeterClient.csproj 文件的文件夹。

运行以下命令：

Install-Package Grpc.Net.Client
Install-Package Google.Protobuf
Install-Package Grpc.Tools

管理 NuGet 包选项以安装包

右键单击“解决方案资源管理器”>“管理 NuGet 包”中的项目。
选择“浏览”选项卡。
在搜索框中输入 Grpc.Net.Client。
从“浏览”选项卡中选择“Grpc.Net.Client”包，然后选择“安装” 。
为 Google.Protobuf 和 Grpc.Tools 重复这些步骤。

从“集成终端”运行以下命令：

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package Grpc.Tools

在 Solution Pad 中，右键单击 GrpcGreeterClient 项目，然后选择“管理 NuGet 包”。
在搜索框中输入 Grpc.Net.Client。
从结果窗格中选择 Grpc.Net.Client 包并选择“添加包”。
在“选择项目”中，选择“确定”。
出现“许可证接受”对话框时，如果你同意许可条款，请选择“接受”。
为 Google.Protobuf 和 Grpc.Tools 重复这些步骤。

添加 greet.proto

在 gRPC 客户端项目中创建 Protos 文件夹。
从 gRPC Greeter 服务将 Protos\greet.proto 文件复制到 gRPC 客户端项目中的 Protos 文件夹。
将 greet.proto 文件中的命名空间更新为项目的命名空间：
```
option csharp_namespace = "GrpcGreeterClient";
```
编辑 GrpcGreeterClient.csproj 项目文件：

右键单击项目，并选择“编辑项目文件”。

添加具有引用 greet.proto 文件的 <Protobuf> 元素的项组：

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

创建 Greeter 客户端

构建客户端项目，以在 GrpcGreeterClient 命名空间中创建类型。

注意

GrpcGreeterClient 类型是由生成进程自动生成的。工具包 Grpc.Tools 基于 greet.proto 文件生成以下文件：

GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\Greet.cs：用于填充、序列化和检索请求和响应消息类型的协议缓冲区代码。
GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\GreetGrpc.cs：包含生成的客户端类。

有关 Grpc.Tools 自动生成的 C# 资产的详细信息，请参阅使用 C# 的 gRPC 服务：生成的 C# 资产。

使用以下代码更新 gRPC 客户端 Program.cs 文件。

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();

在前面突出显示的代码中，将 localhost 端口号 7042 替换为在 GrpcGreeter 服务项目的 Properties/launchSettings.json 中指定的 HTTPS 端口号。

Program.cs 包含 gRPC 客户端的入口点和逻辑。

通过以下方式创建 Greeter 客户端：

实例化 GrpcChannel，使其包含用于创建到 gRPC 服务的连接的信息。
使用 GrpcChannel 构造 Greeter 客户端：

// 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();

Greeter 客户端会调用异步 SayHello 方法。随即显示 SayHello 调用的结果：

// 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();

使用 gRPC Greeter 服务测试 gRPC 客户端

通过添加以下突出显示的行来更新 appsettings.Development.json 文件：

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

在 Greeter 服务中，按 Ctrl+F5 在不使用调试程序的情况下启动服务器。
在 GrpcGreeterClient 项目中，按 Ctrl+F5 在不使用调试程序的情况下启动客户端。

客户端向该服务发送一条包含具有其名称“GreeterClient”的消息的问候信息。该服务会发送“Hello GreeterClient”消息作为答复。 “Hello GreeterClient”答复将在命令提示符中显示：

Greeting: Hello GreeterClient
Press any key to exit...

gRPC 服务在写入命令提示符的日志中记录成功调用的详细信息：

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

注意

本文中的代码需要 ASP.NET Core HTTPS 开发证书来保护 gRPC 服务。如果 .NET gRPC 客户端失败并显示消息 The remote certificate is invalid according to the validation procedure. 或 The SSL connection could not be established.，则开发证书不受信任。要解决此问题，请参阅使用不受信任/无效的证书调用 gRPC 服务。

后续步骤

本教程演示了如何创建 .NET Core gRPC 客户端和 ASP.NET Core gRPC 服务器。最后会生成与 gRPC Greeter 服务进行通信的 gRPC 客户端。

在本教程中，你将了解：

创建 gRPC 服务器。
创建 gRPC 客户端。
使用 gRPC Greeter 服务测试 gRPC 客户端。

先决条件

带有 ASP.NET 和 Web 开发工作负载的 Visual Studio 2022。

创建 gRPC 服务

启动 Visual Studio 2022 并选择“创建新项目”。
在“创建新项目”对话框中，搜索 gRPC。选择“ASP.NET Core gRPC 服务”，并选择“下一步” 。
在“配置新项目”对话框中，为“项目名称”输入 GrpcGreeter。将项目命名为“GrpcGreeter”非常重要，这样在复制和粘贴代码时命名空间就会匹配。
选择“下一页”。
在“其他信息”对话框中，选择“.NET 6.0 (长期支持)”，然后选择“创建”。

本教程假定用户熟悉 VS Code。有关详细信息，请参阅 VS Code入门。

从“终端”菜单中选择“新建终端”以打开集成终端。
更改为将包含项目的目录 (cd)。
运行以下命令：
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
dotnet new 命令将在 GrpcGreeter 文件夹中创建一个新 gRPC 服务。

code 命令会在 Visual Studio Code 的当前实例中打开“GrpcGreeter”项目文件夹。

Visual Studio Code 可能会显示一个对话框，询问：“你是否信任此文件夹中的文件作者?”

如果你信任父文件夹中的所有文件，请选择“信任父文件夹中所有文件的作者”。
选择“是，我信任所有作者”，因为项目文件夹包含 .NET 生成的文件。
当 Visual Studio Code 请求你添加资产来生成和调试项目时，请选择“是”。如果 Visual Studio Code 不提供添加生成和调试资产的功能，请选择“视图”>“命令面板”，然后在搜索框中输入“.NET”。从命令列表中选择 .NET: Generate Assets for Build and Debug 命令。

Visual Studio Code 添加一个包含生成的 launch.json 和 tasks.json 文件的 .vscode 文件夹。

运行服务

按 Ctrl+F5 以在不使用调试程序的情况下运行。

如果尚未将项目配置为使用 SSL，Visual Studio 显示以下对话：

如果信任 IIS Express SSL 证书，请选择“是”。

将显示以下对话框：

如果你同意信任开发证书，请选择“是”。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

Visual Studio：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，如 http://localhost:7042。
  - 端口：随机分配给应用的端口号。
  - localhost：本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。

通过运行以下命令来信任 HTTPS 开发证书：
```
dotnet dev-certs https --trust
```
上述命令在 Linux 上无效。有关信任证书的详细信息，请参阅 Linux 发行版的文档。

如果证书以前不受信任，上述命令显示以下对话：
如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

按 Ctrl-F5 以在不使用调试程序的情况下运行。

Visual Studio Code：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，如 http://localhost:7042。
  - 端口：随机分配给应用的端口号。
  - localhost：本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。

选择“调试”>“在不调试的情况下启动”以启动应用。

Visual Studio for Mac：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，如 http://localhost:7042。
  - 端口：随机分配给应用的端口号。
  - localhost：本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。
Visual Studio for Mac 会显示以下弹出窗口：

如果你信任开发证书，请选择“安装并信任”。

将显示以下对话框：

输入你的密码，然后选择“更新设置”

如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。
在 Visual Studio 中，按“Opt-Cmd-Return”可在不使用调试器的情况下运行。或者，导航到菜单栏，转到“运行”>“在不调试的情况下启动”。

Visual Studio 启动 Kestrel，启动浏览器，并导航到随机分配的端口（例如 http://localhost:7042）。

日志显示在 https://localhost:<port> 上侦听的服务，其中 <port> 是在 Properties/launchSettings.json 中创建和设置项目时随机分配的 localhost 端口号。

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

注意

macOS 不支持 ASP.NET Core gRPC 及 TLS。在 macOS 上成功运行 gRPC 服务需要其他配置。有关详细信息，请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用。

检查项目文件

GrpcGreeter 项目文件：

Protos/greet.proto：定义 Greeter gRPC，并用于生成 gRPC 服务器资产。有关详细信息，请参阅 gRPC 介绍。
Services 文件夹：包含 Greeter 服务的实现。
appSettings.json：包含配置数据，如 Kestrel 使用的协议。有关详细信息，请参阅 ASP.NET Core 中的配置。
Program.cs，其中包含：
- gRPC 服务的入口点。有关详细信息，请参阅 ASP.NET Core 中的 .NET 通用主机。
- 配置应用行为的代码。有关详细信息，请参阅应用启动。

在 .NET 控制台应用中创建 gRPC 客户端

打开 Visual Studio 的第二个实例并选择“创建新项目”。
在“创建新项目”对话框中，选择“控制台应用程序”，然后选择“下一步” 。
在“项目名称”文本框中，输入“GrpcGreeterClient”，然后选择“下一步” 。
在“其他信息”对话框中，选择“.NET 6.0 (长期支持)”，然后选择“创建”。

打开集成终端。
将目录 (cd) 更改为项目的文件夹。

运行以下命令：

dotnet new console -o GrpcGreeterClient
code -r GrpcGreeterClient

Visual Studio Code 可能会显示一个对话框，询问：“你是否信任此文件夹中的文件作者?”

如果你信任父文件夹中的所有文件，请选择“信任父文件夹中所有文件的作者”。
选择“是，我信任所有作者”，因为项目文件夹包含 .NET 生成的文件。
当 Visual Studio Code 请求你添加资产来生成和调试项目时，请选择“是”。如果 Visual Studio Code 不提供添加生成和调试资产的功能，请选择“视图”>“命令面板”，然后在搜索框中输入“.NET”。从命令列表中选择 .NET: Generate Assets for Build and Debug 命令。

Visual Studio Code 添加一个包含生成的 launch.json 和 tasks.json 文件的 .vscode 文件夹。

添加所需的 NuGet 包

gRPC 客户端项目需要以下 NuGet 包：

Grpc.Net.Client，其中包含 .NET Core 客户端。
Google.Protobuf 包含适用于 C# 的 Protobuf 消息。
Grpc.Tools，其中包含适用于 Protobuf 文件的 C# 工具支持。运行时不需要工具包，因此依赖项标记为 PrivateAssets="All"。

通过包管理器控制台 (PMC) 或管理 NuGet 包来安装包。

用于安装包的 PMC 选项

从 Visual Studio 中，依次选择“工具”>“NuGet 包管理器”>“包管理器控制台”
从“包管理器控制台”窗口中，运行 cd GrpcGreeterClient 以将目录更改为包含 GrpcGreeterClient.csproj 文件的文件夹。

运行以下命令：

Install-Package Grpc.Net.Client
Install-Package Google.Protobuf
Install-Package Grpc.Tools

管理 NuGet 包选项以安装包

右键单击“解决方案资源管理器”>“管理 NuGet 包”中的项目。
选择“浏览”选项卡。
在搜索框中输入 Grpc.Net.Client。
从“浏览”选项卡中选择“Grpc.Net.Client”包，然后选择“安装” 。
为 Google.Protobuf 和 Grpc.Tools 重复这些步骤。

从“集成终端”运行以下命令：

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package Grpc.Tools

在 Solution Pad 中，右键单击 GrpcGreeterClient 项目，然后选择“管理 NuGet 包”。
在搜索框中输入 Grpc.Net.Client。
从结果窗格中选择 Grpc.Net.Client 包并选择“添加包”。
在“选择项目”中，选择“确定”。
出现“许可证接受”对话框时，如果你同意许可条款，请选择“接受”。
为 Google.Protobuf 和 Grpc.Tools 重复这些步骤。

添加 greet.proto

在 gRPC 客户端项目中创建 Protos 文件夹。
从 gRPC Greeter 服务将 Protos\greet.proto 文件复制到 gRPC 客户端项目中的 Protos 文件夹。
将 greet.proto 文件中的命名空间更新为项目的命名空间：
```
option csharp_namespace = "GrpcGreeterClient";
```
编辑 GrpcGreeterClient.csproj 项目文件：

右键单击项目，并选择“编辑项目文件”。

添加具有引用 greet.proto 文件的 <Protobuf> 元素的项组：

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

创建 Greeter 客户端

构建客户端项目，以在 GrpcGreeterClient 命名空间中创建类型。

注意

GrpcGreeterClient 类型是由生成进程自动生成的。工具包 Grpc.Tools 基于 greet.proto 文件生成以下文件：

GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\Greet.cs：用于填充、序列化和检索请求和响应消息类型的协议缓冲区代码。
GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\GreetGrpc.cs：包含生成的客户端类。

有关 Grpc.Tools 自动生成的 C# 资产的详细信息，请参阅使用 C# 的 gRPC 服务：生成的 C# 资产。

使用以下代码更新 gRPC 客户端 Program.cs 文件。

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();

在前面突出显示的代码中，将 localhost 端口号 7042 替换为在 GrpcGreeter 服务项目的 Properties/launchSettings.json 中指定的 HTTPS 端口号。

Program.cs 包含 gRPC 客户端的入口点和逻辑。

通过以下方式创建 Greeter 客户端：

实例化 GrpcChannel，使其包含用于创建到 gRPC 服务的连接的信息。
使用 GrpcChannel 构造 Greeter 客户端：

// 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();

Greeter 客户端会调用异步 SayHello 方法。随即显示 SayHello 调用的结果：

// 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();

使用 gRPC Greeter 服务测试 gRPC 客户端

通过添加以下突出显示的行来更新 appsettings.Development.json 文件：

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

在 Greeter 服务中，按 Ctrl+F5 在不使用调试程序的情况下启动服务器。
在 GrpcGreeterClient 项目中，按 Ctrl+F5 在不使用调试程序的情况下启动客户端。

根据前面的 macOS 上 HTTP/2 TLS 问题的解决方法所述，需要将客户端中的通道地址更新为 GrpcGreeter 服务的 launchSetting.json 中的匹配端口“http://localhost:5000"”。更新 GrpcGreeterClient/Program.cs 的第 13 行以读取：
```
using var channel = GrpcChannel.ForAddress("http://localhost:5000");
```
启动 Greeter 服务。
启动客户端。

Greeting: Hello GreeterClient
Press any key to exit...

gRPC 服务在写入命令提示符的日志中记录成功调用的详细信息：

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

注意

后续步骤

本教程演示了如何创建 .NET Core gRPC 客户端和 ASP.NET Core gRPC 服务器。最后会生成与 gRPC Greeter 服务进行通信的 gRPC 客户端。

在本教程中，你将了解：

创建 gRPC 服务器。
创建 gRPC 客户端。
使用 gRPC Greeter 服务测试 gRPC 客户端。

先决条件

带有 ASP.NET 和 Web 开发工作负载的 Visual Studio 2022。
.NET 6.0 SDK

创建 gRPC 服务

启动 Visual Studio 2022 并选择“创建新项目”。
在“创建新项目”对话框中，搜索 gRPC。选择“ASP.NET Core gRPC 服务”，并选择“下一步” 。
在“配置新项目”对话框中，为“项目名称”输入 GrpcGreeter。将项目命名为“GrpcGreeter”非常重要，这样在复制和粘贴代码时命名空间就会匹配。
选择“下一页”。
在“其他信息”对话框中，选择“.NET 6.0 (长期支持)”，然后选择“创建”。

本教程假定用户熟悉 VS Code。有关详细信息，请参阅 VS Code入门。

从“终端”菜单中选择“新建终端”以打开集成终端。
更改为将包含项目的目录 (cd)。
运行以下命令：
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
dotnet new 命令将在 GrpcGreeter 文件夹中创建一个新 gRPC 服务。

code 命令会在 Visual Studio Code 的当前实例中打开“GrpcGreeter”项目文件夹。

Visual Studio Code 可能会显示一个对话框，询问：“你是否信任此文件夹中的文件作者?”

如果你信任父文件夹中的所有文件，请选择“信任父文件夹中所有文件的作者”。
选择“是，我信任所有作者”，因为项目文件夹包含 .NET 生成的文件。
当 Visual Studio Code 请求你添加资产来生成和调试项目时，请选择“是”。如果 Visual Studio Code 不提供添加生成和调试资产的功能，请选择“视图”>“命令面板”，然后在搜索框中输入“.NET”。从命令列表中选择 .NET: Generate Assets for Build and Debug 命令。

Visual Studio Code 添加一个包含生成的 launch.json 和 tasks.json 文件的 .vscode 文件夹。

运行服务

按 Ctrl+F5 以在不使用调试程序的情况下运行。

如果尚未将项目配置为使用 SSL，Visual Studio 显示以下对话：

如果信任 IIS Express SSL 证书，请选择“是”。

将显示以下对话框：

如果你同意信任开发证书，请选择“是”。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

Visual Studio：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，如 http://localhost:7042。
  - 端口：随机分配给应用的端口号。
  - localhost：本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。

通过运行以下命令来信任 HTTPS 开发证书：
```
dotnet dev-certs https --trust
```
上述命令在 Linux 上无效。有关信任证书的详细信息，请参阅 Linux 发行版的文档。

如果证书以前不受信任，上述命令显示以下对话：
如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

按 Ctrl-F5 以在不使用调试程序的情况下运行。

Visual Studio Code：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，如 http://localhost:7042。
  - 端口：随机分配给应用的端口号。
  - localhost：本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。

选择“调试”>“在不调试的情况下启动”以启动应用。

Visual Studio for Mac：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，如 http://localhost:7042。
  - 端口：随机分配给应用的端口号。
  - localhost：本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。
Visual Studio for Mac 会显示以下弹出窗口：

如果你信任开发证书，请选择“安装并信任”。

将显示以下对话框：

输入你的密码，然后选择“更新设置”

如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。
在 Visual Studio 中，按“Opt-Cmd-Return”可在不使用调试器的情况下运行。或者，导航到菜单栏，转到“运行”>“在不调试的情况下启动”。

Visual Studio 启动 Kestrel，启动浏览器，并导航到随机分配的端口（例如 http://localhost:7042）。

日志显示在 https://localhost:<port> 上侦听的服务，其中 <port> 是在 Properties/launchSettings.json 中创建和设置项目时随机分配的 localhost 端口号。

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

注意

macOS 不支持 ASP.NET Core gRPC 及 TLS。在 macOS 上成功运行 gRPC 服务需要其他配置。有关详细信息，请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用。

检查项目文件

GrpcGreeter 项目文件：

Protos/greet.proto：定义 Greeter gRPC，并用于生成 gRPC 服务器资产。有关详细信息，请参阅 gRPC 介绍。
Services 文件夹：包含 Greeter 服务的实现。
appSettings.json：包含配置数据，如 Kestrel 使用的协议。有关详细信息，请参阅 ASP.NET Core 中的配置。
Program.cs，其中包含：
- gRPC 服务的入口点。有关详细信息，请参阅 ASP.NET Core 中的 .NET 通用主机。
- 配置应用行为的代码。有关详细信息，请参阅应用启动。

在 .NET 控制台应用中创建 gRPC 客户端

打开 Visual Studio 的第二个实例并选择“创建新项目”。
在“创建新项目”对话框中，选择“控制台应用程序”，然后选择“下一步” 。
在“项目名称”文本框中，输入“GrpcGreeterClient”，然后选择“下一步” 。
在“其他信息”对话框中，选择“.NET 6.0 (长期支持)”，然后选择“创建”。

打开集成终端。
将目录 (cd) 更改为项目的文件夹。

运行以下命令：

dotnet new console -o GrpcGreeterClient
code -r GrpcGreeterClient

Visual Studio Code 可能会显示一个对话框，询问：“你是否信任此文件夹中的文件作者?”

如果你信任父文件夹中的所有文件，请选择“信任父文件夹中所有文件的作者”。
选择“是，我信任所有作者”，因为项目文件夹包含 .NET 生成的文件。
当 Visual Studio Code 请求你添加资产来生成和调试项目时，请选择“是”。如果 Visual Studio Code 不提供添加生成和调试资产的功能，请选择“视图”>“命令面板”，然后在搜索框中输入“.NET”。从命令列表中选择 .NET: Generate Assets for Build and Debug 命令。

Visual Studio Code 添加一个包含生成的 launch.json 和 tasks.json 文件的 .vscode 文件夹。

添加所需的 NuGet 包

gRPC 客户端项目需要以下 NuGet 包：

Grpc.Net.Client，其中包含 .NET Core 客户端。
Google.Protobuf 包含适用于 C# 的 Protobuf 消息。
Grpc.Tools，其中包含适用于 Protobuf 文件的 C# 工具支持。运行时不需要工具包，因此依赖项标记为 PrivateAssets="All"。

通过包管理器控制台 (PMC) 或管理 NuGet 包来安装包。

用于安装包的 PMC 选项

从 Visual Studio 中，依次选择“工具”>“NuGet 包管理器”>“包管理器控制台”
从“包管理器控制台”窗口中，运行 cd GrpcGreeterClient 以将目录更改为包含 GrpcGreeterClient.csproj 文件的文件夹。

运行以下命令：

Install-Package Grpc.Net.Client
Install-Package Google.Protobuf
Install-Package Grpc.Tools

管理 NuGet 包选项以安装包

右键单击“解决方案资源管理器”>“管理 NuGet 包”中的项目。
选择“浏览”选项卡。
在搜索框中输入 Grpc.Net.Client。
从“浏览”选项卡中选择“Grpc.Net.Client”包，然后选择“安装” 。
为 Google.Protobuf 和 Grpc.Tools 重复这些步骤。

从“集成终端”运行以下命令：

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package Grpc.Tools

在 Solution Pad 中，右键单击 GrpcGreeterClient 项目，然后选择“管理 NuGet 包”。
在搜索框中输入 Grpc.Net.Client。
从结果窗格中选择 Grpc.Net.Client 包并选择“添加包”。
在“选择项目”中，选择“确定”。
出现“许可证接受”对话框时，如果你同意许可条款，请选择“接受”。
为 Google.Protobuf 和 Grpc.Tools 重复这些步骤。

添加 greet.proto

在 gRPC 客户端项目中创建 Protos 文件夹。
从 gRPC Greeter 服务将 Protos\greet.proto 文件复制到 gRPC 客户端项目中的 Protos 文件夹。
将 greet.proto 文件中的命名空间更新为项目的命名空间：
```
option csharp_namespace = "GrpcGreeterClient";
```
编辑 GrpcGreeterClient.csproj 项目文件：

右键单击项目，并选择“编辑项目文件”。

添加具有引用 greet.proto 文件的 <Protobuf> 元素的项组：

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

创建 Greeter 客户端

构建客户端项目，以在 GrpcGreeterClient 命名空间中创建类型。

注意

GrpcGreeterClient 类型是由生成进程自动生成的。工具包 Grpc.Tools 基于 greet.proto 文件生成以下文件：

GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\Greet.cs：用于填充、序列化和检索请求和响应消息类型的协议缓冲区代码。
GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\GreetGrpc.cs：包含生成的客户端类。

有关 Grpc.Tools 自动生成的 C# 资产的详细信息，请参阅使用 C# 的 gRPC 服务：生成的 C# 资产。

使用以下代码更新 gRPC 客户端 Program.cs 文件。

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();

在前面突出显示的代码中，将 localhost 端口号 7042 替换为在 GrpcGreeter 服务项目的 Properties/launchSettings.json 中指定的 HTTPS 端口号。

Program.cs 包含 gRPC 客户端的入口点和逻辑。

通过以下方式创建 Greeter 客户端：

实例化 GrpcChannel，使其包含用于创建到 gRPC 服务的连接的信息。
使用 GrpcChannel 构造 Greeter 客户端：

// 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();

Greeter 客户端会调用异步 SayHello 方法。随即显示 SayHello 调用的结果：

// 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();

使用 gRPC Greeter 服务测试 gRPC 客户端

在 Greeter 服务中，按 Ctrl+F5 在不使用调试程序的情况下启动服务器。
在 GrpcGreeterClient 项目中，按 Ctrl+F5 在不使用调试程序的情况下启动客户端。

根据前面的 macOS 上 HTTP/2 TLS 问题的解决方法所述，需要将客户端中的通道地址更新为 GrpcGreeter 服务的 launchSetting.json 中的匹配端口“http://localhost:5000"”。更新 GrpcGreeterClient/Program.cs 的第 13 行以读取：
```
using var channel = GrpcChannel.ForAddress("http://localhost:5000");
```
启动 Greeter 服务。
启动客户端。

Greeting: Hello GreeterClient
Press any key to exit...

gRPC 服务在写入命令提示符的日志中记录成功调用的详细信息：

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

通过添加以下行来更新 appsettings.Development.json 文件：

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

注意

后续步骤

本教程演示了如何创建 .NET Core gRPC 客户端和 ASP.NET Core gRPC 服务器。

最后会生成与 gRPC Greeter 服务进行通信的 gRPC 客户端。

查看或下载示例代码（如何下载）。

在本教程中，你将了解：

创建 gRPC 服务器。
创建 gRPC 客户端。
使用 gRPC Greeter 服务测试 gRPC 客户端。

先决条件

具有“ASP.NET 和 Web 开发”工作负载的 Visual Studio 2019 16.8 或更高版本
.NET 5.0 SDK

创建 gRPC 服务

启动 Visual Studio 并选择“创建新项目”。
在“创建新项目”对话框中，选择“gRPC 服务”，然后选择“下一步” 。
在“配置新项目”对话框中，为“项目名称”输入 GrpcGreeter。将项目命名为“GrpcGreeter”非常重要，这样在复制和粘贴代码时命名空间就会匹配。
选择“下一页”。
在“其他信息”对话框中，选择“目标框架”下拉列表中的“.NET 5.0” 。
选择“创建” 。

本教程假定用户熟悉 VS Code。有关详细信息，请参阅 VS Code入门。

从“终端”菜单中选择“新建终端”以打开集成终端。
更改为将包含项目的目录 (cd)。
运行以下命令：
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
dotnet new 命令将在 GrpcGreeter 文件夹中创建一个新 gRPC 服务。

code 命令会在 Visual Studio Code 的当前实例中打开“GrpcGreeter”项目文件夹。

Visual Studio Code 可能会显示一个对话框，询问：“你是否信任此文件夹中的文件作者?”

如果你信任父文件夹中的所有文件，请选择“信任父文件夹中所有文件的作者”。
选择“是，我信任所有作者”，因为项目文件夹包含 .NET 生成的文件。
当 Visual Studio Code 请求你添加资产来生成和调试项目时，请选择“是”。如果 Visual Studio Code 不提供添加生成和调试资产的功能，请选择“视图”>“命令面板”，然后在搜索框中输入“.NET”。从命令列表中选择 .NET: Generate Assets for Build and Debug 命令。

Visual Studio Code 添加一个包含生成的 launch.json 和 tasks.json 文件的 .vscode 文件夹。

运行服务

按 Ctrl+F5 以在不使用调试程序的情况下运行。

如果尚未将项目配置为使用 SSL，Visual Studio 显示以下对话：

如果信任 IIS Express SSL 证书，请选择“是”。

将显示以下对话框：

如果你同意信任开发证书，请选择“是”。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

Visual Studio 启动 IIS Express 并运行应用。地址栏显示 localhost:port#，而不是显示 example.com。这是因为 localhost 是本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。 Visual Studio 创建 Web 项目时，Web 服务器使用的是随机端口。

通过运行以下命令来信任 HTTPS 开发证书：
```
dotnet dev-certs https --trust
```
上述命令在 Linux 上无效。有关信任证书的详细信息，请参阅 Linux 发行版的文档。

如果证书以前不受信任，上述命令显示以下对话：
如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

按 Ctrl-F5 以在不使用调试程序的情况下运行。

Visual Studio Code 启动 Kestrel，启动浏览器并导航到 http://localhost:5001。地址栏显示 localhost:port#，而不是显示 example.com。这是因为 localhost 是本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。

选择“运行”>“开始执行(不调试)”以启动应用。

Visual Studio for Mac：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，其中 port 是随机选择的端口号。
Visual Studio for Mac 会显示以下弹出窗口：

如果你信任开发证书，请选择“是”。

将显示以下对话框：

输入你的密码，然后选择“确定”

如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。
在 Visual Studio 中，按“Opt-Cmd-Return”可在不使用调试器的情况下运行。或者，导航到菜单栏，转到“运行”>“在不调试的情况下启动”。

Visual Studio 启动 Kestrel，启动浏览器并导航到 http://localhost:5001。

日志显示该服务正在侦听 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

注意

gRPC 模板配置为使用传输层安全性 (TLS)。 gRPC 客户端需要使用 HTTPS 调用服务器。

macOS 不支持 ASP.NET Core gRPC 及 TLS。在 macOS 上成功运行 gRPC 服务需要其他配置。有关详细信息，请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用。

检查项目文件

GrpcGreeter 项目文件：

greet.proto：Protos/greet.proto 文件定义 Greeter gRPC，且用于生成 gRPC 服务器资产。有关详细信息，请参阅 gRPC 介绍。
Services 文件夹：包含 Greeter 服务的实现。
appsettings.json：包含配置数据，例如 Kestrel 使用的协议。有关详细信息，请参阅 ASP.NET Core 中的配置。
Program.cs：包含 gRPC 服务的入口点。有关详细信息，请参阅 ASP.NET Core 中的 .NET 通用主机。
Startup.cs：包含配置应用行为的代码。有关详细信息，请参阅应用启动。

在 .NET 控制台应用中创建 gRPC 客户端

打开 Visual Studio 的第二个实例并选择“创建新项目”。
在“创建新项目”对话框中，选择“控制台应用(.NET Core)”，然后选择“下一步” 。
在“项目名称”文本框中，输入“GrpcGreeterClient”，然后选择“创建” 。

打开集成终端。
将目录 (cd) 更改为项目的文件夹。

运行以下命令：

dotnet new console -o GrpcGreeterClient
code -r GrpcGreeterClient

当 Visual Studio Code 请求你添加资产来生成和调试项目时，请选择“是”。

Visual Studio Code 添加一个包含生成的 launch.json 和 tasks.json 文件的 .vscode 文件夹。

添加所需的包

gRPC 客户端项目需要以下包：

Grpc.Net.Client，其中包含 .NET Core 客户端。
Google.Protobuf 包含适用于 C# 的 Protobuf 消息。
Grpc.Tools 包含适用于 Protobuf 文件的 C# 工具支持。运行时不需要工具包，因此依赖项标记为 PrivateAssets="All"。

通过包管理器控制台 (PMC) 或管理 NuGet 包来安装包。

用于安装包的 PMC 选项

从 Visual Studio 中，依次选择“工具”>“NuGet 包管理器”>“包管理器控制台”
从“包管理器控制台”窗口中，运行 cd GrpcGreeterClient 以将目录更改为包含 GrpcGreeterClient.csproj 文件的文件夹。

运行以下命令：

Install-Package Grpc.Net.Client
Install-Package Google.Protobuf
Install-Package Grpc.Tools

管理 NuGet 包选项以安装包

右键单击“解决方案资源管理器”>“管理 NuGet 包”中的项目。
选择“浏览”选项卡。
在搜索框中输入 Grpc.Net.Client。
从“浏览”选项卡中选择“Grpc.Net.Client”包，然后选择“安装” 。
为 Google.Protobuf 和 Grpc.Tools 重复这些步骤。

从“集成终端”运行以下命令：

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package Grpc.Tools

添加 greet.proto

在 gRPC 客户端项目中创建 Protos 文件夹。
从 gRPC Greeter 服务将 Protos\greet.proto 文件复制到 gRPC 客户端项目中的 Protos 文件夹。
将 greet.proto 文件中的命名空间更新为项目的命名空间：
```
option csharp_namespace = "GrpcGreeterClient";
```
编辑 GrpcGreeterClient.csproj 项目文件：
右键单击项目，并选择“编辑项目文件”。

选择 GrpcGreeterClient.csproj 文件。

右键单击项目，并选择“编辑项目文件”。

添加具有引用 greet.proto 文件的 <Protobuf> 元素的项组：

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

创建 Greeter 客户端

构建客户端项目，以在 GrpcGreeterClient 命名空间中创建类型。

注意

GrpcGreeterClient 类型是由生成进程自动生成的。工具包 Grpc.Tools 基于 greet.proto 文件生成以下文件：

GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\Greet.cs：用于填充、序列化和检索请求和响应消息类型的协议缓冲区代码。
GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\GreetGrpc.cs：包含生成的客户端类。

有关 Grpc.Tools 自动生成的 C# 资产的详细信息，请参阅使用 C# 的 gRPC 服务：生成的 C# 资产。

使用以下代码更新 gRPC 客户端 Program.cs 文件：

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 包含 gRPC 客户端的入口点和逻辑。

通过以下方式创建 Greeter 客户端：

实例化 GrpcChannel，使其包含用于创建到 gRPC 服务的连接的信息。
使用 GrpcChannel 构造 Greeter 客户端：

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();
}

Greeter 客户端会调用异步 SayHello 方法。随即显示 SayHello 调用的结果：

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();
}

使用 gRPC Greeter 服务测试 gRPC 客户端

在 Greeter 服务中，按 Ctrl+F5 在不使用调试程序的情况下启动服务器。
在 GrpcGreeterClient 项目中，按 Ctrl+F5 在不使用调试程序的情况下启动客户端。

根据前面的 macOS 上 HTTP/2 TLS 问题的解决方法所述，需要将客户端中的通道地址更新为“http://localhost:5000"”。更新 GrpcGreeterClient/Program.cs 的第 13 行以读取：
```
using var channel = GrpcChannel.ForAddress("http://localhost:5000");
```
启动 Greeter 服务。
启动客户端。

Greeting: Hello GreeterClient
Press any key to exit...

gRPC 服务在写入命令提示符的日志中记录成功调用的详细信息：

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

注意

后续步骤

本教程演示了如何创建 .NET Core gRPC 客户端和 ASP.NET Core gRPC 服务器。

最后会生成与 gRPC Greeter 服务进行通信的 gRPC 客户端。

查看或下载示例代码（如何下载）。

在本教程中，你将了解：

创建 gRPC 服务器。
创建 gRPC 客户端。
使用 gRPC Greeter 服务测试 gRPC 客户端。

先决条件

具有“ASP.NET 和 Web 开发”工作负载的 Visual Studio 2019 16.4 或更高版本
.NET Core 3.1 SDK

创建 gRPC 服务

启动 Visual Studio 并选择“创建新项目”。或者，从 Visual Studio“文件”菜单中选择“新建”>“项目” 。
在“创建新项目”对话框中，选择“gRPC 服务”，然后选择“下一步” ：
将项目命名为 GrpcGreeter。将项目命名为“GrpcGreeter”非常重要，这样在复制和粘贴代码时命名空间就会匹配。
选择“创建”。
在“创建新 gRPC 服务”对话框中：
- 选择“gRPC 服务”模板。
- 选择“创建”。

打开集成终端。
将目录 (cd) 更改为项目的文件夹。
运行以下命令：
```
dotnet new grpc -o GrpcGreeter
code -r GrpcGreeter
```
- dotnet new 命令将在 GrpcGreeter 文件夹中创建一个新 gRPC 服务。
- code 命令将在新 Visual Studio Code 实例中打开 GrpcGreeter 文件夹。
一个对话框随即出现，其中包含：“‘GrpcGreeter’中缺少进行生成和调试所需的资产”。是否添加它们?”
选择 “是” 。

运行服务

按 Ctrl+F5 以在不使用调试程序的情况下运行。

如果尚未将项目配置为使用 SSL，Visual Studio 显示以下对话：

如果信任 IIS Express SSL 证书，请选择“是”。

将显示以下对话框：

如果你同意信任开发证书，请选择“是”。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

Visual Studio 启动 IIS Express 并运行应用。地址栏显示 localhost:port#，而不是显示 example.com。这是因为 localhost 是本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。 Visual Studio 创建 Web 项目时，Web 服务器使用的是随机端口。

通过运行以下命令来信任 HTTPS 开发证书：
```
dotnet dev-certs https --trust
```
上述命令在 Linux 上无效。有关信任证书的详细信息，请参阅 Linux 发行版的文档。

如果证书以前不受信任，上述命令显示以下对话：
如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。

有关信任 Firefox 浏览器的信息，请参阅 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 证书错误。

按 Ctrl-F5 以在不使用调试程序的情况下运行。

Visual Studio Code 启动 Kestrel，启动浏览器并导航到 http://localhost:5001。地址栏显示 localhost:port#，而不是显示 example.com。这是因为 localhost 是本地计算机的标准主机名。 Localhost 仅为来自本地计算机的 Web 请求提供服务。

选择“运行”>“开始执行(不调试)”以启动应用。

Visual Studio for Mac：
- 启动 Kestrel 服务器。
- 启动浏览器。
- 导航到 http://localhost:port，其中 port 是随机选择的端口号。
Visual Studio for Mac 会显示以下弹出窗口：

如果你信任开发证书，请选择“是”。

将显示以下对话框：

输入你的密码，然后选择“确定”

如果你同意信任开发证书，请选择“是”。

有关详细信息，请参阅信任 ASP.NET Core HTTPS 开发证书。
在 Visual Studio 中，按“Opt-Cmd-Return”可在不使用调试器的情况下运行。或者，导航到菜单栏，转到“运行”>“在不调试的情况下启动”。

Visual Studio 启动 Kestrel，启动浏览器并导航到 http://localhost:5001。

日志显示该服务正在侦听 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

注意

gRPC 模板配置为使用传输层安全性 (TLS)。 gRPC 客户端需要使用 HTTPS 调用服务器。

macOS 不支持 ASP.NET Core gRPC 及 TLS。在 macOS 上成功运行 gRPC 服务需要其他配置。有关详细信息，请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用。

检查项目文件

GrpcGreeter 项目文件：

greet.proto：Protos/greet.proto 文件定义 Greeter gRPC，且用于生成 gRPC 服务器资产。有关详细信息，请参阅 gRPC 介绍。
Services 文件夹：包含 Greeter 服务的实现。
appsettings.json：包含配置数据，例如 Kestrel 使用的协议。有关详细信息，请参阅 ASP.NET Core 中的配置。
Program.cs：包含 gRPC 服务的入口点。有关详细信息，请参阅 ASP.NET Core 中的 .NET 通用主机。
Startup.cs：包含配置应用行为的代码。有关详细信息，请参阅应用启动。

在 .NET 控制台应用中创建 gRPC 客户端

打开 Visual Studio 的第二个实例并选择“创建新项目”。
在“创建新项目”对话框中，选择“控制台应用(.NET Core)”，然后选择“下一步” 。
在“项目名称”文本框中，输入“GrpcGreeterClient”，然后选择“创建” 。

添加所需的包

gRPC 客户端项目需要以下包：

Grpc.Net.Client，其中包含 .NET Core 客户端。
Google.Protobuf 包含适用于 C# 的 Protobuf 消息。
Grpc.Tools 包含适用于 Protobuf 文件的 C# 工具支持。运行时不需要工具包，因此依赖项标记为 PrivateAssets="All"。

通过包管理器控制台 (PMC) 或管理 NuGet 包来安装包。

用于安装包的 PMC 选项

从 Visual Studio 中，依次选择“工具”>“NuGet 包管理器”>“包管理器控制台”
从“包管理器控制台”窗口中，运行 cd GrpcGreeterClient 以将目录更改为包含 GrpcGreeterClient.csproj 文件的文件夹。

运行以下命令：

Install-Package Grpc.Net.Client
Install-Package Google.Protobuf
Install-Package Grpc.Tools

管理 NuGet 包选项以安装包

右键单击“解决方案资源管理器”>“管理 NuGet 包”中的项目。
选择“浏览”选项卡。
在搜索框中输入 Grpc.Net.Client。
从“浏览”选项卡中选择“Grpc.Net.Client”包，然后选择“安装” 。
为 Google.Protobuf 和 Grpc.Tools 重复这些步骤。

从“集成终端”运行以下命令：

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package Grpc.Tools

添加 greet.proto

在 gRPC 客户端项目中创建 Protos 文件夹。
从 gRPC Greeter 服务将 Protos\greet.proto 文件复制到 gRPC 客户端项目中的 Protos 文件夹。
将 greet.proto 文件中的命名空间更新为项目的命名空间：
```
option csharp_namespace = "GrpcGreeterClient";
```
编辑 GrpcGreeterClient.csproj 项目文件：
右键单击项目，并选择“编辑项目文件”。

选择 GrpcGreeterClient.csproj 文件。

右键单击项目，并选择“编辑项目文件”。

添加具有引用 greet.proto 文件的 <Protobuf> 元素的项组：

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

创建 Greeter 客户端

构建客户端项目，以在 GrpcGreeterClient 命名空间中创建类型。

注意

GrpcGreeterClient 类型是由生成进程自动生成的。工具包 Grpc.Tools 基于 greet.proto 文件生成以下文件：

GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\Greet.cs：用于填充、序列化和检索请求和响应消息类型的协议缓冲区代码。
GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\GreetGrpc.cs：包含生成的客户端类。

有关 Grpc.Tools 自动生成的 C# 资产的详细信息，请参阅使用 C# 的 gRPC 服务：生成的 C# 资产。

使用以下代码更新 gRPC 客户端 Program.cs 文件：

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 包含 gRPC 客户端的入口点和逻辑。

通过以下方式创建 Greeter 客户端：

实例化 GrpcChannel，使其包含用于创建到 gRPC 服务的连接的信息。
使用 GrpcChannel 构造 Greeter 客户端：

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();
}

Greeter 客户端会调用异步 SayHello 方法。随即显示 SayHello 调用的结果：

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();
}

使用 gRPC Greeter 服务测试 gRPC 客户端

在 Greeter 服务中，按 Ctrl+F5 在不使用调试程序的情况下启动服务器。
在 GrpcGreeterClient 项目中，按 Ctrl+F5 在不使用调试程序的情况下启动客户端。

根据前面的 macOS 上 HTTP/2 TLS 问题的解决方法所述，需要将客户端中的通道地址更新为“http://localhost:5000"”。更新 GrpcGreeterClient/Program.cs 的第 13 行以读取：
```
using var channel = GrpcChannel.ForAddress("http://localhost:5000");
```
启动 Greeter 服务。
启动客户端。

Greeting: Hello GreeterClient
Press any key to exit...

gRPC 服务在写入命令提示符的日志中记录成功调用的详细信息：

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

注意

教程：在 ASP.NET Core 中创建 gRPC 客户端和服务器

先决条件

创建 gRPC 服务

运行服务

检查项目文件

在 .NET 控制台应用中创建 gRPC 客户端

添加所需的 NuGet 包

用于安装包的 PMC 选项

管理 NuGet 包选项以安装包

添加 greet.proto

创建 Greeter 客户端

使用 gRPC Greeter 服务测试 gRPC 客户端

后续步骤

先决条件

创建 gRPC 服务

运行服务

检查项目文件

在 .NET 控制台应用中创建 gRPC 客户端

添加所需的 NuGet 包

用于安装包的 PMC 选项

管理 NuGet 包选项以安装包

添加 greet.proto

创建 Greeter 客户端

使用 gRPC Greeter 服务测试 gRPC 客户端

后续步骤

先决条件

创建 gRPC 服务

运行服务

检查项目文件

在 .NET 控制台应用中创建 gRPC 客户端

添加所需的 NuGet 包

用于安装包的 PMC 选项

管理 NuGet 包选项以安装包

添加 greet.proto

创建 Greeter 客户端

使用 gRPC Greeter 服务测试 gRPC 客户端

后续步骤

先决条件

创建 gRPC 服务

运行服务

检查项目文件

在 .NET 控制台应用中创建 gRPC 客户端

添加所需的包

用于安装包的 PMC 选项

管理 NuGet 包选项以安装包

添加 greet.proto

创建 Greeter 客户端

使用 gRPC Greeter 服务测试 gRPC 客户端

后续步骤

先决条件

创建 gRPC 服务

运行服务

检查项目文件

在 .NET 控制台应用中创建 gRPC 客户端

添加所需的包

用于安装包的 PMC 选项

管理 NuGet 包选项以安装包

添加 greet.proto

创建 Greeter 客户端

使用 gRPC Greeter 服务测试 gRPC 客户端

后续步骤

反馈

其他资源