共用方式為

教學課程：在 ASP.NET Core 中建立 gRPC 用戶端與伺服器

本教學課程示範如何建立 .NET gRPC 用戶端和 ASP.NET Core gRPC Server。 在結束時，您將擁有可與 gRPC Greeter 服務通訊的 gRPC 用戶端。

在本教學課程中，您已：

  • 建立 gRPC 伺服器。
  • 建立 gRPC 用戶端。
  • 使用 gRPC Greeter 服務測試 gRPC 用戶端。

Prerequisites

建立 gRPC 服務

  • 啟動 Visual Studio 2022，然後選取 [ 新增專案]。
  • 在 [建立新專案] 對話方塊中，搜尋 gRPC。 選取 [ASP.NET Core gRPC 服務]，然後選取 [下一步]。
  • 在 [設定新專案] 對話方塊中，輸入 GrpcGreeter 作為 [專案名稱]。 請務必將專案命名為 GrpcGreeter ，以便在複製和貼上程式代碼時符合命名空間。
  • 選取 下一步。
  • 在 [其他資訊] 對話框中，選取 [.NET 9.0 （標準服務支援）]，然後選取 [建立]。

執行服務

  • 按 Ctrl+F5 即可執行而不使用偵錯工具。

    當專案尚未設定為使用 SSL 時，Visual Studio 會顯示下列對話方塊：

    此專案設定為使用 SSL。為避免瀏覽器中的 SSL 警告，您可以選擇信任 IIS Express 產生的自我簽署憑證。您要信任 IIS Express SSL 憑證嗎？

    如果您信任 IIS Express SSL 憑證，請選取 [是]。

    此時會顯示下列對話方塊：

    安全性警告對話方塊

    若您同意信任開發憑證，請選取 [是]。

    如需關於信任 Firefox 瀏覽器的資訊，請參閱 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 憑證錯誤。

    Visual Studio：

    • 啟動 Kestrel 伺服器。
    • 啟動瀏覽器。
    • 瀏覽至 http://localhost:port，例如 http://localhost:7042。
      • 埠：應用程式隨機指派的埠號碼。
      • localhost：本機電腦的標準主機名稱。 Localhost 只會為來自本機電腦的 Web 要求提供服務。

記錄會顯示在 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

Note

gRPC 範本已設為使用傳輸層安全性 (TLS)。 gRPC 用戶端需要使用 HTTPS 來呼叫伺服器。 gRPC 服務 localhost 埠號碼會在專案建立時隨機指派，並在 gRPC 服務項目的檔案的 [屬性]\launchSettings.js 中設定。

檢查專案檔

GrpcGreeter 項目檔：

  • Protos/greet.proto：會定義 Greeter gRPC，並會用來產生 gRPC 伺服器資產。 如需詳細資訊，請參閱 gRPC 簡介。
  • Services 資料夾：包含 Greeter 服務的實作。
  • appSettings.json：包含組態資料，例如 Kestrel 所使用的通訊協定。 如需詳細資訊，請參閱 ASP.NET Core 中的組態。
  • Program.cs，其中包含：

在 .NET 主控台應用程式中建立 gRPC 用戶端

  • 開啟 Visual Studio 的第二個實例，然後選取 [ 新增專案]。
  • 在 [建立新專案] 對話方塊中，選取 [主控台應用程式] 並選取 [下一步]。
  • 在 [ 項目名稱] 文本框中，輸入 GrpcGreeterClient ，然後選取 [ 下一步]。
  • 在 [其他資訊] 對話框中，選取 [.NET 9.0 （標準服務支援）]，然後選取 [建立]。

新增必要的 NuGet 封裝

gRPC 用戶端專案需要下列 NuGet 套件：

  • Grpc.Net.Client，其中包含 .NET 用戶端。
  • Google.Protobuf，其中包含 C# 的 protobuf 訊息 API。
  • Grpc.Tools，其中包含對 C# 的工具支援，以支援 protobuf 檔案。 執行階段不需要工具套件，因此相依性會標示為 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。

新增 greet.proto

  • 在 gRPC 用戶端專案中建立 Protos 資料夾。

  • 將 Protos\greet.proto 檔案從 gRPC Greeter 服務複製到 gRPC 客戶端專案中的 Protos 資料夾。

  • 將 greet.proto 檔案內的命名空間更新為專案的命名空間：

    option csharp_namespace = "GrpcGreeterClient";

  • 編輯 GrpcGreeterClient.csproj 專案檔：

以滑鼠右鍵按一下專案，然後選取 [編輯專案檔]。

  • 新增一個包含 <Protobuf> 元素，並且參考 greet.proto 檔案的項目群組：

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

建立 Greeter 用戶端

  • 建置用戶端專案，以便在 GrpcGreeterClient 命名空間中建立類型。

Note

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 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 取代為 HTTPS 服務專案內的 Properties/launchSettings.json 中指定的 GrpcGreeter 連接埠號碼。

Program.cs 包含 gRPC 用戶端的進入點和邏輯。

Greeter 用戶端建立者：

  • 具現化包含建立與 gRPC 服務連線資訊的 GrpcChannel。
  • 使用 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"
    }
  }
}
  • 在 GrpcGreeter 服務專案中，按 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 HTTP/2 POST https://localhost:7042/greet.Greeter/SayHello - 200 - application/grpc 40.4615ms

Note

此文章中的程式碼需要 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 gRPC 用戶端和 ASP.NET Core gRPC Server。 在結束時，您將擁有可與 gRPC Greeter 服務通訊的 gRPC 用戶端。

在本教學課程中，您已：

  • 建立 gRPC 伺服器。
  • 建立 gRPC 用戶端。
  • 使用 gRPC Greeter 服務測試 gRPC 用戶端。

Prerequisites

建立 gRPC 服務

  • 啟動 Visual Studio 2022，然後選取 [ 新增專案]。
  • 在 [建立新專案] 對話方塊中，搜尋 gRPC。 選取 [ASP.NET Core gRPC 服務]，然後選取 [下一步]。
  • 在 [設定新專案] 對話方塊中，輸入 GrpcGreeter 作為 [專案名稱]。 請務必將專案命名為 GrpcGreeter ，以便在複製和貼上程式代碼時符合命名空間。
  • 選取 下一步。
  • 在 [ 其他資訊] 對話框中，選取 [.NET 8.0（長期支援]， 然後選取 [ 建立]。

執行服務

  • 按 Ctrl+F5 即可執行而不使用偵錯工具。

    當專案尚未設定為使用 SSL 時，Visual Studio 會顯示下列對話方塊：

    此專案設定為使用 SSL。為避免瀏覽器中的 SSL 警告，您可以選擇信任 IIS Express 產生的自我簽署憑證。您要信任 IIS Express SSL 憑證嗎？

    如果您信任 IIS Express SSL 憑證，請選取 [是]。

    此時會顯示下列對話方塊：

    安全性警告對話方塊

    若您同意信任開發憑證，請選取 [是]。

    如需關於信任 Firefox 瀏覽器的資訊，請參閱 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 憑證錯誤。

    Visual Studio：

    • 啟動 Kestrel 伺服器。
    • 啟動瀏覽器。
    • 瀏覽至 http://localhost:port，例如 http://localhost:7042。
      • 埠：應用程式隨機指派的埠號碼。
      • localhost：本機電腦的標準主機名稱。 Localhost 只會為來自本機電腦的 Web 要求提供服務。

記錄會顯示在 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

Note

gRPC 範本已設為使用傳輸層安全性 (TLS)。 gRPC 用戶端需要使用 HTTPS 來呼叫伺服器。 gRPC 服務 localhost 埠號碼會在專案建立時隨機指派，並在 gRPC 服務項目的檔案的 [屬性]\launchSettings.js 中設定。

檢查專案檔

GrpcGreeter 項目檔：

  • Protos/greet.proto：會定義 Greeter gRPC，並會用來產生 gRPC 伺服器資產。 如需詳細資訊，請參閱 gRPC 簡介。
  • Services 資料夾：包含 Greeter 服務的實作。
  • appSettings.json：包含組態資料，例如 Kestrel 所使用的通訊協定。 如需詳細資訊，請參閱 ASP.NET Core 中的組態。
  • Program.cs，其中包含：

在 .NET 主控台應用程式中建立 gRPC 用戶端

  • 開啟 Visual Studio 的第二個實例，然後選取 [ 新增專案]。
  • 在 [建立新專案] 對話方塊中，選取 [主控台應用程式] 並選取 [下一步]。
  • 在 [ 項目名稱] 文本框中，輸入 GrpcGreeterClient ，然後選取 [ 下一步]。
  • 在 [ 其他資訊] 對話框中，選取 [.NET 8.0（長期支援]， 然後選取 [ 建立]。

新增必要的 NuGet 封裝

gRPC 用戶端專案需要下列 NuGet 套件：

  • Grpc.Net.Client，其中包含 .NET 用戶端。
  • Google.Protobuf，其中包含 C# 的 protobuf 訊息 API。
  • Grpc.Tools，其中包含對 C# 的工具支援，以支援 protobuf 檔案。 執行階段不需要工具套件，因此相依性會標示為 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。

新增 greet.proto

  • 在 gRPC 用戶端專案中建立 Protos 資料夾。

  • 將 Protos\greet.proto 檔案從 gRPC Greeter 服務複製到 gRPC 客戶端專案中的 Protos 資料夾。

  • 將 greet.proto 檔案內的命名空間更新為專案的命名空間：

    option csharp_namespace = "GrpcGreeterClient";

  • 編輯 GrpcGreeterClient.csproj 專案檔：

以滑鼠右鍵按一下專案，然後選取 [編輯專案檔]。

  • 新增一個包含 <Protobuf> 元素，並且參考 greet.proto 檔案的項目群組：

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

建立 Greeter 用戶端

  • 建置用戶端專案，以便在 GrpcGreeterClient 命名空間中建立類型。

Note

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 取代為 HTTPS 服務專案內的 Properties/launchSettings.json 中指定的 GrpcGreeter 連接埠號碼。

Program.cs 包含 gRPC 用戶端的進入點和邏輯。

Greeter 用戶端建立者：

  • 具現化包含建立與 gRPC 服務連線資訊的 GrpcChannel。
  • 使用 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

Note

此文章中的程式碼需要 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 gRPC 用戶端和 ASP.NET Core gRPC Server。 在結束時，您將擁有可與 gRPC Greeter 服務通訊的 gRPC 用戶端。

在本教學課程中，您已：

  • 建立 gRPC 伺服器。
  • 建立 gRPC 用戶端。
  • 使用 gRPC Greeter 服務測試 gRPC 用戶端。

Prerequisites

建立 gRPC 服務

  • 啟動 Visual Studio 2022 並選取 [建立新專案]。
  • 在 [建立新專案] 對話方塊中，搜尋 gRPC。 選取 [ASP.NET Core gRPC 服務]，然後選取 [下一步]。
  • 在 [設定新專案] 對話方塊中，輸入 GrpcGreeter 作為 [專案名稱]。 請務必將專案命名為 GrpcGreeter ，以便在複製和貼上程式代碼時符合命名空間。
  • 選取 下一步。
  • 在 [ 其他資訊] 對話框中，選取 [.NET 6.0（長期支援）， 然後選取 [建立]。

執行服務

  • 按 Ctrl+F5 即可執行而不使用偵錯工具。

    當專案尚未設定為使用 SSL 時，Visual Studio 會顯示下列對話方塊：

    此專案設定為使用 SSL。為避免瀏覽器中的 SSL 警告，您可以選擇信任 IIS Express 產生的自我簽署憑證。您要信任 IIS Express SSL 憑證嗎？

    如果您信任 IIS Express SSL 憑證，請選取 [是]。

    此時會顯示下列對話方塊：

    安全性警告對話方塊

    若您同意信任開發憑證，請選取 [是]。

    如需關於信任 Firefox 瀏覽器的資訊，請參閱 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 憑證錯誤。

    Visual Studio：

    • 啟動 Kestrel 伺服器。
    • 啟動瀏覽器。
    • 瀏覽至 http://localhost:port，例如 http://localhost:7042。
      • 埠：應用程式隨機指派的埠號碼。
      • localhost：本機電腦的標準主機名稱。 Localhost 只會為來自本機電腦的 Web 要求提供服務。

記錄會顯示在 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

Note

gRPC 範本已設為使用傳輸層安全性 (TLS)。 gRPC 用戶端需要使用 HTTPS 來呼叫伺服器。 gRPC 服務 localhost 埠號碼會在專案建立時隨機指派，並在 gRPC 服務項目的檔案的 [屬性]\launchSettings.js 中設定。

macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 您需要額外的組態才能在 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，其中包含：

在 .NET 主控台應用程式中建立 gRPC 用戶端

  • 開啟第二個 Visual Studio 執行個體，並選取 [建立新專案]。
  • 在 [建立新專案] 對話方塊中，選取 [主控台應用程式]，並選取 [下一步]。
  • 在 [ 項目名稱] 文本框中，輸入 GrpcGreeterClient ，然後選取 [ 下一步]。
  • 在 [ 其他資訊] 對話框中，選取 [.NET 6.0（長期支援）， 然後選取 [建立]。

新增必要的 NuGet 封裝

gRPC 用戶端專案需要下列 NuGet 套件：

  • Grpc.Net.Client，其中包含 .NET 用戶端。
  • Google.Protobuf，其中包含 C# 的 protobuf 訊息 API。
  • Grpc.Tools，其中包含對 C# 的工具支援，以支援 protobuf 檔案。 執行階段不需要工具套件，因此相依性會標示為 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。

新增 greet.proto

  • 在 gRPC 用戶端專案中建立 Protos 資料夾。

  • 將 Protos\greet.proto 檔案從 gRPC Greeter 服務複製到 gRPC 客戶端專案中的 Protos 資料夾。

  • 將 greet.proto 檔案內的命名空間更新為專案的命名空間：

    option csharp_namespace = "GrpcGreeterClient";

  • 編輯 GrpcGreeterClient.csproj 專案檔：

以滑鼠右鍵按一下專案，然後選取 [編輯專案檔]。

  • 新增一個包含 <Protobuf> 元素，並且參考 greet.proto 檔案的項目群組：

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

建立 Greeter 用戶端

  • 建置用戶端專案，以便在 GrpcGreeterClient 命名空間中建立類型。

Note

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 取代為 HTTPS 服務專案內的 Properties/launchSettings.json 中指定的 GrpcGreeter 連接埠號碼。

Program.cs 包含 gRPC 用戶端的進入點和邏輯。

Greeter 用戶端建立者：

  • 具現化包含建立與 gRPC 服務連線資訊的 GrpcChannel。
  • 使用 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

Note

此文章中的程式碼需要 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 gRPC 用戶端和 ASP.NET Core gRPC Server。 在結束時，您將擁有可與 gRPC Greeter 服務通訊的 gRPC 用戶端。

在本教學課程中，您已：

  • 建立 gRPC 伺服器。
  • 建立 gRPC 用戶端。
  • 使用 gRPC Greeter 服務測試 gRPC 用戶端。

Prerequisites

建立 gRPC 服務

  • 啟動 Visual Studio 2022 並選取 [建立新專案]。
  • 在 [建立新專案] 對話方塊中，搜尋 gRPC。 選取 [ASP.NET Core gRPC 服務]，然後選取 [下一步]。
  • 在 [設定新專案] 對話方塊中，輸入 GrpcGreeter 作為 [專案名稱]。 請務必將專案命名為 GrpcGreeter ，以便在複製和貼上程式代碼時符合命名空間。
  • 選取 下一步。
  • 在 [ 其他資訊] 對話框中，選取 [.NET 6.0（長期支援）， 然後選取 [建立]。

執行服務

  • 按 Ctrl+F5 即可執行而不使用偵錯工具。

    當專案尚未設定為使用 SSL 時，Visual Studio 會顯示下列對話方塊：

    此專案設定為使用 SSL。為避免瀏覽器中的 SSL 警告，您可以選擇信任 IIS Express 產生的自我簽署憑證。您要信任 IIS Express SSL 憑證嗎？

    如果您信任 IIS Express SSL 憑證，請選取 [是]。

    此時會顯示下列對話方塊：

    安全性警告對話方塊

    若您同意信任開發憑證，請選取 [是]。

    如需關於信任 Firefox 瀏覽器的資訊，請參閱 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 憑證錯誤。

    Visual Studio：

    • 啟動 Kestrel 伺服器。
    • 啟動瀏覽器。
    • 瀏覽至 http://localhost:port，例如 http://localhost:7042。
      • 埠：應用程式隨機指派的埠號碼。
      • localhost：本機電腦的標準主機名稱。 Localhost 只會為來自本機電腦的 Web 要求提供服務。

記錄會顯示在 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

Note

gRPC 範本已設為使用傳輸層安全性 (TLS)。 gRPC 用戶端需要使用 HTTPS 來呼叫伺服器。 gRPC 服務 localhost 埠號碼會在專案建立時隨機指派，並在 gRPC 服務項目的檔案的 [屬性]\launchSettings.js 中設定。

macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 您需要額外的組態才能在 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，其中包含：

在 .NET 主控台應用程式中建立 gRPC 用戶端

  • 開啟第二個 Visual Studio 執行個體，並選取 [建立新專案]。
  • 在 [建立新專案] 對話方塊中，選取 [主控台應用程式]，並選取 [下一步]。
  • 在 [ 項目名稱] 文本框中，輸入 GrpcGreeterClient ，然後選取 [ 下一步]。
  • 在 [ 其他資訊] 對話框中，選取 [.NET 6.0（長期支援）， 然後選取 [建立]。

新增必要的 NuGet 封裝

gRPC 用戶端專案需要下列 NuGet 套件：

  • Grpc.Net.Client，其中包含 .NET 用戶端。
  • Google.Protobuf，其中包含 C# 的 protobuf 訊息 API。
  • Grpc.Tools，其中包含對 C# 的工具支援，以支援 protobuf 檔案。 執行階段不需要工具套件，因此相依性會標示為 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。

新增 greet.proto

  • 在 gRPC 用戶端專案中建立 Protos 資料夾。

  • 將 Protos\greet.proto 檔案從 gRPC Greeter 服務複製到 gRPC 客戶端專案中的 Protos 資料夾。

  • 將 greet.proto 檔案內的命名空間更新為專案的命名空間：

    option csharp_namespace = "GrpcGreeterClient";

  • 編輯 GrpcGreeterClient.csproj 專案檔：

以滑鼠右鍵按一下專案，然後選取 [編輯專案檔]。

  • 新增一個包含 <Protobuf> 元素，並且參考 greet.proto 檔案的項目群組：

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

建立 Greeter 用戶端

  • 建置用戶端專案，以便在 GrpcGreeterClient 命名空間中建立類型。

Note

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 取代為 HTTPS 服務專案內的 Properties/launchSettings.json 中指定的 GrpcGreeter 連接埠號碼。

Program.cs 包含 gRPC 用戶端的進入點和邏輯。

Greeter 用戶端建立者：

  • 具現化包含建立與 gRPC 服務連線資訊的 GrpcChannel。
  • 使用 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，在不啟動偵錯工具的情況下啟動用戶端。

用戶端會傳送問候語給服務，其中包含其名稱 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

新增下列幾行來更新 appsettings.Development.json 檔案：

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

Note

此文章中的程式碼需要 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 gRPC 用戶端和 ASP.NET Core gRPC Server。

在結束時，您將擁有可與 gRPC Greeter 服務通訊的 gRPC 用戶端。

檢視或下載範例程式碼 (如何下載)。

在本教學課程中，您已：

  • 建立 gRPC 伺服器。
  • 建立 gRPC 用戶端。
  • 使用 gRPC Greeter 服務測試 gRPC 用戶端。

Prerequisites

建立 gRPC 服務

  • 啟動 Visual Studio 並選取 [建立新專案]。
  • 在 [建立新專案] 對話方塊中，選取 [gRPC 服務]，然後選取 [下一步]。
  • 在 [設定新專案] 對話方塊中，輸入 GrpcGreeter 作為 [專案名稱]。 請務必將專案命名為 GrpcGreeter ，以便在複製和貼上程式代碼時符合命名空間。
  • 選取 下一步。
  • 在 [其他資訊] 對話框中，在 [目標 Framework] 下拉式清單中選取 [.NET 5.0]。
  • 選取 ，創建。

執行服務

  • 按 Ctrl+F5 即可執行而不使用偵錯工具。

    當專案尚未設定為使用 SSL 時，Visual Studio 會顯示下列對話方塊：

    此專案設定為使用 SSL。為避免瀏覽器中的 SSL 警告，您可以選擇信任 IIS Express 產生的自我簽署憑證。您要信任 IIS Express SSL 憑證嗎？

    如果您信任 IIS Express SSL 憑證，請選取 [是]。

    此時會顯示下列對話方塊：

    安全性警告對話方塊

    若您同意信任開發憑證，請選取 [是]。

    如需關於信任 Firefox 瀏覽器的資訊，請參閱 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 憑證錯誤。

    Visual Studio 會啟動 IIS Express 並執行應用程式。 位址列會顯示 localhost:port#，而不是類似於 example.com 的內容。 這是因為 localhost 是本機電腦的標準主機名稱。 Localhost 只會為來自本機電腦的 Web 要求提供服務。 當 Visual Studio 建立 Web 專案時，會為網頁伺服器使用隨機連接埠。

該記錄會顯示正在接聽 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

gRPC 範本已設為使用傳輸層安全性 (TLS)。 gRPC 用戶端需要使用 HTTPS 來呼叫伺服器。

macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 您需要額外的組態才能在 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 中的 .NET 泛型主機。
  • Startup.cs：包含設定應用程式行為的程式碼。 如需詳細資訊，請參閱 應用程式啟動。

在 .NET 主控台應用程式中建立 gRPC 用戶端

  • 開啟第二個 Visual Studio 執行個體，並選取 [建立新專案]。
  • 在 [ 建立新專案] 對話框中，選取 [ 控制台應用程式][.NET]， 然後選取 [ 下一步]。
  • 在 [ 項目名稱] 文本框中，輸入 GrpcGreeterClient ，然後選取 [ 建立]。

新增必要套件

gRPC 用戶端專案需要下列套件：

  • Grpc.Net.Client，其中包含 .NET 用戶端。
  • Google.Protobuf，其中包含 C# 的 protobuf 訊息 API。
  • 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。

新增 greet.proto

  • 在 gRPC 用戶端專案中建立 Protos 資料夾。

  • 將 Protos\greet.proto 檔案從 gRPC Greeter 服務複製到 gRPC 客戶端專案中的 Protos 資料夾。

  • 將 greet.proto 檔案內的命名空間更新為專案的命名空間：

    option csharp_namespace = "GrpcGreeterClient";

  • 編輯 GrpcGreeterClient.csproj 專案檔：

    以滑鼠右鍵按一下專案，然後選取 [編輯專案檔]。

  • 新增一個包含 <Protobuf> 元素，並且參考 greet.proto 檔案的項目群組：

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

建立 Greeter 用戶端

  • 建置用戶端專案，以便在 GrpcGreeterClient 命名空間中建立類型。

Note

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 用戶端建立者：

  • 具現化包含建立與 gRPC 服務連線資訊的 GrpcChannel。
  • 使用 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，在不啟動偵錯工具的情況下啟動用戶端。

用戶端會傳送問候語給服務，其中包含其名稱 GreeterClient 的訊息。 該服務會傳送 "Hello GreeterClient" 訊息做為回應。 "Hello GreeterClient" 回應會顯示在命令提示字元中：

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

Note

此文章中的程式碼需要 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 用戶端。

Prerequisites

建立 gRPC 服務

  • 啟動 Visual Studio 並選取 [建立新專案]。 或者，從Visual Studio [檔案 ] 功能表中，選取 [ 新增>專案]。

  • 在 [建立新專案] 對話方塊中，選取 [gRPC 服務]，然後選取 [下一步]：

    Visual Studio 中的 [建立新專案] 對話方塊

  • 將專案命名為 GrpcGreeter。 請務必將專案命名為 GrpcGreeter ，以便在複製和貼上程式代碼時符合命名空間。

  • 選取 ，創建。

  • 在 [建立新的 gRPC 服務] 對話方塊中：

    • 選取 gRPC 服務 範本。
    • 選取 ，創建。

執行服務

  • 按 Ctrl+F5 即可執行而不使用偵錯工具。

    當專案尚未設定為使用 SSL 時，Visual Studio 會顯示下列對話方塊：

    此專案設定為使用 SSL。為避免瀏覽器中的 SSL 警告，您可以選擇信任 IIS Express 產生的自我簽署憑證。您要信任 IIS Express SSL 憑證嗎？

    如果您信任 IIS Express SSL 憑證，請選取 [是]。

    此時會顯示下列對話方塊：

    安全性警告對話方塊

    若您同意信任開發憑證，請選取 [是]。

    如需關於信任 Firefox 瀏覽器的資訊，請參閱 Firefox SEC_ERROR_INADEQUATE_KEY_USAGE 憑證錯誤。

    Visual Studio 會啟動 IIS Express 並執行應用程式。 位址列會顯示 localhost:port#，而不是類似於 example.com 的內容。 這是因為 localhost 是本機電腦的標準主機名稱。 Localhost 只會為來自本機電腦的 Web 要求提供服務。 當 Visual Studio 建立 Web 專案時，會為網頁伺服器使用隨機連接埠。

該記錄會顯示正在接聽 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

gRPC 範本已設為使用傳輸層安全性 (TLS)。 gRPC 用戶端需要使用 HTTPS 來呼叫伺服器。

macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 您需要額外的組態才能在 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 中的 .NET 泛型主機。
  • Startup.cs：包含設定應用程式行為的程式碼。 如需詳細資訊，請參閱 應用程式啟動。

在 .NET 主控台應用程式中建立 gRPC 用戶端

  • 開啟第二個 Visual Studio 執行個體，並選取 [建立新專案]。
  • 在 [建立新專案] 對話方塊中，選取 [主控台應用程式 (.NET Core)] 並選取 [下一步]。
  • 在 [ 項目名稱] 文本框中，輸入 GrpcGreeterClient ，然後選取 [ 建立]。

新增必要套件

gRPC 用戶端專案需要下列套件：

  • Grpc.Net.Client，其中包含 .NET Core 用戶端。
  • Google.Protobuf，其中包含 C# 的 protobuf 訊息 API。
  • 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。

新增 greet.proto

  • 在 gRPC 用戶端專案中建立 Protos 資料夾。

  • 將 Protos\greet.proto 檔案從 gRPC Greeter 服務複製到 gRPC 客戶端專案中的 Protos 資料夾。

  • 將 greet.proto 檔案內的命名空間更新為專案的命名空間：

    option csharp_namespace = "GrpcGreeterClient";

  • 編輯 GrpcGreeterClient.csproj 專案檔：

    以滑鼠右鍵按一下專案，然後選取 [編輯專案檔]。

  • 新增一個包含 <Protobuf> 元素，並且參考 greet.proto 檔案的項目群組：

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

建立 Greeter 用戶端

  • 建置用戶端專案，以便在 GrpcGreeterClient 命名空間中建立類型。

Note

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 用戶端建立者：

  • 具現化包含建立與 gRPC 服務連線資訊的 GrpcChannel。
  • 使用 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，在不啟動偵錯工具的情況下啟動用戶端。

用戶端會傳送問候語給服務，其中包含其名稱 GreeterClient 的訊息。 該服務會傳送 "Hello GreeterClient" 訊息做為回應。 "Hello GreeterClient" 回應會顯示在命令提示字元中：

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

Note

此文章中的程式碼需要 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 服務。

後續步驟

  • Last updated on