Esta página foi traduzida pela API Cloud Translation.

Como criar um serviço gRPC com C#

1. Visão geral

gRPC é um framework e um conjunto de ferramentas de chamada de procedimento remoto (RPC) e linguagem neutras de plataformas desenvolvidas no Google. Ele permite que você defina um serviço usando buffers de protocolo, um conjunto de ferramentas e uma linguagem de serialização binária particularmente avançados. Em seguida, ele permite gerar stubs idiomáticos de clientes e servidores a partir da definição do serviço em várias linguagens.

Neste codelab, você 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 do 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

Um navegador, como o Chrome ou o Firefox.
Visual Studio 2013 ou mais recente instalado.
Familiaridade com o .NET Framework e a linguagem C#.

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 amostras do gRPC em C#

Fazer o download das amostras

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

Se preferir, clone o repositório git.

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

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

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. Você verá uma solução com vários projetos.

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

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

3. Conhecer o exemplo 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 pelo nome. Há um projeto Greeter que inclui a definição de serviço comum (arquivo proto) em que o cliente e o servidor são baseados.

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 que o cliente e o servidor usam. A definição do serviço define um serviço gRPC chamado GreetingService, que tem um método greeting que usa 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. É possível acessar 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 clientes e servidores a partir do arquivo proto. O projeto já contém stubs de cliente e servidor gerados para que você não precise gerá-los por conta própria. No entanto, se você alterar algo no arquivo de definição de serviço, precisará executar esse script para gerar novamente os stubs.

Servidor do Greeter

Este é o projeto para o servidor gRPC. Program.cs é o ponto de entrada principal em que a implementação da porta e do servidor está configurada. 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 da recepção

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

4. Executar o exemplo do Greeter

Primeiro, inicie o servidor Greeter. Abra um prompt de comando, navegue até a pasta bin > Debug do Greeter Server e execute o executável. Você verá o servidor detectando.

> 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, navegue até a pasta bin > Debug do Greeter Server e execute o executável. Você vai ver que o cliente está 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. Adicionar um novo método ao nosso serviço gRPC chamado "Goodbye" que retorna "adeus" em vez de "hello" para o cliente.

A primeira etapa é atualizar o arquivo de definição do 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, chame o método goodbye em Program.cs..

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

Recrie o projeto e execute o servidor e o cliente novamente. Agora 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. Conhecer o exemplo do Chat

Há também um projeto ChatServer e um ChatWindowsClient na solução. Como o nome sugere, ele é 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 sejam marcadas com a palavra-chave stream. Isso basicamente transforma a conexão em um fluxo bidirecional onde o cliente e o servidor podem enviar mensagens um para o outro a qualquer momento; a solução perfeita para um aplicativo de chat.

Você pode explorar ainda mais o exemplo, criá-lo e executá-lo para ver como ele funciona como um exercício.