教學課程:在 ASP.NET Core 中建立 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 (長期支援) ],然後選取 [ 建立]。
執行服務
按 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://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
,其中包含:- gRPC 服務的進入點。 如需詳細資訊,請參閱 ASP.NET Core 中的 .NET 泛型主機。
- 設定應用程式行為的程式碼。 如需詳細資訊,請參閱應用程式啟動。
在 .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.Protobuf
與Grpc.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.json
GrpcGreeter
埠號碼取代 localhost 埠號碼7042
HTTPS
。
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 用戶端。
必要條件
- 包含 ASP.NET 和 Web 開發工作負載的 Visual Studio 2019 16.8 版或更新版本
- .NET 5.0 SDK
建立 gRPC 服務
- 啟動 Visual Studio,然後選取 [建立新專案]。
- 在 [ 建立新專案 ] 對話方塊中,選取 gRPC 服務 ,然後選取 [ 下一步]。
- 在 [ 設定新專案] 對話方塊中,輸入
GrpcGreeter
[專案名稱]。 請務必將專案命名為 GrpcGreeter ,以便在複製和貼上程式碼時符合命名空間。 - 選取 [下一步] 。
- 在 [其他資訊]對話方塊中,選取[目標 Framework] 下拉式清單中的[.NET 5.0]。
- 選取 [建立] 。
執行服務
按 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 專案時,會為網頁伺服器使用隨機連接埠。
該記錄會顯示正在接聽 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.proto: Protos/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.Protobuf
與Grpc.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 用戶端。
必要條件
Visual Studio 2019 16.4 或更新版本 搭配 ASP.NET 和 Web 開發 工作負載
建立 gRPC 服務
啟動 Visual Studio,然後選取 [建立新專案]。 或者,從 Visual Studio 的 [檔案] 功能表中,選取 [新增]>[專案]。
在 [ 建立新專案 ] 對話方塊中,選取 [gRPC 服務 ],然後選取 [ 下一步]:
將專案命名為 GrpcGreeter。 請務必命名專案 GrpcGreeter ,以便在複製並貼上程式碼時,命名空間相符。
選取 [建立] 。
在 [建立新的 gRPC 服務] 對話方塊中:
- 已選取 [gRPC 服務] 範本。
- 選取 [建立] 。
執行服務
按 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 專案時,會為網頁伺服器使用隨機連接埠。
該記錄會顯示正在接聽 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.proto: Protos/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.Protobuf
與Grpc.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。