C ile gRPC Hizmetleri#

  • Makale
  • Okumak için 3 dakika

Bu belgede, C# dilinde GRPC uygulamaları yazmak için gereken kavramlar özetlenmektedir. burada ele alınan konular hem C coretabanlı hem de ASP.NET Core tabanlı grpc uygulamaları için geçerlidir.

Uyarı

ASP.NET Core GRPC'nin, Azure App Service IIS ile birlikte Azure App Service gerekir. gRPC'nin nerede kullanılabı hakkında daha fazla bilgi için .NET'de desteklenen platformlarda gRPC bkz. .

Proto dosyası

gRPC, API geliştirmesi için bir sözleşmenin ilk yaklaşımını kullanır. Protokol arabellekleri (protoarabellek) varsayılan olarak arabirim tanım dili (IDL) olarak kullanılır. * . Proto dosyası şunları içerir:

  • GRPC hizmetinin tanımı.
  • İstemciler ve sunucular arasında gönderilen iletiler.

Prototipsiz dosyaların sözdizimi hakkında daha fazla bilgi için bkz .NET uygulamaları için Protobuf iletileri oluşturma ..

Örneğin, gRPC hizmetini kullanmaya başlamabölümünde kullanılan Greet. proto dosyasını düşünün:

  • Bir Greeter hizmeti tanımlar.
  • GreeterHizmet bir çağrıyı tanımlar SayHello .
  • SayHello bir HelloRequest ileti gönderir ve bir HelloReply ileti alır:
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;
}

Ingilizce dışındaki dillere çevrilmiş kod açıklamalarını görmek isterseniz, Bu GitHub tartışma sorununubize tanıyın.

C uygulamasına bir. proto dosyası ekleyin #

* . Proto dosyası bir projeye öğe grubuna eklenerek dahil edilir <Protobuf> :

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

Varsayılan olarak, <Protobuf> başvuru somut bir istemci ve hizmet temel sınıfı oluşturur. Başvuru öğesinin özniteliği, GrpcServices C# varlık oluşturmayı sınırlamak için kullanılabilir. Geçerli GrpcServices Seçenekler şunlardır:

  • Both (mevcut olmadığında varsayılan)
  • Server
  • Client
  • None

. Proto dosyaları için C# araçları desteği

Araçları Paketi GRPC. Tools , * . proto dosyalarından C# varlıkları oluşturmak için gereklidir. Oluşturulan varlıklar (dosyalar):

  • , Projenin oluşturulduğu her seferinde gerekli olarak oluşturulur.
  • Projeye eklenmez veya kaynak denetimine iade edilmedi.
  • Obj dizininde bulunan bir yapı yapıtı.

Bu paket hem sunucu hem de istemci projeleri için gereklidir. Grpc.AspNetCoreMetapackage öğesine bir başvuru içerir Grpc.Tools . sunucu projeleri Grpc.AspNetCore Visual Studio Paket Yöneticisi kullanarak veya bir proje dosyasına bir ekleyerek ekleyebilir <PackageReference> :

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

İstemci projeleri Grpc.Tools , gRPC istemcisini kullanmak için gereken diğer paketlerle birlikte doğrudan başvurmalıdır. Çalışma zamanında araç paketi gerekli değildir, bu nedenle bağımlılık şu şekilde işaretlenir PrivateAssets="All" :

<PackageReference Include="Google.Protobuf" Version="3.18.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.39.0" />
<PackageReference Include="Grpc.Tools" Version="2.40.0">
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
  <PrivateAssets>all</PrivateAssets>
</PackageReference>

Oluşturulan C# varlıkları

Araç paketi, eklenen * . proto dosyalarında tanımlanan Iletileri temsil eden C# türlerini üretir.

Sunucu tarafı varlıklar için, soyut bir hizmet temel türü oluşturulur. Temel tür, . proto dosyasında bulunan tüm GRPC çağrılarının tanımlarını içerir. Bu temel türden türetilen somut bir hizmet uygulamasını oluşturun ve gRPC çağrılarının mantığını uygular. greet.protoDaha önce açıklanan örnek için, GreeterBase sanal bir yöntemi içeren bir soyut tür SayHello oluşturulur. Somut bir uygulama GreeterService , yöntemini geçersiz kılar ve gRPC çağrısını işleme mantığını uygular.

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

İstemci tarafı varlıklar için somut bir istemci türü oluşturulur. . Proto dosyasındaki GRPC çağrıları, çağrılabilecek somut türdeki yöntemlere çevrilir. greet.protoDaha önce açıklanan örnek için somut bir GreeterClient tür oluşturulur. GreeterClient.SayHelloAsyncSunucuya bir gRPC çağrısı başlatmak için çağrısı yapın.

// 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();

Varsayılan olarak, sunucu ve istemci varlıkları öğe grubuna dahil edilen her * . proto dosyası için oluşturulur <Protobuf> . Sunucu projesinde yalnızca sunucu varlıklarının oluşturulmasını sağlamak için GrpcServices özniteliği olarak ayarlanır Server .

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

Benzer şekilde, özniteliği Client istemci projelerinde olarak ayarlanır.

Ek kaynaklar

Bu belgede, C# dilinde GRPC uygulamaları yazmak için gereken kavramlar özetlenmektedir. burada ele alınan konular hem C coretabanlı hem de ASP.NET Core tabanlı grpc uygulamaları için geçerlidir.

Uyarı

ASP.NET Core GRPC'nin, Azure App Service IIS ile birlikte Azure App Service gerekir. gRPC'nin nerede kullanılabı hakkında daha fazla bilgi için .NET'de desteklenen platformlarda gRPC bkz. .

Proto dosyası

gRPC, API geliştirmesi için bir sözleşmenin ilk yaklaşımını kullanır. Protokol arabellekleri (protoarabellek) varsayılan olarak arabirim tanım dili (IDL) olarak kullanılır. * . Proto dosyası şunları içerir:

  • GRPC hizmetinin tanımı.
  • İstemciler ve sunucular arasında gönderilen iletiler.

Prototipsiz dosyaların sözdizimi hakkında daha fazla bilgi için bkz .NET uygulamaları için Protobuf iletileri oluşturma ..

Örneğin, gRPC hizmetini kullanmaya başlamabölümünde kullanılan Greet. proto dosyasını düşünün:

  • Bir Greeter hizmeti tanımlar.
  • GreeterHizmet bir çağrıyı tanımlar SayHello .
  • SayHello bir HelloRequest ileti gönderir ve bir HelloReply ileti alır:
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;
}

Ingilizce dışındaki dillere çevrilmiş kod açıklamalarını görmek isterseniz, Bu GitHub tartışma sorununubize tanıyın.

C uygulamasına bir. proto dosyası ekleyin #

* . Proto dosyası bir projeye öğe grubuna eklenerek dahil edilir <Protobuf> :

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

Varsayılan olarak, <Protobuf> başvuru somut bir istemci ve hizmet temel sınıfı oluşturur. Başvuru öğesinin özniteliği, GrpcServices C# varlık oluşturmayı sınırlamak için kullanılabilir. Geçerli GrpcServices Seçenekler şunlardır:

  • Both (mevcut olmadığında varsayılan)
  • Server
  • Client
  • None

. Proto dosyaları için C# araçları desteği

Araçları Paketi GRPC. Tools , * . proto dosyalarından C# varlıkları oluşturmak için gereklidir. Oluşturulan varlıklar (dosyalar):

  • , Projenin oluşturulduğu her seferinde gerekli olarak oluşturulur.
  • Projeye eklenmez veya kaynak denetimine iade edilmedi.
  • Obj dizininde bulunan bir yapı yapıtı.

Bu paket hem sunucu hem de istemci projeleri için gereklidir. Grpc.AspNetCoreMetapackage öğesine bir başvuru içerir Grpc.Tools . sunucu projeleri Grpc.AspNetCore Visual Studio Paket Yöneticisi kullanarak veya bir proje dosyasına bir ekleyerek ekleyebilir <PackageReference> :

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

İstemci projeleri Grpc.Tools , gRPC istemcisini kullanmak için gereken diğer paketlerle birlikte doğrudan başvurmalıdır. Çalışma zamanında araç paketi gerekli değildir, bu nedenle bağımlılık şu şekilde işaretlenir PrivateAssets="All" :

<PackageReference Include="Google.Protobuf" Version="3.11.4" />
<PackageReference Include="Grpc.Net.Client" Version="2.28.0" />
<PackageReference Include="Grpc.Tools" Version="2.28.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

Oluşturulan C# varlıkları

Araç paketi, eklenen * . proto dosyalarında tanımlanan Iletileri temsil eden C# türlerini üretir.

Sunucu tarafı varlıklar için, soyut bir hizmet temel türü oluşturulur. Temel tür, . proto dosyasında bulunan tüm GRPC çağrılarının tanımlarını içerir. Bu temel türden türetilen somut bir hizmet uygulamasını oluşturun ve gRPC çağrılarının mantığını uygular. greet.protoDaha önce açıklanan örnek için, GreeterBase sanal bir yöntemi içeren bir soyut tür SayHello oluşturulur. Somut bir uygulama GreeterService , yöntemini geçersiz kılar ve gRPC çağrısını işleme mantığını uygular.

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

İstemci tarafı varlıklar için somut bir istemci türü oluşturulur. . Proto dosyasındaki GRPC çağrıları, çağrılabilecek somut türdeki yöntemlere çevrilir. greet.protoDaha önce açıklanan örnek için somut bir GreeterClient tür oluşturulur. GreeterClient.SayHelloAsyncSunucuya bir gRPC çağrısı başlatmak için çağrısı yapın.

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    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();
}

Varsayılan olarak, sunucu ve istemci varlıkları öğe grubuna dahil edilen her * . proto dosyası için oluşturulur <Protobuf> . Sunucu projesinde yalnızca sunucu varlıklarının oluşturulmasını sağlamak için GrpcServices özniteliği olarak ayarlanır Server .

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

Benzer şekilde, özniteliği Client istemci projelerinde olarak ayarlanır.

Ek kaynaklar