Tutorial: Criar um cliente e um servidor gRPC no ASP.NET Core

Este tutorial mostra como criar um cliente gRPC .NET e um ASP.NET Core gRPC Server. No final, você terá um cliente gRPC que se comunica com o serviço gRPC Greeter.

Neste tutorial, você:

• Crie um servidor gRPC.
• Crie um cliente gRPC.
• Teste o cliente gRPC com o serviço gRPC Greeter.

Prerequisites

Estúdio Visual

• Visual Studio 2022 com a carga de trabalho de ASP.NET e desenvolvimento web .

  

Código do Visual Studio

• Código do Visual Studio
• Kit de desenvolvimento em C# para código do Visual Studio
• SDK do .NET 9

Você pode seguir as instruções do Visual Studio Code no macOS, Linux ou Windows. Alterações podem ser necessárias se você usar um ambiente de desenvolvimento integrado (IDE) diferente do Visual Studio Code.

Criar um serviço gRPC

Estúdio Visual

• Inicie o Visual Studio 2022 e selecione Novo projeto.
• Na caixa de diálogo Criar um novo projeto , procure gRPC. Selecione ASP.NET Serviço gRPC principal e selecione Avançar.
• Na caixa de diálogo Configurar o novo projeto, digite GrpcGreeter para nome do projeto. É importante nomear o projeto GrpcGreeter para que os namespaces correspondam quando você copia e cola o código.
• Selecione Avançar.
• Na caixa de diálogo Informações adicionais , selecione .NET 9.0 (Suporte de Termo Padrão) e, em seguida, selecione Criar.

Código do Visual Studio

O tutorial pressupõe familiaridade com o VS Code. Para obter mais informações, consulte Introdução ao VS Code.

• Selecione Novo Terminal no menu Terminal para abrir o terminal integrado.

• Mude para o diretório (cd) que conterá o projeto.

• Execute os seguintes comandos:

  dotnet new grpc -o GrpcGreeter
  code -r GrpcGreeter
  

  O dotnet new comando cria um novo serviço gRPC na pasta GrpcGreeter .

  O code comando abre a pasta do projeto GrpcGreeter na instância atual do Visual Studio Code.

Visual Studio Code pode exibir uma caixa de diálogo que pergunta: Você confia nos autores dos arquivos nesta pasta?

• Se você confiar em todos os arquivos na pasta pai, selecione Confiar nos autores de todos os arquivos na pasta pai.
• Selecione Sim, confio nos autores, pois a pasta do projeto tem arquivos gerados pelo .NET.
• Quando o Visual Studio Code solicitar que adicione elementos para compilar e depurar o projeto, selecione Sim. Se o Visual Studio Code não oferecer a opção de adicionar ativos de compilação e depuração, selecione Exibir>Paleta de Comandos e digite ".NET" na caixa de pesquisa. Na lista de comandos, selecione o comando .NET: Generate Assets for Build and Debug.

O Visual Studio Code adiciona uma pasta .vscode com arquivos launch.json e tasks.json gerados.

Executar o serviço

Estúdio Visual

• Pressione Ctrl+F5 para executar sem o depurador.

  Visual Studio exibe a seguinte caixa de diálogo quando um projeto ainda não está configurado para usar SSL:

  

  Selecione Sim se confiar no certificado SSL do IIS Express.

  A seguinte caixa de diálogo é exibida:

  

  Selecione Sim se concordar em confiar no certificado de desenvolvimento.

  Para obter informações sobre como confiar no navegador Firefox, consulte o erro de certificado SEC_ERROR_INADEQUATE_KEY_USAGE do Firefox na secção .

  Visual Studio:

  • Inicia o servidor Kestrel.
  • Inicia um navegador.
  • Navega até http://localhost:port, tal como http://localhost:7042.
    • port: um número de porta atribuído aleatoriamente para o aplicativo.
    • localhost: O nome de host padrão para o computador local. Localhost atende apenas solicitações da Web do computador local.

Código do Visual Studio

• Confie no certificado de desenvolvimento HTTPS executando o seguinte comando:

  dotnet dev-certs https --trust
  

  O comando anterior exibe a seguinte caixa de diálogo, desde que o certificado não seja confiável anteriormente:

  

• Selecione Sim se concordar em confiar no certificado de desenvolvimento.

  Para obter mais informações, consulte a seção Aplicação de SSL do artigo Confiança no certificado de desenvolvimento HTTPS do ASP.NET Core.

Para obter informações sobre como confiar no navegador Firefox, consulte o erro de certificado SEC_ERROR_INADEQUATE_KEY_USAGE do Firefox na secção .

• Pressione Ctrl-F5 para executar sem o depurador.

  Código do Visual Studio:

  • Inicia o servidor Kestrel.
  • Inicia um navegador.
  • Navega até http://localhost:port, tal como http://localhost:7042.
    • port: um número de porta atribuído aleatoriamente para o aplicativo.
    • localhost: O nome de host padrão para o computador local. Localhost atende apenas solicitações da Web do computador local.

Os registos mostram o serviço a escutar em https://localhost:<port>, onde <port> é o número da porta localhost atribuído aleatoriamente no momento da criação do projeto e definido em Properties/launchSettings.json.

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:<port>
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

Note

O modelo gRPC está configurado para usar TLS (Transport Layer Security). Os clientes gRPC precisam usar HTTPS para chamar o servidor. O número da porta localhost do serviço gRPC é atribuído aleatoriamente quando o projeto é criado e configurado no arquivo Propriedades\launchSettings.js do projeto de serviço gRPC.

Examinar os arquivos do projeto

GrpcGreeter arquivos de projeto:

• Protos/greet.proto: define o Greeter gRPC e é usado para gerar os ativos do servidor gRPC. Para obter mais informações, consulte Introdução ao gRPC.
• Services pasta: Contém a implementação do serviço Greeter.
• appSettings.json: Contém dados de configuração, como o protocolo usado pelo Kestrel. Para obter mais informações, consulte Configuração no ASP.NET Core.
• Program.cs, que contém:
  • O ponto de entrada para o serviço gRPC. Para mais informações, consulte o Host Genérico do .NET no ASP.NET Core.
  • Código que configura o comportamento do aplicativo. Para obter mais informações, consulte Inicialização do aplicativo.

Criar o cliente gRPC em um aplicativo de console .NET

Estúdio Visual

• Abra uma segunda instância do Visual Studio e selecione Novo projeto.
• Na caixa de diálogo Criar um novo projeto , selecione Aplicativo de console e selecione Avançar.
• Na caixa de texto Nome do projeto , digite GrpcGreeterClient e selecione Avançar.
• Na caixa de diálogo Informações adicionais , selecione .NET 9.0 (Suporte de Termo Padrão) e, em seguida, selecione Criar.

Código do Visual Studio

• Abra o terminal integrado .

• Altere diretórios (cd) para uma pasta para o projeto.

• Execute os seguintes comandos:

  dotnet new console -o GrpcGreeterClient
  code -r GrpcGreeterClient
  

Visual Studio Code pode exibir uma caixa de diálogo que pergunta: Você confia nos autores dos arquivos nesta pasta?

• Se você confiar em todos os arquivos na pasta pai, selecione Confiar nos autores de todos os arquivos na pasta pai.
• Selecione Sim, confio nos autores, pois a pasta do projeto tem arquivos gerados pelo .NET.
• Quando o Visual Studio Code solicitar que adicione elementos para compilar e depurar o projeto, selecione Sim. Se o Visual Studio Code não oferecer a opção de adicionar ativos de compilação e depuração, selecione Exibir>Paleta de Comandos e digite ".NET" na caixa de pesquisa. Na lista de comandos, selecione o comando .NET: Generate Assets for Build and Debug.

O Visual Studio Code adiciona uma pasta .vscode com arquivos launch.json e tasks.json gerados.

Adicionar pacotes NuGet necessários

O projeto de cliente gRPC requer os seguintes pacotes NuGet:

• Grpc.Net.Client, que contém o cliente .NET.
• Google.Protobuf, que contém APIs de mensagem protobuf para C#.
• Grpc.Tools, que contêm suporte a ferramentas C# para arquivos protobuf. O pacote de ferramentas não é necessário em tempo de execução, portanto, a dependência é marcada com PrivateAssets="All".

Estúdio Visual

Instale os pacotes usando o Console do Gerenciador de Pacotes (PMC) ou Gerenciar Pacotes NuGet.

Opção PMC para instalar pacotes

• No Visual Studio, selecione Ferramentas>NuGet Package Manager>Console do Gerenciador de Pacotes

• Na janela Console do Gerenciador de Pacotes , execute cd GrpcGreeterClient para alterar os diretórios para a pasta que contém os GrpcGreeterClient.csproj arquivos.

• Execute os seguintes comandos:

  Install-Package Grpc.Net.Client
  Install-Package Google.Protobuf
  Install-Package Grpc.Tools
  

Opção Gerenciar pacotes NuGet para instalar pacotes

• Clique com o botão direito do rato no projeto no Explorador de Soluções>Gerir Pacotes NuGet.
• Selecione a guia Procurar.
• Digite Grpc.Net.Client na caixa de pesquisa.
• Selecione o pacote Grpc.Net.Client na guia Procurar e selecione Instalar.
• Repita para Google.Protobuf e Grpc.Tools.

Código do Visual Studio

Execute os seguintes comandos a partir do Terminal Integrado:

dotnet add GrpcGreeterClient.csproj package Grpc.Net.Client
dotnet add GrpcGreeterClient.csproj package Google.Protobuf
dotnet add GrpcGreeterClient.csproj package Grpc.Tools

Adicionar greet.proto

• Crie uma pasta Protos no projeto de cliente gRPC.

• Copie o arquivo Protos\greet.proto do serviço gRPC Greeter para a pasta Protos no projeto de cliente gRPC.

• Atualize o namespace dentro do greet.proto arquivo para o namespace do projeto:

  option csharp_namespace = "GrpcGreeterClient";
  

• Edite o ficheiro do projeto GrpcGreeterClient.csproj.

Estúdio Visual

Clique com o botão direito do mouse no projeto e selecione Editar arquivo de projeto.

Código do Visual Studio

Selecione o arquivo GrpcGreeterClient.csproj.

• Adicione um grupo de itens com um <Protobuf> elemento que se refira ao arquivo greet.proto :

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

Criar o cliente Greeter

• Crie o projeto cliente para criar os tipos no GrpcGreeterClient namespace.

Note

Os GrpcGreeterClient tipos são gerados automaticamente pelo processo de compilação. O pacote de ferramentas Grpc.Tools gera os seguintes arquivos com base no arquivo greet.proto :

• GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\Greet.cs: O código de buffer de protocolo que preenche, serializa e recupera os tipos de mensagem de solicitação e resposta.
• GrpcGreeterClient\obj\Debug\[TARGET_FRAMEWORK]\Protos\GreetGrpc.cs: Contém as classes de cliente geradas.

Para obter mais informações sobre os ativos C# gerados automaticamente pelo Grpc.Tools, consulte Serviços gRPC com C#: ativos C# gerados.

• Atualize o arquivo de cliente Program.cs gRPC com o código a seguir.

  using Grpc.Net.Client;
  using GrpcGreeterClient;
  
  // 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();
  

• No código realçado anterior, substitua o número da porta 7042 pelo número da porta HTTPS especificado em Properties/launchSettings.json dentro do projeto de serviço GrpcGreeter.

Program.cs contém o ponto de entrada e a lógica para o cliente gRPC.

O cliente Greeter é criado por:

• Instanciar um GrpcChannel que contém as informações para estabelecer a conexão com o serviço gRPC.
• Usando o GrpcChannel para construir o cliente Greeter:

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

O cliente Greeter chama o método assíncrono SayHello . O resultado da SayHello chamada é exibido:

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

Teste o cliente gRPC com o serviço gRPC Greeter

Atualize o appsettings.Development.json arquivo adicionando as seguintes linhas realçadas:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.AspNetCore.Hosting": "Information",
      "Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"
    }
  }
}

Estúdio Visual

• No projeto de serviço GrpcGreeter, pressione Ctrl+F5 para iniciar o servidor sem o depurador.
• No projeto de GrpcGreeterClient console, pressione Ctrl+F5 para iniciar o cliente sem o depurador.

Código do Visual Studio

• Inicie o serviço Greeter.
• Inicie o cliente.

O cliente envia uma saudação ao serviço com uma mensagem contendo seu nome, GreeterClient. O serviço envia a mensagem "Hello GreeterClient" como resposta. A resposta "Hello GreeterClient" é exibida no prompt de comando:

Greeting: Hello GreeterClient
Press any key to exit...

O serviço gRPC regista os detalhes da chamada bem-sucedida nos logs gravados na linha de comandos.

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:<port>
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\GH\aspnet\docs\4\Docs\aspnetcore\tutorials\grpc\grpc-start\sample\GrpcGreeter
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 POST https://localhost:<port>/greet.Greeter/SayHello application/grpc
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'gRPC - /greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'gRPC - /greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished HTTP/2 POST https://localhost:7042/greet.Greeter/SayHello - 200 - application/grpc 40.4615ms

Note

O código neste artigo requer o certificado de desenvolvimento HTTPS ASP.NET Core para proteger o serviço gRPC. Se o cliente gRPC do .NET falhar com a mensagem The remote certificate is invalid according to the validation procedure. ou The SSL connection could not be established., o certificado de desenvolvimento não é confiável. Para corrigir esse problema, consulte Chamar um serviço gRPC com um certificado não confiável/inválido.

Próximos passos

• Veja ou transfira o código de exemplo completo para este tutorial (como transferir).
• Visão geral do gRPC no .NET
• serviços gRPC com C#
• Migrar gRPC de C-core para gRPC para .NET