Layanan gRPC dengan C#

Dokumen ini menguraikan konsep yang diperlukan untuk menulis aplikasi gRPC di C#. Topik yang dibahas di sini berlaku untuk aplikasi gRPC berbasis C-core dan ASP.NET Core.

file proto

gRPC menggunakan pendekatan yang mengutamakan kontrak untuk pengembangan API. Buffer protokol (protobuf) digunakan sebagai Bahasa Definisi Antarmuka (IDL) secara default. File .proto berisi:

• Definisi layanan gRPC.
• Pesan yang dikirim antara klien dan server.

Untuk informasi selengkapnya tentang sintaks file protobuf, lihat Membuat pesan Protobuf untuk aplikasi .NET.

Misalnya, pertimbangkan file greet.proto yang digunakan di Memulai layanan gRPC:

• Greeter Menentukan layanan.
• Layanan Greeter mendefinisikan SayHello panggilan.
• SayHelloHelloRequest mengirim pesan dan menerima HelloReply pesan:

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

Jika Anda ingin melihat komentar kode yang diterjemahkan ke bahasa selain bahasa Inggris, beri tahu kami dalam masalah diskusi GitHub ini.

.proto Menambahkan file ke aplikasi C#

File .proto disertakan dalam proyek dengan menambahkannya ke <Protobuf> grup item:

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

Secara default, <Protobuf> referensi menghasilkan klien konkret dan kelas dasar layanan. Atribut elemen GrpcServices referensi dapat digunakan untuk membatasi pembuatan aset C#. Opsi yang valid GrpcServices adalah:

• Both (default saat tidak ada)
• Server
• Client
• None

Dukungan Alat C# untuk file .proto

Paket alat Grpc.Tools diperlukan untuk menghasilkan aset C# dari .proto file. Aset yang dihasilkan (file):

• Dihasilkan sesuai kebutuhan setiap kali proyek dibangun.
• Tidak ditambahkan ke proyek atau diperiksa ke kontrol sumber.
• Adalah artefak build yang terkandung dalam direktori obj .

Paket ini diperlukan oleh proyek server dan klien. Metapackage Grpc.AspNetCore mencakup referensi ke Grpc.Tools. Proyek server dapat menambahkan Grpc.AspNetCore menggunakan Manajer Paket di Visual Studio atau dengan menambahkan <PackageReference> ke file proyek:

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

Proyek klien harus langsung mereferensikan Grpc.Tools bersama paket lain yang diperlukan untuk menggunakan klien gRPC. Paket peralatan tidak diperlukan saat runtime, sehingga dependensi ditandai dengan 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>

Aset C# yang dihasilkan

Paket alat menghasilkan jenis C# yang mewakili pesan yang ditentukan dalam file yang disertakan .proto .

Untuk aset sisi server, jenis dasar layanan abstrak dihasilkan. Jenis dasar berisi definisi semua panggilan gRPC yang terkandung dalam .proto file. Buat implementasi layanan konkret yang berasal dari jenis dasar ini dan terapkan logika untuk panggilan gRPC. greet.protoUntuk , contoh yang dijelaskan sebelumnya, jenis abstrak GreeterBase yang berisi metode virtual SayHello dihasilkan. Implementasi GreeterService konkret mengambil alih metode dan mengimplementasikan logika penanganan panggilan 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
        });
    }
}

Untuk aset sisi klien, jenis klien konkret dihasilkan. Panggilan gRPC dalam file diterjemahkan .proto ke dalam metode pada jenis beton, yang dapat dipanggil. greet.protoUntuk , contoh yang dijelaskan sebelumnya, jenis beton GreeterClient dihasilkan. Panggil GreeterClient.SayHelloAsync untuk memulai panggilan gRPC ke 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();

Secara default, aset server dan klien dihasilkan untuk setiap .proto file yang disertakan <Protobuf> dalam grup item. Untuk memastikan hanya aset server yang dihasilkan dalam proyek server, GrpcServices atribut diatur ke Server.

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

Demikian pula, atribut diatur ke Client dalam proyek klien.

Sumber Daya Tambahan:

• Gambaran umum untuk gRPC di .NET
• Membuat klien dan server gRPC .NET Core di ASP.NET Core
• Layanan gRPC dengan ASP.NET Core
• Memanggil layanan gRPC dengan klien .NET