Migrasi gRPC dari C-core ke gRPC untuk .NET

Karena implementasi tumpukan yang mendasar, tidak semua fitur berfungsi dengan cara yang sama antara aplikasi gRPC berbasis C-core dan gRPC untuk .NET. Dokumen ini menyoroti perbedaan utama untuk migrasi di antara dua tumpukan.

Penting

gRPC C-core berada dalam mode pemeliharaan dan tidak akan digunakan lagi demi gRPC untuk .NET. gRPC C-core tidak disarankan untuk aplikasi baru.

Dukungan platform

gRPC C-core dan gRPC untuk .NET memiliki dukungan platform yang berbeda:

• gRPC C-core: Implementasi C++ gRPC dengan tumpukan TLS dan HTTP/2 sendiri. Paket Grpc.Core ini adalah pembungkus .NET di sekitar gRPC C-core dan berisi klien dan server gRPC. Ini mendukung .NET Framework, .NET Core, dan .NET 5 atau yang lebih baru.
• gRPC untuk .NET: Dirancang untuk .NET Core 3.x dan .NET 5 atau yang lebih baru. Ini menggunakan tumpukan TLS dan HTTP/2 yang dibangun ke dalam rilis .NET modern. Paket Grpc.AspNetCore berisi server gRPC yang dihosting di ASP.NET Core dan memerlukan .NET Core 3.x atau .NET 5 atau yang lebih baru. Paket Grpc.Net.Client berisi klien gRPC. Klien di Grpc.Net.Client memiliki dukungan terbatas untuk .NET Framework menggunakan WinHttpHandler.

Untuk informasi selengkapnya, lihat gRPC pada platform yang didukung .NET.

Mengonfigurasi server dan saluran

Paket, konfigurasi, dan kode startup NuGet harus dimodifikasi saat bermigrasi dari gRPC C-Core ke gRPC untuk .NET.

gRPC untuk .NET memiliki paket NuGet terpisah untuk klien dan servernya. Paket yang ditambahkan bergantung pada apakah aplikasi menghosting layanan gRPC atau memanggilnya:

• Grpc.AspNetCore: Layanan dihosting oleh ASP.NET Core. Untuk informasi konfigurasi server, lihat layanan gRPC dengan ASP.NET Core.
• Grpc.Net.Client: Klien menggunakan GrpcChannel, yang secara internal menggunakan fungsionalitas jaringan yang disertakan dalam .NET. Untuk informasi konfigurasi klien, lihat Memanggil layanan gRPC dengan klien .NET.

Setelah migrasi selesai, Grpc.Core paket harus dihapus dari aplikasi. Grpc.Core berisi biner asli besar, dan menghapus paket mengurangi waktu pemulihan NuGet dan ukuran aplikasi.

Layanan dan klien yang dihasilkan kode

gRPC C-Core dan gRPC untuk .NET berbagi banyak API, dan kode yang dihasilkan dari .proto file kompatibel dengan kedua implementasi gRPC. Sebagian besar klien dan layanan dapat dimigrasikan dari C-Core ke gRPC untuk .NET tanpa perubahan.

Masa pakai implementasi layanan gRPC

Di tumpukan ASP.NET Core, layanan gRPC, secara default, dibuat dengan masa pakai terlingkup. Sebaliknya, GRPC C-core secara default mengikat ke layanan dengan masa pakai singleton.

Masa pakai terlingkup memungkinkan implementasi layanan untuk menyelesaikan layanan lain dengan masa pakai terlingkup. Misalnya, masa pakai tercakup juga dapat diselesaikan DbContext dari kontainer DI melalui injeksi konstruktor. Menggunakan masa pakai terlingkup:

• Instans baru implementasi layanan dibangun untuk setiap permintaan.
• Tidak dimungkinkan untuk berbagi status antara permintaan melalui anggota instans pada jenis implementasi.
• Harapannya adalah untuk menyimpan status bersama dalam layanan singleton dalam kontainer DI. Status bersama yang disimpan diselesaikan dalam konstruktor implementasi layanan gRPC.

Untuk informasi selengkapnya tentang masa pakai layanan, lihat Injeksi dependensi di ASP.NET Core.

Menambahkan layanan singleton

Untuk memfasilitasi transisi dari implementasi C-core gRPC ke ASP.NET Core, Anda dapat mengubah masa pakai layanan implementasi layanan dari cakupan ke singleton. Ini melibatkan penambahan instans implementasi layanan ke kontainer DI:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
    services.AddSingleton(new GreeterService());
}

Namun, implementasi layanan dengan masa pakai singleton tidak lagi dapat menyelesaikan layanan terlingkup melalui injeksi konstruktor.

Mengonfigurasi opsi layanan gRPC

Di aplikasi berbasis C-core, pengaturan seperti grpc.max_receive_message_length dan grpc.max_send_message_length dikonfigurasi saat ChannelOption membuat instans Server.

Di ASP.NET Core, gRPC menyediakan konfigurasi melalui jenis .GrpcServiceOptions Misalnya, layanan gRPC ukuran pesan masuk maksimum dapat dikonfigurasi melalui AddGrpc. Contoh berikut mengubah default MaxReceiveMessageSize 4 MB menjadi 16 MB:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc(options =>
    {
        options.MaxReceiveMessageSize = 16 * 1024 * 1024; // 16 MB
    });
}

Untuk informasi selengkapnya tentang konfigurasi, lihat konfigurasi gRPC untuk .NET.

Pencatatan

Aplikasi berbasis C-core mengandalkan GrpcEnvironment untuk mengonfigurasi pencatat untuk tujuan penelusuran kesalahan. Tumpukan ASP.NET Core menyediakan fungsionalitas ini melalui API Pengelogan. Misalnya, pencatat dapat ditambahkan ke layanan gRPC melalui injeksi konstruktor:

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

Untuk informasi selengkapnya tentang pengelogan dan diagnostik gRPC, lihat Pengelogan dan diagnostik di gRPC di .NET.

HTTPS

Aplikasi berbasis C-core mengonfigurasi HTTPS melalui properti Server.Ports. Konsep serupa digunakan untuk mengonfigurasi server di ASP.NET Core. Misalnya, Kestrel menggunakan konfigurasi titik akhir untuk fungsionalitas ini.

Interseptor gRPC

ASP.NET Core middleware menawarkan fungsionalitas serupa dibandingkan dengan pencegat di aplikasi gRPC berbasis C-core. Keduanya didukung oleh aplikasi gRPC ASP.NET Core, sehingga tidak perlu menulis ulang pencegat.

Untuk informasi selengkapnya tentang bagaimana fitur ini dibandingkan satu sama lain, lihat Interseptor gRPC versus Middleware.

Host gRPC dalam proyek non-ASP.NET Core

Server berbasis C-core dapat ditambahkan ke jenis proyek apa pun. gRPC untuk server .NET memerlukan ASP.NET Core. ASP.NET Core biasanya tersedia karena file proyek menentukan Microsoft.NET.SDK.Web sebagai SDK.

Server gRPC dapat dihosting <FrameworkReference Include="Microsoft.AspNetCore.App" /> untuk non-ASP.NET proyek Core dengan menambahkan ke proyek. Referensi kerangka kerja membuat API ASP.NET Core tersedia dan dapat digunakan untuk memulai server ASP.NET Core.

Untuk informasi selengkapnya, lihat Host gRPC di proyek non-ASP.NET Core.

Sumber Daya Tambahan:

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