Derinlemesine yazılım eğitimleri için kanalımı takip edebilirsiniz...

.NET 7 – Asp.NET Core gRPC Uygulamalarında JSON Transcoding

Yazar: Gençay · Yayımlanmış 22 Aralık 2022 · Güncellendi 22 Aralık 2022

Merhaba,

Bu içeriğimizde gRPC teknolojisini REST API olarak kullanmamızı sağlayacak olan .NET 7 ile gelen JSON Transcoding özelliğini tüm teferruatlarıyla birlikte değerlendiriyor olacağız.

gRPC, bilindiği üzere yüksek performanslı(high-performance) ve gerçek zamanlı(real-time) servisler üretmemizi sağlayan, birçok avantajın yanında belli başlı sınırlılıklar barındıran Remote Procedure Call(RPC) framework’üdür. gRPC’nin en büyük sınırlılıklarından biri her platforma uygun bir modele sahip olmamasıdır. Özellikle web browser’ların binary protokolleri yorumlayamaması ve HTTP/2 protokolünü tam olarak desteklememesinden dolayı gRPC’nin getirdiği avantajlardan ziyade modern web uygulamalarında hala REST API’lar ve JSON formatındaki veriler yerlerini korumaktadırlar.

.NET 7 ile gelen JSON Transcoding özelliği sayesinde artık gRPC servisleri için RESTful JSON API’ları oluşturabilir ve bildiğiniz HTTP konseptleri eşliğinde gRPC’yi kullanabilirsiniz. Böylece deneysel olarak gRPC JSON Transcoding ile HTTP API’larının yerini alacak alternatif bir çözüm yolu üretebilirsiniz.

gRPC JSON Transcoding, deneysel olarak HTTP API’ların yerini alabilecek alternatif bir çözüm olabilir…

Nasıl Kullanılır?

gRPC JSON Transcoding özelliğini kullanabilmek için öncelikle gRPC Server uygulamasına Microsoft.AspNetCore.Grpc.JsonTranscoding kütüphanesinin yüklenmesi ve ardından ‘Program.cs’ dosyasında aşağıdaki gibi AddJsonTranscoding servisi çağrılarak uygulamanın yapılandırılması gerekmektedir.

using gRPC_Server.Services;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCors(options => options.AddDefaultPolicy(policy => policy.AllowAnyMethod()
                                                                             .AllowAnyHeader()
                                                                             .AllowAnyOrigin()));

builder.Services.AddGrpc()
    .AddJsonTranscoding();

var app = builder.Build();
app.UseCors();

app.MapGrpcService<MessageService>();
app.MapGet("/", () => "");

app.Run();

Bu konfigürasyonlardan sonra projenin root dizininde ‘google/api’ path’i altına http.proto ve annotations.proto dosyalarını ekleyiniz.Son olarak .proto dosyanızı aşağıdaki gibi HTTP konseptine uygun bir şekilde güncelleyiniz.

syntax = "proto3";

option csharp_namespace = "gRPC_Server";

import "google/api/annotations.proto";

package message;

service Message {
  rpc SendMessage (MessageRequest) returns (stream MessageReply){
    option (google.api.http) = {
      get: "/message/{text}"
    };
  };
}

message MessageRequest {
  string text = 1;
}

message MessageReply {
  string text = 1;
}

Burada 5. satıra bakarsanız google/api/annotations.proto path’indeki dosya import edilmekte ve 11 ile 13. satır aralığında ‘SendMessage’ fonksiyonunun HTTP protokolü üzerinden /message/{text} endpoint’i eşliğinde ‘GET’ türünden tetiklenebileceği bildirilmektedir. Buradaki {text} parametresi ise, tetikleme sürecinde ilgili fonksiyonun aldığı ‘MessageRequest’ nesnesinin ‘text’ field’ına karşılık gelmektedir.

Böylece ‘SendMessage’ metodu artık hem gRPC hem de JSON Web API olarak çağrılabilecek şekilde tasarlanmıştır. Misal olarak tarayıcı üzerinden ilgili endpoint’e bir istek gönderdiğimizde cevap olarak aşağıdaki ekran görüntüsündeki değeri elde ediyor olacağız.

gRPC JSON Transcoding’i GET isteklerinin dışında aşağıdaki HTTP metotlarının hepsiyle de kullanabilmekteyiz.

GET
POST
PUT
DELETE
PATCH

Örneğin, POST isteğini karşılayabilecek bir metodu aşağıdaki gibi tasarlayabiliriz.

syntax = "proto3";

option csharp_namespace = "gRPC_Server";

import "google/api/annotations.proto";

package person;

service Person {
  rpc CreatePerson (PersonRequest) returns (PersonResponse){
    option (google.api.http) = {
      post: "/persons",
      body : "*"
    };
  };
}
message PersonRequest {
  string name = 1;
  string surname = 2;
}

message PersonResponse {
  string message = 1;
}

gRPC JSON Transcoding | Swagger

Ayrıca yapılan tüm bu konfigürasyonları Swashbuckle ile entegre ederek gRPC’yi Swagger arayüzü üzerinden de test edebiliriz. Bunun için server uygulamasına Microsoft.AspNetCore.Grpc.Swagger kütüphanesini yükleyiniz ve ‘Program.cs’ dosyasında aşağıdaki yapılandırmayı gerçekleştiriniz.

using gRPC_Server.Services;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCors(options => options.AddDefaultPolicy(policy => policy.AllowAnyMethod()
                                                                             .AllowAnyHeader()
                                                                             .AllowAnyOrigin()));

builder.Services.AddGrpc()
    .AddJsonTranscoding();

builder.Services.AddGrpcSwagger();
builder.Services.AddSwaggerGen(options =>
                               options.SwaggerDoc("v1", new OpenApiInfo
                               {
                                   Title = "gRPC Transcoding",
                                   Version = "v1"
                               }));

var app = builder.Build();
app.UseCors();

app.UseSwagger();
app.UseSwaggerUI(options => options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"));

app.MapGrpcService<MessageService>();
app.MapGrpcService<PersonService>();
app.MapGet("/", () => "");

app.Run();

Yukarıdaki kod bloğunu incelerseniz eğer Swagger için 12 ile 13. satırlardaki gibi uygulamaya gerekli servislerin eklenmesi ve devamında ise 23 ile 24. satırlardaki gibi middleware’lerin çağrılması yeterli olacaktır.

Bunun dışında .proto dosyasında aşağıdaki gibi yorum satırlarından da açıklama satırları oluşturulabilir.

.
.
.
//Person service
service Person {
    //Person creater service
  rpc CreatePerson (PersonRequest) returns (PersonResponse){
    option (google.api.http) = {
      post: "/persons",
      body : "*"
    };
  };
}
.
.
.

Tabi yorum satırlarını açıklama satırı olarak okuyabilmek için server uygulamasının .csproj dosyasında <GenerateDocumentationFile>true</GenerateDocumentationFile> komutu ile gerekli etkinleştirmenin yapılması ve ardından yine ‘Program.cs’ dosyasında AddSwaggerGen metodunda aşağıdaki gibi yapılandırmanın inşası gerekmektedir.

.
.
.
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "gRPC Transcoding",
        Version = "v1"
    });

    var filePath = Path.Combine(System.AppContext.BaseDirectory, "gRPC_Server.xml");
    options.IncludeXmlComments(filePath);
    options.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);
});
.
.
.

Nihai olarak ilgili servisi ayağa kaldırdığımızda Swagger arayüzünü aşağıdaki gibi görebiliriz.