Como criar um serviço gRPC com C#

1. Visão geral

O gRPC é um framework e um conjunto de ferramentas de chamada de procedimento remoto (RPC) neutro em relação a linguagem e plataforma desenvolvido no Google. Ele permite definir um serviço usando buffers de protocolo, um conjunto de ferramentas e uma linguagem de serialização binária particularmente poderosos. Em seguida, é possível gerar stubs idiomáticos de cliente e servidor com base na definição do serviço em vários idiomas.

Neste codelab, você vai aprender a criar um serviço em C# que expõe uma API usando o framework gRPC. Você interage com esse serviço usando um cliente de console escrito em C# que usa a mesma descrição do serviço.

O que você vai aprender

  • A linguagem do buffer de protocolo.
  • Como implementar um serviço gRPC usando C#.
  • Como implementar um cliente gRPC usando C#.
  • Como atualizar um serviço gRPC.

O que é necessário

Como você usará este tutorial?

Apenas leitura Leitura e exercícios

Como você classificaria sua experiência com o Google Cloud Platform?

Iniciante Intermediário Proficiente

2. Fazer o download e criar exemplos do gRPC C#

Baixar amostras

Faça o download do repositório de amostra do gRPC C# como um arquivo zip e extraia-o.

Ou você pode clonar o repositório Git dele.

git clone https://github.com/meteatamel/grpc-samples-dotnet.git

De qualquer forma, você precisa ter uma pasta grpc-samples-dotnet com o seguinte conteúdo:

d056832ff4ce0c8f.png

Criar a solução

A pasta do aplicativo de exemplo contém GrpcSamples.sln, uma solução do Visual Studio. Clique duas vezes para abrir a solução no Visual Studio. Uma solução com vários projetos vai aparecer.

61da9ddc86c08019.png

Vamos analisar os projetos em mais detalhes na próxima seção, mas primeiro vamos criar o projeto. Acesse Build > Build Solution ou Ctrl + Shift + B para criar a solução. Isso vai baixar todas as dependências do NuGet e compilar o aplicativo.

No final, você vai ver uma mensagem Build succeeded na saída do console do Visual Studio.

3. Conheça o exemplo do Greeter

O Greeter é um exemplo simples de gRPC em que um cliente envia uma solicitação com um nome e o servidor responde com uma mensagem seguida do nome. Há um projeto Greeter que inclui a definição de serviço comum (arquivo proto) em que o cliente e o servidor se baseiam.

Projeto Greeter

Esse é o projeto comum compartilhado entre o cliente e o servidor. Ele tem um greeter.proto, que é a definição do serviço gRPC usada pelo cliente e pelo servidor. A definição de serviço define um serviço gRPC chamado GreetingService, que tem um método greeting que recebe HelloRequest como entrada e HelloResponse como saída.

service GreetingService {
    rpc greeting(HelloRequest) returns (HelloResponse);
}

Esse é um método unário (ou seja, sem streaming) em que o cliente envia uma única solicitação e recebe uma única resposta do servidor. Confira o restante do conteúdo de greeter.proto.. Esse projeto também tem um script chamado generate_protos.bat que pode ser usado para gerar stubs de cliente e servidor do arquivo proto. O projeto já contém stubs de cliente e servidor gerados, então não é necessário gerar os seus. No entanto, se você mudar algo no arquivo de definição de serviço, será necessário executar esse script para regenerar os stubs.

Servidor de saudação

Este é o projeto do servidor gRPC. Program.cs é o ponto de entrada principal em que a porta e a implementação do servidor são configuradas. A classe importante é GreeterServiceImpl.cs. Ele tem um método greeting em que a funcionalidade real é implementada.

public override Task<HelloResponse> greeting(HelloRequest request,
       ServerCallContext context)
{
    return Task.FromResult(new HelloResponse { 
          Greeting = "Hello " + request.Name });
}

Cliente de boas-vindas

Esse é o lado do cliente do serviço gRPC. Ele também tem Program.cs como ponto de entrada. Ele cria um canal para se comunicar com o servidor e, em seguida, cria um cliente com o canal do stub gerado. Em seguida, ele cria uma solicitação e a envia ao servidor usando o stub do cliente.

4. Executar a amostra do Greeter

Primeiro, inicie o servidor Greeter. Abra um prompt de comando, acesse a pasta bin > Debug do Greeter Server e execute o arquivo. O servidor vai ficar em espera.

> C:\grpc-samples-dotnet\GreeterServer\bin\Debug>GreeterServer.exe
GreeterServer listening on port 50051
Press any key to stop the server...

Em seguida, execute o cliente Greeter. Em um prompt de comando separado, acesse a pasta bin > Debug do Greeter Server e execute o arquivo executável. Você vai notar o cliente enviando a solicitação e recebendo uma resposta do servidor.

> C:\grpc-samples-dotnet\GreeterClient\bin\Debug>GreeterClient.exe
GreeterClient sending request
GreeterClient received response: Hello Mete - on C#
Press any key to exit...

5. Atualizar o exemplo do Greeter

Vamos ver como é atualizar nosso serviço. Adicione um novo método ao nosso serviço gRPC chamado "goodbye" que retorna "goodbye" em vez de "hello" ao cliente.

A primeira etapa é atualizar o arquivo de definição de serviço greeter.proto.

service GreetingService {
    rpc greeting(HelloRequest) returns (HelloResponse);
    
    rpc goodbye(HelloRequest) returns (HelloResponse);
}

Em seguida, você precisa gerar novamente os stubs de cliente e servidor. Em um prompt de comando, execute generate_protos.bat. Depois que os stubs forem gerados, talvez seja necessário atualizar seus projetos do Visual Studio para receber o código atualizado.

Por fim, atualize o código do cliente e do servidor para aproveitar o novo método. No serviço, atualize GreeterServiceImpl.cs e adicione um novo método goodbye.

public override Task<HelloResponse> goodbye(HelloRequest request,
       ServerCallContext context)
{
    return Task.FromResult(new HelloResponse { 
          Greeting = "Goodbye " + request.Name });
}

No cliente, faça uma chamada para o método goodbye em Program.cs..

response = client.goodbye(request);
Console.WriteLine("GreeterClient received response: " 
                       + response.Greeting);

Recompile o projeto e execute o servidor e o cliente novamente. O cliente vai receber uma mensagem de despedida.

> C:\grpc-samples-dotnet\GreeterClient\bin\Debug>GreeterClient.exe
GreeterClient sending request
GreeterClient received response: Hello Mete - on C#
GreeterClient received response: Goodbye Mete - on C#
Press any key to exit...

6. Conheça o exemplo de chat

Há também um projeto ChatServer e um ChatWindowsClient na solução. Como o nome sugere, este é um par de cliente e servidor para um aplicativo de chat simples. O projeto Chat tem o arquivo de definição de serviço chamado chat.proto. Ele define um ChatService com um método chat.

service ChatService {
 rpc chat(stream ChatMessage) returns (stream ChatMessageFromServer);
}

O importante aqui é que as mensagens de chat recebidas e enviadas são marcadas com a palavra-chave stream. Isso basicamente transforma a conexão em um stream bidirecional em que o cliente e o servidor podem enviar mensagens um ao outro a qualquer momento, a solução perfeita para um aplicativo de chat.

Você pode explorar mais o exemplo, criar e executar para ver como ele funciona como um exercício.

7. Parabéns!

O que vimos

  • A linguagem de buffer de protocolo.
  • Como implementar um serviço gRPC usando C#.
  • Como implementar um cliente gRPC usando C#.
  • Como atualizar um serviço gRPC.

Próximas etapas