使用 .NET 的程式碼優先 gRPC 服務與用戶端

作者：James Newton-King 和 Marc Gravell

程式碼優先 gRPC 使用 .NET 類型來定義服務和訊息合約。

當整個系統使用 .NET 時，程式碼優先是不錯的選擇：

• 可以在 .NET 伺服器與用戶端之間共用 .NET 服務和資料合約類型。
• 無需在 .proto 檔案和程式碼產生作業中定義合約。

在使用多種語言的多語言系統中不建議使用程式碼優先。 .NET 服務和資料合約類型無法與非 .NET 平台一起使用。 若要呼叫使用程式碼優先撰寫的 gRPC 服務，其他平台必須建立符合服務的 .proto 合約。

protobuf-net.Grpc

重要

如需 protobuf-net.Grpc 的說明，請瀏覽 protobuf-net.Grpc 網站或在 protobuf-net.Grpc GitHub 存放庫上建立問題。

protobuf-net.Grpc 是 Microsoft 不支援的社群專案。 該專案會將程式碼優先支援新增至 Grpc.AspNetCore 和 Grpc.Net.Client。 其使用以屬性標註的 .NET 類型來定義應用程式的 gRPC 服務和訊息。

建立程式碼優先 gRPC 服務的第一個步驟是定義程式碼合約：

• 建立將由伺服器和用戶端共用的新專案。
• 新增 protobuf-net.Grpc 套件參考。
• 建立服務和資料合約類型。

using ProtoBuf.Grpc;
using System.Runtime.Serialization;
using System.ServiceModel;
using System.Threading.Tasks;

namespace Shared.Contracts;

[DataContract]
public class HelloReply
{
    [DataMember(Order = 1)]
    public string Message { get; set; }
}

[DataContract]
public class HelloRequest
{
    [DataMember(Order = 1)]
    public string Name { get; set; }
}

[ServiceContract]
public interface IGreeterService
{
    [OperationContract]
    Task<HelloReply> SayHelloAsync(HelloRequest request,
        CallContext context = default);
}

上述 程式碼：

• 定義 HelloRequest 和 HelloReply 訊息。
• 使用一元 SayHelloAsync gRPC 方法定義 IGreeterService 合約介面。

服務合約會在伺服器上實作，並從用戶端呼叫。

根據方法的串流類型，服務介面上定義的方法必須符合特定簽章：

• 一元
• 伺服器串流
• 用戶端串流
• 雙向串流

如需定義服務合約的詳細資訊，請參閱 protobuf-net.Grpc 使用者入門文件。

建立程式碼優先 gRPC 服務

若要將 gRPC 程式碼優先服務新增至 ASP.NET Core 應用程式，請執行下列動作：

• 新增 protobuf-net.Grpc.AspNetCore 套件參考。

• 新增共用程式碼合約專案的參考。

  <Project Sdk="Microsoft.NET.Sdk.Web">
  
    <PropertyGroup>
      <TargetFramework>net6.0</TargetFramework>
      <Nullable>enable</Nullable>
      <ImplicitUsings>enable</ImplicitUsings>
    </PropertyGroup>
  
    <ItemGroup>
      <PackageReference Include="protobuf-net.Grpc.AspNetCore" Version="1.0.152" />
    </ItemGroup>
  
    <ItemGroup>
        <ProjectReference Include="..\Shared\Shared.Contracts.csproj" />
    </ItemGroup>
  
  </Project>
  

• 建立新的 GreeterService.cs 檔案並實作 IGreeterService 服務介面：

  using Shared.Contracts;
  using ProtoBuf.Grpc;
  
  public class GreeterService : IGreeterService
  {
      public Task<HelloReply> SayHelloAsync(HelloRequest request, CallContext context = default)
      {
          return Task.FromResult(
                  new HelloReply
                  {
                      Message = $"Hello {request.Name}"
                  });
      }
  }
  

• 更新 Program.cs 檔案：

  using ProtoBuf.Grpc.Server;
  
  var builder = WebApplication.CreateBuilder(args);
  
  // Additional configuration is required to successfully run gRPC on macOS.
  // For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682
  
  // Add services to the container.
  builder.Services.AddCodeFirstGrpc();
  
  var app = builder.Build();
  
  // Configure the HTTP request pipeline.
  app.MapGrpcService<GreeterService>();
  app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");
  
  app.Run();
  

  上述醒目提示的程式碼會更新下列內容:

  • AddCodeFirstGrpc 註冊啟用程式碼優先的服務。
  • MapGrpcService<GreeterService> 新增程式碼優先服務端點。

使用程式碼優先和 .proto 檔案實作的 gRPC 服務，可在同一個應用程式中共存。 所有 gRPC 服務都會使用 gRPC 服務組態。

建立程式碼優先 gRPC 用戶端

程式碼優先 gRPC 用戶端使用服務合約來呼叫 gRPC 服務。

• 在 gRPC 用戶端 .csproj 檔案中：

  • 新增 protobuf-net.Grpc 套件參考。
  • 新增 Grpc.Net.Client 套件參考。
  • 新增共用程式碼合約專案的參考。

  <Project Sdk="Microsoft.NET.Sdk">
  
    <PropertyGroup>
      <OutputType>Exe</OutputType>
      <TargetFramework>net6.0</TargetFramework>
      <ImplicitUsings>enable</ImplicitUsings>
      <Nullable>enable</Nullable>
    </PropertyGroup>
  
    <ItemGroup>
      <PackageReference Include="Grpc.Net.Client" Version="2.52.0" />
      <PackageReference Include="protobuf-net.Grpc" Version="1.0.152" />
    </ItemGroup>
      
    <ItemGroup>
      <ProjectReference Include="..\Shared\Shared.Contracts.csproj" />
    </ItemGroup>
  
  </Project>
  

• 更新用戶端 program.cs

  // See https://aka.ms/new-console-template for more information
  using Grpc.Net.Client;
  using ProtoBuf.Grpc.Client;
  using Shared.Contracts;
  
  namespace GrpcGreeterClient;
  
  internal class Program
  {
      private static async Task Main(string[] args)
      {
          using var channel = GrpcChannel.ForAddress("https://localhost:7184");
          var client = channel.CreateGrpcService<IGreeterService>();
  
          var reply = await client.SayHelloAsync(
              new HelloRequest { Name = "GreeterClient" });
  
          Console.WriteLine($"Greeting: {reply.Message}");
          Console.WriteLine("Press any key to exit...");
          Console.ReadKey();
      }
  }
  
  
  

上述 gRPC 用戶端 Program.cs 程式碼：

• 建立 gRPC 通道。
• 使用 CreateGrpcService<IGreeterService> 擴充方法從通道建立程式碼優先用戶端。
• 使用 SayHelloAsync 呼叫 gRPC 服務。

程式碼優先 gRPC 用戶端是從通道建立。 就像一般用戶端一樣，程式碼優先用戶端會使用其通道組態。

檢視或下載範例程式碼 \(英文\) (如何下載)

其他資源

• protobuf-net.Grpc 網站
• protobuf-net.Grpc GitHub 存放庫