gRPC Services với C#

Bài viết này cung cấp tổng quan về các khái niệm cần thiết để viết ứng dụng gRPC trong C#. Thông tin trình bày áp dụng cho cả ứng dụng gRPC dựa trên C-core và ASP.NET Core.

Xem xét tệp .proto

gRPC sử dụng cách tiếp cận contract-first (hợp đồng trước) để phát triển API. Protocol buffers (bộ đệm giao thức) — còn gọi là protobuf — được sử dụng làm Interface Definition Language (IDL - Ngôn ngữ định nghĩa giao diện) theo mặc định. Tệp .proto chứa:

• Định nghĩa gRPC service.
• Các message (thông điệp) được gửi giữa client và server.

Để biết thêm về cú pháp của tệp protobuf, xem Tạo Protobuf messages cho ứng dụng .NET.

Hãy xem xét tệp greet.proto được sử dụng trong hướng dẫn Tạo gRPC client và server trong ASP.NET Core:

• Tệp định nghĩa một Greeter service.
• Greeter service định nghĩa một SayHello call (lời gọi).
• SayHello call gửi một HelloRequest message và nhận một HelloReply message.

Tệp chứa mã sau:

syntax = "proto3";

option csharp_namespace = "GrpcGreeter";

package greet;

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply);
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings.
message HelloReply {
  string message = 1;
}

Thêm tệp .proto vào ứng dụng C#

Tệp .proto được đưa vào project bằng cách thêm nó vào item group (nhóm mục) <Protobuf>:

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

Theo mặc định, một tham chiếu <Protobuf> tạo ra một concrete client (client cụ thể) và một service base class (lớp cơ sở dịch vụ). Thuộc tính GrpcServices của phần tử tham chiếu có thể được dùng để giới hạn việc tạo C# asset (tài sản). Các tùy chọn GrpcServices hợp lệ là:

• Both (mặc định khi không có)
• Server
• Client
• None

Hỗ trợ công cụ C# cho tệp .proto

Package công cụ Grpc.Tools là bắt buộc để tạo C# assets từ tệp .proto.

Các assets (tệp) được tạo có đặc điểm sau:

• Được tạo theo nhu cầu mỗi khi project được build.
• Không được thêm vào project hoặc checked into source control (kiểm soát mã nguồn).
• Là build artifact (sản phẩm build) nằm trong thư mục obj.

Cả project server và client đều cần package này. Metapackage Grpc.AspNetCore bao gồm tham chiếu đến Grpc.Tools. Project server có thể thêm Grpc.AspNetCore bằng cách sử dụng Package Manager trong Visual Studio hoặc thêm <PackageReference> vào tệp project:

<PackageReference Include="Grpc.AspNetCore" Version="2.32.0" />

Project client nên tham chiếu trực tiếp Grpc.Tools cùng với các package khác cần thiết để sử dụng gRPC client. Package công cụ không cần thiết lúc runtime (thời điểm chạy), vì vậy dependency (phụ thuộc) được đánh dấu với thiết lập PrivateAssets="All":

<PackageReference Include="Google.Protobuf" Version="3.18.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.52.0" />
<PackageReference Include="Grpc.Tools" Version="2.40.0">
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  <PrivateAssets>all</PrivateAssets>
</PackageReference>

C# assets được tạo tự động

Package công cụ tạo các C# types đại diện cho các message được định nghĩa trong tệp .proto được đưa vào.

Đối với server-side assets (tài sản phía server), một abstract service base type (kiểu cơ sở dịch vụ trừu tượng) được tạo. Base type chứa định nghĩa của tất cả gRPC calls trong tệp .proto. Tạo một concrete service implementation (triển khai dịch vụ cụ thể) kế thừa từ base type này và thực hiện logic cho các gRPC calls. Đối với tệp greet.proto trong ví dụ trước, một abstract type GreeterBase chứa virtual method SayHello được tạo. Một implementation cụ thể là GreeterService ghi đè method và thực hiện logic xử lý gRPC call.

public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;
    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }

    public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

Đối với client-side assets (tài sản phía client), một concrete client type (kiểu client cụ thể) được tạo. Các gRPC calls trong tệp .proto được chuyển đổi thành các method trên kiểu cụ thể, có thể được gọi. Đối với tệp greet.proto trong ví dụ trước, một concrete type GreeterClient được tạo. Gọi GreeterClient.SayHelloAsync để khởi tạo một gRPC call đến server.

// 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();

Theo mặc định, cả server và client assets đều được tạo cho mỗi tệp .proto được đưa vào item group <Protobuf>. Để đảm bảo chỉ server assets được tạo trong project server, thuộc tính GrpcServices được đặt thành Server.

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

Tương tự, thuộc tính được đặt thành Client trong project client.

Nội dung liên quan

• Tổng quan về gRPC trên .NET
• Tạo .NET gRPC client và server trong ASP.NET Core
• gRPC services với ASP.NET Core
• Gọi gRPC services bằng .NET client