在 ASP.NET Core 中使用 gRPCurl 和 gRPCui 測試 gRPC 服務

作者：James Newton-King

已為 gRPC 備妥工具，可讓開發人員在不建置用戶端應用程式的情況下測試服務：

• gRPCurl 是開放原始碼命令列工具，可提供與 gRPC 服務的互動。
• gRPCui 建置在 gRPCurl 之上，並為 gRPC 新增開放原始碼互動式 Web UI。

本文探討如何：

• 使用 gRPC ASP.NET Core 應用程式設定 gRPC 伺服器反映。
• 使用測試工具與 gRPC 互動：
  • 使用 grpcurl 探索及測試 gRPC 服務。
  • 使用 grpcui 透過瀏覽器與 gRPC 服務互動。

注意

若要了解如何對 gRPC 服務進行單元測試，請參閱在 ASP.NET Core 中測試 gRPC 服務。

設定 gRPC 反映

工具必須知道服務的 Protobuf 合約，才能呼叫這些服務。 作法有二：

• 在伺服器上設定 gRPC 反映。 gRPCurl 之類的工具會使用反映來自動探索服務合約。
• 手動將 .proto 檔案新增至工具。

使用 gRPC 反映更加輕鬆。 gRPC 反映會將新的 gRPC 服務新增至應用程式，而用戶端可以呼叫該應用程式來探索服務。

gRPC ASP.NET Core 具備 Grpc.AspNetCore.Server.Reflection 套件，內建支援 gRPC 反映。 若要在應用程式中設定反映，請執行下列動作：

• 新增 Grpc.AspNetCore.Server.Reflection 套件參考。
• 在 Program.cs 中註冊反映：
  • AddGrpcReflection 代表註冊啟用反映的服務。
  • MapGrpcReflectionService 代表新增反映服務端點。

builder.Services.AddGrpc();
builder.Services.AddGrpcReflection();

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

設定 gRPC 反映時：

• gRPC 反映服務會新增至伺服器應用程式。
• 支援 gRPC 反映的用戶端應用程式可以呼叫反映服務，以探索伺服器所裝載的服務。
• gRPC 服務仍會從用戶端呼叫。 反映只會啟用服務探索，而不會略過伺服器端安全性。 受驗證和授權保護的端點需要呼叫端傳遞認證，才能成功呼叫端點。

反射服務安全性

gRPC 反射會傳回可用的 API 清單，其中包含敏感性資訊。 請務必小心限制 gRPC 反射服務的存取權。

通常只有在本機開發環境中才需要 gRPC 反射。 針對本機開發，只有在 IsDevelopment 傳回 true 時，才會對應反射服務：

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

您可以透過標準 ASP.NET 核心授權延伸模組方法來控制服務的存取，例如 AllowAnonymous 和 RequireAuthorization。

例如，如果應用程式預設已設定為需要授權，請使用 AllowAnonymous 設定 gRPC 反射端點，以略過驗證和授權。

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService().AllowAnonymous();
}

gRPCurl

gRPCurl 是 gRPC 社群所建立的命令列工具。 其中的功能包括：

• 呼叫 gRPC 服務，包括串流服務。
• 使用 gRPC 反映進行服務探索。
• 列出及描述 gRPC 服務。
• 使用安全 (TLS) 和不安全 (純文字) 的伺服器。

如需下載並安裝 grpcurl 的詳細資訊，請參閱 gRPCurl GitHub 首頁。

使用 grpcurl

-help 引數可說明 grpcurl 命令列選項：

$ grpcurl -help

探索服務

使用 describe 動詞可檢視伺服器所定義的服務。 請將 <port> 指定為 gRPC 伺服器的 localhost 連接埠號碼。 連接埠號碼是在 Properties/launchSettings.json 中建立並設定專案時隨機指派：

$ grpcurl localhost:<port> describe
greet.Greeter is a service:
service Greeter {
  rpc SayHello ( .greet.HelloRequest ) returns ( .greet.HelloReply );
  rpc SayHellos ( .greet.HelloRequest ) returns ( stream .greet.HelloReply );
}
grpc.reflection.v1alpha.ServerReflection is a service:
service ServerReflection {
  rpc ServerReflectionInfo ( stream .grpc.reflection.v1alpha.ServerReflectionRequest ) returns ( stream .grpc.reflection.v1alpha.ServerReflectionResponse );
}

上述範例：

• 在伺服器 localhost:<port> 上執行 describe 動詞。 其中 <port> 是在 Properties/launchSettings.json 中建立並設定 gRPC 伺服器專案時隨機指派
• 列印 gRPC 反映所傳回的服務和方法。
  • Greeter 是應用程式所實作的服務。
  • ServerReflection 是 Grpc.AspNetCore.Server.Reflection 套件所新增的服務。

將 describe 與服務、方法或訊息名稱結合以檢視其詳細資料：

$ grpcurl localhost:<port> describe greet.HelloRequest
greet.HelloRequest is a message:
message HelloRequest {
  string name = 1;
}

呼叫 gRPC 服務

指定服務和方法名稱以及代表要求訊息的 JSON 引數，藉以呼叫 gRPC 服務。 JSON 會轉換成 Protobuf 並傳送至服務。

$ grpcurl -d '{ \"name\": \"World\" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

在前述範例中:

• -d 引數指定使用 JSON 的要求訊息。 這個引數必須位在伺服器位址和方法名稱之前。
• 呼叫 greeter.Greeter 服務上的 SayHello 方法。
• 以 JSON 的形式列印回應訊息。
• 其中 <port> 是在 Properties/launchSettings.json 中建立並設定 gRPC 伺服器專案時隨機指派

上述範例會使用 \ 來逸出 " 字元。 逸出 " 在 PowerShell 主控台中是必要動作，但在某些主控台中不得使用。 例如，上一個命令在 macOS 主控台上為：

$ grpcurl -d '{ "name": "World" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

gRPCui

gRPCui 是適用於 gRPC 的互動式 Web UI。 gRPCui 建置在 gRPCurl 之上。 gRPCui 提供用來探索及測試 gRPC 服務的 GUI，類似於 Swagger UI 之類的 HTTP 工具。

如需下載並安裝 grpcui 的詳細資訊，請參閱 gRPCui GitHub 首頁。

使用 grpcui

使用要與之互動的伺服器位址作為引數來執行 grpcui：

$ grpcui localhost:<port>
gRPC Web UI available at http://127.0.0.1:55038/

在上述範例中，將 <port> 指定為 gRPC 伺服器的 localhost 連接埠號碼。 連接埠號碼是在 Properties/launchSettings.json 中建立並設定專案時隨機指派

此工具會啟動包含互動式 Web UI 的瀏覽器視窗。使用 gRPC 反映即可自動探索 gRPC 服務。

其他資源

• gRPCurl GitHub 首頁
• gRPCui GitHub 首頁
• Grpc.AspNetCore.Server.Reflection
• 在 ASP.NET Core 中測試 gRPC 服務
• 在測試中模擬 gRPC 用戶端