Layanan gRPC dengan C#

Artikel ini memberikan gambaran umum tentang konsep yang diperlukan untuk menulis aplikasi gRPC di C#. Informasi yang disajikan berlaku untuk aplikasi gRPC berbasis C dan berbasis ASP.NET Core.

Tinjau berkas .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.

Pertimbangkan file greet.proto yang digunakan dalam tutorial, Buat klien dan server gRPC di ASP.NET Core:

• File ini menentukan layanan Greeter.
• Layanan Greeter mendefinisikan panggilan SayHello.
• Panggilan SayHello mengirim pesan HelloRequest dan menerima pesan HelloReply .

File berisi kode berikut:

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

Menambahkan file .proto 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 ketika tidak ada)
• Server
• Client
• None

Dukungan alat C# untuk file .proto

Paket alat Grpc.Tools diperlukan untuk menghasilkan aset C# dari file .proto .

Aset (file) yang dihasilkan memiliki karakteristik berikut:

• Mereka dihasilkan sesuai kebutuhan setiap kali proyek dibangun.
• Mereka tidak ditambahkan ke proyek atau diperiksa ke kontrol sumber.
• Mereka adalah artefak pembuatan yang terkandung dalam direktori obj.

Proyek server dan klien memerlukan paket ini. Metapackage Grpc.AspNetCore mencakup referensi ke Grpc.Tools. Proyek server dapat menambahkan Grpc.AspNetCore dengan menggunakan Package Manager 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 alat bantu tidak dibutuhkan di runtime, sehingga dependensi ditandai dengan pengaturan 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 .proto yang disertakan.

Untuk aset sisi server, jenis dasar layanan abstrak dihasilkan. Jenis dasar berisi definisi semua panggilan gRPC yang terkandung dalam file .proto . Buat implementasi layanan konkret yang berasal dari jenis dasar ini dan terapkan logika untuk panggilan gRPC. Untuk file greet.proto yang digunakan dalam contoh 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 .proto diterjemahkan ke dalam metode pada tipe konkret, yang bisa dipanggil. Untuk file greet.proto yang digunakan dalam contoh 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 file .proto yang disertakan dalam <Protobuf> grup item. Untuk memastikan hanya aset server yang dihasilkan dalam proyek server, atribut GrpcServices diatur ke Server.

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

Demikian pula, atribut diatur ke Client dalam proyek klien.

Konten terkait

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