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

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

在本教學課程中,您:

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

必要條件

建立 gRPC 服務

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

執行服務

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

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

    This project is configured to use SSL. To avoid SSL warnings in the browser you can choose to trust the self-signed certificate that IIS Express has generated. Would you like to trust the IIS Express SSL certificate?

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

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

    Security warning dialog

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

    如需信任 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

注意

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

macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 您需要額外的組態才能在 macOS 上成功執行 gRPC 服務。 如需詳細資訊,請參閱無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

檢查專案檔

GrpcGreeter 專案檔:

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

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

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

新增必要的 NuGet 封裝

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

  • 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.ProtobufGrpc.Tools 重複進行。

新增 greet.proto

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

  • Protos\greet.proto 檔案從 gRPC Greeter 服務複製到 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();
    
  • 在上述醒目提示的程式碼中,以服務專案中指定的 Properties/launchSettings.jsonGrpcGreeter 埠號碼取代 localhost 埠號碼 7042HTTPS

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"

注意

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

警告

ASP.NET Core gRPC 具有搭配 Azure App Service 或 IIS 使用的額外需求。 如需可使用 gRPC 的詳細資訊,請參閱 .NET 支援平臺上的 gRPC

後續步驟

本教學課程示範如何建立 .NET Core gRPC 用戶端,以及 ASP.NET Core gRPC 伺服器。

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

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

在本教學課程中,您:

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

必要條件

建立 gRPC 服務

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

執行服務

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

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

    This project is configured to use SSL. To avoid SSL warnings in the browser you can choose to trust the self-signed certificate that IIS Express has generated. Would you like to trust the IIS Express SSL certificate?

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

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

    Security warning dialog

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

    如需信任 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

注意

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

macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 您需要額外的組態才能在 macOS 上成功執行 gRPC 服務。 如需詳細資訊,請參閱無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

檢查專案檔

GrpcGreeter 專案檔:

  • greet.protoProtos/greet.proto 檔案會 Greeter 定義 gRPC,並用來產生 gRPC 伺服器資產。 如需詳細資訊,請參閱 gRPC 簡介
  • 服務 資料夾:包含服務的實作 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 訊息 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.ProtobufGrpc.Tools 重複進行。

新增 greet.proto

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

  • Protos\greet.proto 檔案從 gRPC Greeter 服務複製到 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;
    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

注意

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

警告

ASP.NET Core gRPC 具有搭配 Azure App Service 或 IIS 使用的額外需求。 如需可以使用 gRPC 之位置的詳細資訊,請參閱 .NET 支援平臺上的 gRPC

後續步驟

本教學課程示範如何建立 .NET Core gRPC 用戶端,以及 ASP.NET Core gRPC 伺服器。

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

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

在本教學課程中,您:

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

必要條件

建立 gRPC 服務

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

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

    Create a new project dialog in Visual Studio

  • 將專案命名為 GrpcGreeter。 請務必命名專案 GrpcGreeter ,以便在複製並貼上程式碼時,命名空間相符。

  • 選取 [建立] 。

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

    • 已選取 [gRPC 服務] 範本。
    • 選取 [建立] 。

執行服務

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

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

    This project is configured to use SSL. To avoid SSL warnings in the browser you can choose to trust the self-signed certificate that IIS Express has generated. Would you like to trust the IIS Express SSL certificate?

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

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

    Security warning dialog

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

    如需信任 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

注意

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

macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 您需要額外的組態才能在 macOS 上成功執行 gRPC 服務。 如需詳細資訊,請參閱無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

檢查專案檔

GrpcGreeter 專案檔:

  • greet.protoProtos/greet.proto 檔案會 Greeter 定義 gRPC,並用來產生 gRPC 伺服器資產。 如需詳細資訊,請參閱 gRPC 簡介
  • 服務 資料夾:包含服務的實作 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 訊息 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.ProtobufGrpc.Tools 重複進行。

新增 greet.proto

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

  • Protos\greet.proto 檔案從 gRPC Greeter 服務複製到 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;
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

注意

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

警告

ASP.NET Core gRPC 具有搭配 Azure App Service 或 IIS 使用的額外需求。 如需可使用 gRPC 的詳細資訊,請參閱 .NET 支援平臺上的 gRPC

後續步驟