Serviços gRPC com C#

Este documento descreve os conceitos necessários para escrever aplicativos gRPC em C#. Os tópicos abordados aqui se aplicam a aplicativos gRPC baseados em C-core e ASP.NET Core.

Ficheiro Proto

O gRPC usa uma abordagem de contrato em primeiro lugar para o desenvolvimento de API. Os buffers de protocolo (protobuf) são usados como IDL (Interface Definition Language) por padrão. O .proto ficheiro contém:

• A definição do serviço gRPC.
• As mensagens enviadas entre clientes e servidores.

Para obter mais informações sobre a sintaxe de arquivos protobuf, consulte Criar mensagens Protobuf para aplicativos .NET.

Por exemplo, considere o arquivo greet.proto usado em Introdução ao serviço gRPC:

• Define um Greeter serviço.
• O Greeter serviço define uma SayHello chamada.
• SayHello envia uma HelloRequest mensagem e recebe uma HelloReply mensagem:

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

Se quiser ver os comentários de código traduzidos para outros idiomas além do inglês, avise-nos nesta discussão do GitHub .

Adicionar um .proto arquivo a um aplicativo C#

O .proto arquivo é incluído em um projeto adicionando-o ao grupo de <Protobuf> itens:

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

Por padrão, uma <Protobuf> referência gera um cliente concreto e uma classe base de serviço. O atributo GrpcServices do elemento de referência pode ser usado para limitar a geração de ativos em C#. As opções válidas GrpcServices são:

• Both (padrão quando não presente)
• Server
• Client
• None

Suporte a ferramentas C# para .proto arquivos

O pacote de ferramentas Grpc.Tools é necessário para gerar os ativos C# a partir de .proto arquivos. Os ativos gerados (arquivos):

• São gerados conforme a necessidade cada vez que o projeto é construído.
• Não são adicionados ao projeto nem verificados no controle do código-fonte.
• São um artefato de construção contido no diretório obj .

Este pacote é exigido pelos projetos de servidor e cliente. O Grpc.AspNetCore metapacote inclui uma referência a Grpc.Tools. Projetos de servidor podem adicionar Grpc.AspNetCore usando o Gerenciador de Pacotes no Visual Studio ou adicionando um <PackageReference> ao arquivo de projeto:

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

Os projetos do cliente devem fazer referência direta ao Grpc.Tools juntamente com os outros pacotes necessários para usar o cliente gRPC. O pacote de ferramentas não é necessário em tempo de execução, portanto, a dependência é marcada com 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>

Ativos C# gerados

O pacote de ferramentas gera os tipos C# que representam as mensagens definidas nos arquivos incluídos .proto .

Para ativos do lado do servidor, um tipo de base de serviço abstrato é gerado. O tipo base contém as definições de todas as chamadas gRPC contidas no .proto arquivo. Crie uma implementação de serviço concreta que derive desse tipo base e implemente a lógica para as chamadas gRPC. Para o greet.proto, o exemplo descrito anteriormente, um tipo abstrato GreeterBase que contém um método virtual SayHello é gerado. Uma implementação GreeterService concreta substitui o método e implementa a lógica que manipula a chamada 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
        });
    }
}

Para ativos do lado do cliente, um tipo de cliente concreto é gerado. As chamadas gRPC no ficheiro .proto são traduzidas em métodos no tipo concreto, que podem ser chamados. Para o greet.proto, o exemplo descrito anteriormente, um tipo concreto GreeterClient é gerado. Ligue para GreeterClient.SayHelloAsync para iniciar uma chamada gRPC com o servidor.

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

Por padrão, os ativos de servidor e cliente são gerados para cada .proto arquivo incluído no grupo de <Protobuf> itens. Para garantir que apenas os ativos de servidor sejam gerados em um projeto de servidor, o GrpcServices atributo é definido como Server.

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

Da mesma forma, o atributo é definido como Client em projetos cliente.

Recursos adicionais

• Visão geral do gRPC no .NET
• Criar um cliente e um servidor gRPC .NET no ASP.NET Core
• serviços gRPC com ASP.NET Core
• Chamar Serviços gRPC com o Cliente .NET