ASP.NET Core: Tổng quan dịch vụ gRPC với C#

Trong bài viết này

1. Tập tin proto
2. Thêm file .proto vào ứng dụng C#
3. Hỗ trợ công cụ C# cho các file .proto
4. Nội dung C# được tạo
5. Tài nguyên bổ sung

Bài viết này phác thảo các khái niệm cần thiết để viết ứng dụng gRPC trong C#. Các chủ đề được đề cập ở đây áp dụng cho cả ứng dụng gRPC dựa trên C-core và dựa trên ASP.NET Core.

gRPC sử dụng cách tiếp cận ưu tiên hợp đồng để phát triển API. Bộ đệm giao thức (protobuf) được sử dụng làm Ngôn ngữ định nghĩa giao diện (Interface Definition Language - IDL) theo mặc định. Tập tin .proto chứa:

• Định nghĩa về dịch vụ gRPC.
• Các tin nhắn được gửi giữa máy khách và máy chủ.

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

Ví dụ: hãy xem xét tệp hello.proto được sử dụng trong Bắt đầu với dịch vụ gRPC:

• Định nghĩa một dịch vụ Greeter.
• Dịch vụ Greeter xác định một lời gọi SayHello.
• SayHello gửi tin nhắn HelloRequest và nhận tin nhắn HelloReply:

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;
}

Nếu bạn muốn xem các nhận xét về mã được dịch sang các ngôn ngữ khác ngoài tiếng Anh, hãy cho chúng tôi biết trong vấn đề thảo luận GitHub này.

File .proto được đưa vào dự án bằng cách thêm nó vào nhóm mục <Protobuf>:

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

Theo mặc định, một tham chiếu <Protobuf> sẽ tạo ra một ứng dụng khách cụ thể và một lớp cơ sở dịch vụ. Attribute của phần tử tham chiếu GrpcServices có thể được sử dụng để hạn chế việc tạo nội dung C#. Các tùy chọn GrpcServices hợp lệ là:

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

Cần có gói công cụ Grpc.Tools để tạo nội dung C# từ các tệp .proto. Nội dung được tạo (tệp):

• Được tạo ra trên cơ sở khi cần thiết mỗi khi dự án được xây dựng.
• Không được thêm vào dự án hoặc được kiểm tra trong kiểm soát nguồn.
• Là một tạo phẩm xây dựng có trong thư mục obj.

Gói này được yêu cầu bởi cả dự án máy chủ và máy khách. Siêu gói Grpc.AspNetCore bao gồm một tham chiếu đến Grpc.Tools. Các dự án máy chủ có thể thêm Grpc.AspNetCore bằng Trình quản lý gói trong Visual Studio hoặc bằng cách thêm <PackageReference> vào tệp dự án:

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

Các dự án client nên tham khảo trực tiếp Grpc.Tools cùng với các gói khác cần thiết để sử dụng ứng dụng khách gRPC. Gói công cụ này không bắt buộc trong thời gian chạy, vì vậy phần phụ thuộc được đánh dấu bằng 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>

Gói công cụ tạo ra các kiểu C# đại diện cho các thông báo được xác định trong các file .proto đã được bao gồm.

Đối với nội dung phía máy chủ, loại cơ sở dịch vụ trừu tượng sẽ được tạo. Loại cơ sở chứa các định nghĩa của tất cả các lệnh gọi gRPC có trong file .proto. Tạo triển khai dịch vụ cụ thể bắt nguồn từ loại cơ sở này và triển khai logic cho lệnh gọi gRPC. Đối với greet.proto, là ví dụ được mô tả ở trên, một kiểu GreeterBase trừu tượng chứa phương thức SayHello ảo được tạo. Việc triển khai cụ thể GreeterService sẽ ghi đè phương thức và triển khai logic xử lý lệnh gọi gRPC.

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 nội dung phía máy khách, một kiểu máy khách cụ thể sẽ được tạo. Các lệnh gọi gRPC trong file .proto được dịch thành các phương thức trên kiểu cụ thể, có thể được gọi. Đối với ví dụ greet.proto được mô tả ở trên, một kiểu GreeterClient cụ thể được tạo ra. Gọi GreeterClient.SayHelloAsync để bắt đầu lời gọi gRPC đến máy chủ.

// Số cổng phải khớp với cổng của máy chủ gRPC.
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, nội dung máy chủ và máy khách được tạo cho mỗi file .proto có trong nhóm mục <Protobuf>. Để đảm bảo chỉ có nội dung máy chủ được tạo trong dự án máy chủ, attribute GrpcServices được đặt thành Server.

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

Tương tự, attribute này được đặt thành Clienttrong các dự án máy khách.

• Tổng quan về gRPC trên .NET
• Tạo máy khách và máy chủ .NET Core gRPC trong ASP.NET Core
• Dịch vụ gRPC với ASP.NET Core
• Gọi các dịch vụ gRPC bằng máy khách .NET