C# içeren gRPC hizmetleri

  • Makale

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Bu belgede C# dilinde gRPC uygulamaları yazmak için gereken kavramlar özetlenmiştir. Burada ele alınan konular hem C çekirdek tabanlı hem de ASP.NET Çekirdek tabanlı gRPC uygulamaları için geçerlidir.

proto dosyası

gRPC, API geliştirme için sözleşme öncelikli bir yaklaşım kullanır. Protokol arabellekleri (protobuf), varsayılan olarak Arabirim Tanım Dili (IDL) olarak kullanılır. Dosya aşağıdakileri .proto içerir:

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

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

Örneğin, gRPC hizmetini kullanmaya başlama bölümünde kullanılan greet.proto dosyasını göz önünde bulundurun:

  • Bir Greeter hizmeti tanımlar.
  • Hizmet Greeter bir SayHello çağrı tanımlar.
  • 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;
}

Kod açıklamalarının İngilizce dışındaki dillere çevirisini görmek isterseniz, bunu bu GitHub tartışma konusunda bize bildirin.

.proto C# uygulamasına dosya ekleme

Dosya .proto , öğe grubuna <Protobuf> eklenerek projeye eklenir:

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

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

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

.proto dosyaları için C# Araç desteği

Dosyalardan .proto C# varlıklarını oluşturmak için Grpc.Tools araç paketi gereklidir. Oluşturulan varlıklar (dosyalar):

  • Proje her oluşturulduğunda gerektiği gibi oluşturulur.
  • Projeye eklenmez veya kaynak denetimine iade edilemez.
  • obj dizininde bulunan bir derleme yapıtıdır.

Bu paket hem sunucu hem de istemci projeleri için gereklidir. Grpc.AspNetCore Meta paketi için Grpc.Toolsbir başvuru içerir. Sunucu projeleriGrpc.AspNetCore, Visual Studio'daki Paket Yöneticisi kullanarak veya proje dosyasına bir <PackageReference> ekleyerek ekleyebilir:

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

İstemci projeleri, gRPC istemcisini kullanmak için gereken diğer paketlerin yanı sıra doğrudan başvurmalıdır Grpc.Tools . Araç paketi çalışma zamanında gerekli olmadığından bağımlılık ile PrivateAssets="All"işaretlenir:

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

Oluşturulan C# varlıkları

Araç paketi, dahil .proto edilen dosyalarda tanımlanan iletileri temsil eden C# türlerini oluşturur.

Sunucu tarafı varlıklar için soyut bir hizmet temel türü oluşturulur. Temel tür, dosyada yer alan tüm gRPC çağrılarının tanımlarını .proto içerir. Bu temel türden türetilen ve gRPC çağrıları için mantığı uygulayan somut bir hizmet uygulaması oluşturun. greet.protoiçin, daha önce açıklanan örnekte, sanal SayHello yöntem içeren bir soyut GreeterBase tür oluşturulur. Somut bir uygulama GreeterService yöntemini geçersiz kılar ve gRPC çağrısını işleyen mantığı 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. Dosyadaki .proto gRPC çağrıları, somut türdeki yöntemlere çevrilir ve bu yöntemler çağrılabilir. greet.protoiçin, daha önce açıklanan örnek için somut GreeterClient bir tür oluşturulur. Sunucuya GreeterClient.SayHelloAsync gRPC çağrısı başlatmak için çağrısı.

// 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, öğe grubuna <Protobuf> dahil edilen her .proto dosya için sunucu ve istemci varlıkları oluşturulur. Bir sunucu projesinde GrpcServices yalnızca sunucu varlıklarının oluşturulduğundan emin olmak için özniteliği olarak Serverayarlanır.

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

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

Ek kaynaklar

Bu belgede C# dilinde gRPC uygulamaları yazmak için gereken kavramlar özetlenmiştir. Burada ele alınan konular hem C çekirdek tabanlı hem de ASP.NET Çekirdek tabanlı gRPC uygulamaları için geçerlidir.

proto dosyası

gRPC, API geliştirme için sözleşme öncelikli bir yaklaşım kullanır. Protokol arabellekleri (protobuf), varsayılan olarak Arabirim Tanım Dili (IDL) olarak kullanılır. Dosya aşağıdakileri .proto içerir:

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

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

Örneğin, gRPC hizmetini kullanmaya başlama bölümünde kullanılan greet.proto dosyasını göz önünde bulundurun:

  • Bir Greeter hizmeti tanımlar.
  • Hizmet Greeter bir SayHello çağrı tanımlar.
  • 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;
}

Kod açıklamalarının İngilizce dışındaki dillere çevirisini görmek isterseniz, bunu bu GitHub tartışma konusunda bize bildirin.

.proto C# uygulamasına dosya ekleme

Dosya .proto , öğe grubuna <Protobuf> eklenerek projeye eklenir:

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

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

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

.proto dosyaları için C# Araç desteği

Dosyalardan .proto C# varlıklarını oluşturmak için Grpc.Tools araç paketi gereklidir. Oluşturulan varlıklar (dosyalar):

  • Proje her oluşturulduğunda gerektiği gibi oluşturulur.
  • Projeye eklenmez veya kaynak denetimine iade edilemez.
  • obj dizininde bulunan bir derleme yapıtıdır.

Bu paket hem sunucu hem de istemci projeleri için gereklidir. Grpc.AspNetCore Meta paketi için Grpc.Toolsbir başvuru içerir. Sunucu projeleriGrpc.AspNetCore, Visual Studio'daki Paket Yöneticisi kullanarak veya proje dosyasına bir <PackageReference> ekleyerek ekleyebilir:

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

İstemci projeleri, gRPC istemcisini kullanmak için gereken diğer paketlerin yanı sıra doğrudan başvurmalıdır Grpc.Tools . Araç paketi çalışma zamanında gerekli olmadığından bağımlılık ile PrivateAssets="All"işaretlenir:

<PackageReference Include="Google.Protobuf" Version="3.11.4" />
<PackageReference Include="Grpc.Net.Client" Version="2.52.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, dahil .proto edilen dosyalarda tanımlanan iletileri temsil eden C# türlerini oluşturur.

Sunucu tarafı varlıklar için soyut bir hizmet temel türü oluşturulur. Temel tür, dosyada yer alan tüm gRPC çağrılarının tanımlarını .proto içerir. Bu temel türden türetilen ve gRPC çağrıları için mantığı uygulayan somut bir hizmet uygulaması oluşturun. greet.protoiçin, daha önce açıklanan örnekte, sanal SayHello yöntem içeren bir soyut GreeterBase tür oluşturulur. Somut bir uygulama GreeterService yöntemini geçersiz kılar ve gRPC çağrısını işleyen mantığı 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. Dosyadaki .proto gRPC çağrıları, somut türdeki yöntemlere çevrilir ve bu yöntemler çağrılabilir. greet.protoiçin, daha önce açıklanan örnek için somut GreeterClient bir tür oluşturulur. Sunucuya GreeterClient.SayHelloAsync gRPC çağrısı başlatmak için çağrısı.

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, öğe grubuna <Protobuf> dahil edilen her .proto dosya için sunucu ve istemci varlıkları oluşturulur. Bir sunucu projesinde GrpcServices yalnızca sunucu varlıklarının oluşturulduğundan emin olmak için özniteliği olarak Serverayarlanır.

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

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

Ek kaynaklar