Compartilhar via

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

  • Artigo

Este tutorial mostra como criar um cliente gRPC do .NET Core e um servidor gRPC do ASP.NET Core. No final, você terá um cliente gRPC que se comunica com o serviço de Boas-vindas do gRPC.

Neste tutorial, você:

  • Criará um servidor gRPC.
  • Criará um cliente gRPC.
  • Testar o cliente gRPC com o serviço de Boas-vindas do gRPC.

Pré-requisitos

Criar um serviço gRPC

  • Inicie o Visual Studio 2022 e selecione Novo Projeto.
  • Na caixa de diálogo Criar um novo projeto, faça a busca por gRPC. Selecione Serviço gRPC ASP.NET Core e selecione Avançar.
  • Na caixa de diálogo Configurar seu novo projeto, insira GrpcGreeter no Nome do projeto. É importante nomear o projeto GrpcGreeter de modo que os namespaces façam a correspondência quando você copiar e colar o código.
  • Selecione Avançar.
  • Na caixa de diálogo Informações adicionais, selecione .NET 8.0 (suporte de longo prazo) e, a seguir, selecione Criar.

Executar o serviço

  • Pressione Ctrl + F5 para execução sem o depurador.

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

    Este projeto está configurado para usar SSL. para evitar avisos de SSL no navegador, você pode optar por confiar no certificado autoassinado que o IIS Express gerou. Gostaria de confiar no certificado SSL do IIS Express?

    Selecione Sim se você confia no certificado SSL do IIS Express.

    A seguinte caixa de diálogo é exibida:

    Caixa de diálogo de aviso de segurança

    Selecione Sim se você concordar com confiar no certificado de desenvolvimento.

    Para obter informações sobre como confiar no navegador Firefox, confira Erro de certificado Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

    Visual Studio:

    • Inicia o servidor Kestrel.
    • Inicia um navegador.
    • Navega para http://localhost:port, como por exemplo http://localhost:7042.
      • portz: um número de porta atribuído aleatoriamente para o aplicativo.
      • localhost: o nome do host padrão de seu computador local. Localhost serve somente solicitações da Web do computador local.

Os logs mostram o serviço escutando em https://localhost:<port>, em que <port> é o número da porta localhost atribuído aleatoriamente quando o projeto é criado 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

Observação

O modelo gRPC é configurado para usar o protocolo TLS. 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 definido no arquivo Properties\launchSettings.json do projeto de serviço gRPC.

Examinar os arquivos de projeto

Arquivos de projeto GrpcGreeter:

  • Protos/greet.proto: define o gRPC de Greeter e é usado para gerar os ativos do servidor gRPC. Para obter mais informações, confira Introdução ao gRPC.
  • Pasta Services: 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:

Criar o cliente gRPC em um aplicativo de console .NET

  • 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 Avançar.
  • Na caixa de texto Nome do projeto, digite GrpcGreeterClient e selecione Avançar.
  • No diálogo Informações adicionais, selecione .NET 8.0 (Suporte de longo prazo) e escolha Criar.

Adicionar os pacotes NuGet necessários

O projeto do cliente gRPC requer os seguintes pacotes NuGet:

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

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

Opção do PMC para instalar pacotes

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

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

  • 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 mouse no projeto em Gerenciador de Soluções>Gerenciar Pacotes NuGet.
  • Selecione a guia Procurar.
  • Insira 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.

Adicionar greet.proto

  • Crie uma pasta Protos no projeto do cliente gRPC.

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

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

    option csharp_namespace = "GrpcGreeterClient";

  • Edite o arquivo de projeto GrpcGreeterClient.csproj:

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

  • Adicione um grupo de itens com um elemento <Protobuf> que faça referência ao arquivo greet.proto:

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

Criar o cliente Greeter

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

Observação

Os tipos GrpcGreeterClient são gerados automaticamente pelo processo de build. 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 do 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, confira Serviços gRPC com C#: ativos C# gerados.

  • Atualize o cliente gRPC Program.cs com o seguinte código.

    using System.Threading.Tasks;
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 localhost 7042 pelo número da porta HTTPS especificado em Properties/launchSettings.json no 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 da seguinte forma:

  • Criando uma instância de GrpcChannel que contém as informações para criar a conexão com o serviço gRPC.
  • Como usar 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 SayHello assíncrono. O resultado da chamada SayHello é 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();

Testar o cliente gRPC com o serviço de Boas-vindas do gRPC

Atualize o arquivo appsettings.Development.json adicionando as seguintes linhas em destaque:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
      ,"Microsoft.AspNetCore.Hosting": "Information",
      "Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"
    }
  }
}
  • No serviço Greeter, pressione Ctrl+F5 para iniciar o servidor sem o depurador.
  • No projeto GrpcGreeterClient, pressione Ctrl+F5 para iniciar o cliente sem o depurador.

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

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

O serviço gRPC registra os detalhes da chamada bem-sucedida nos logs gravados no prompt de comando:

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 in 78.32260000000001ms 200 application/grpc

Observação

O código neste artigo requer o certificado de desenvolvimento HTTPS do ASP.NET Core para proteger o serviço gRPC. Se houver falha no cliente gRPC e for exibida 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 será confiável. Para consertar esse problema, consulte Chamar um serviço gRPC com um certificado não confiável/inválido.

Próximas etapas

Este tutorial mostra como criar um cliente gRPC do .NET Core e um servidor gRPC do ASP.NET Core. No final, você terá um cliente gRPC que se comunica com o serviço de Boas-vindas do gRPC.

Neste tutorial, você:

  • Criará um servidor gRPC.
  • Criará um cliente gRPC.
  • Testar o cliente gRPC com o serviço de Boas-vindas do gRPC.

Pré-requisitos

Criar um serviço gRPC

  • Inicie o Visual Studio 2022 e selecione Criar um novo projeto.
  • Na caixa de diálogo Criar um novo projeto, faça a busca por gRPC. Selecione Serviço gRPC ASP.NET Core e selecione Avançar.
  • Na caixa de diálogo Configurar seu novo projeto, insira GrpcGreeter no Nome do projeto. É importante nomear o projeto GrpcGreeter de modo que os namespaces façam a correspondência quando você copiar e colar o código.
  • Selecione Avançar.
  • No diálogo Informações adicionais, selecione .NET 6.0 (Suporte de longo prazo) e escolha Criar.

Executar o serviço

  • Pressione Ctrl + F5 para execução sem o depurador.

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

    Este projeto está configurado para usar SSL. para evitar avisos de SSL no navegador, você pode optar por confiar no certificado autoassinado que o IIS Express gerou. Gostaria de confiar no certificado SSL do IIS Express?

    Selecione Sim se você confia no certificado SSL do IIS Express.

    A seguinte caixa de diálogo é exibida:

    Caixa de diálogo de aviso de segurança

    Selecione Sim se você concordar com confiar no certificado de desenvolvimento.

    Para obter informações sobre como confiar no navegador Firefox, confira Erro de certificado Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

    Visual Studio:

    • Inicia o servidor Kestrel.
    • Inicia um navegador.
    • Navega para http://localhost:port, como por exemplo http://localhost:7042.
      • portz: um número de porta atribuído aleatoriamente para o aplicativo.
      • localhost: o nome do host padrão de seu computador local. Localhost serve somente solicitações da Web do computador local.

Os logs mostram o serviço escutando em https://localhost:<port>, em que <port> é o número da porta localhost atribuído aleatoriamente quando o projeto é criado 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

Observação

O modelo gRPC é configurado para usar o protocolo TLS. 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 definido no arquivo Properties\launchSettings.json do projeto de serviço gRPC.

O macOS não é compatível com gRPC do ASP.NET Core com TLS. É necessária uma configuração adicional para executar com êxito os serviços gRPC no macOS. Para obter mais informações, confira Não é possível iniciar o aplicativo ASP.NET Core gRPC no macOS.

Examinar os arquivos de projeto

Arquivos de projeto GrpcGreeter:

  • Protos/greet.proto: define o gRPC de Greeter e é usado para gerar os ativos do servidor gRPC. Para obter mais informações, confira Introdução ao gRPC.
  • Pasta Services: 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:

Criar o cliente gRPC em um aplicativo de console .NET

  • Abra uma segunda instância do Visual Studio e selecione Criar um novo projeto.
  • Na caixa de diálogo Criar um novo projeto, selecione Aplicativo de Console e Avançar.
  • Na caixa de texto Nome do projeto, digite GrpcGreeterClient e selecione Avançar.
  • No diálogo Informações adicionais, selecione .NET 6.0 (Suporte de longo prazo) e escolha Criar.

Adicionar os pacotes NuGet necessários

O projeto do cliente gRPC requer os seguintes pacotes NuGet:

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

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

Opção do PMC para instalar pacotes

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

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

  • 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 mouse no projeto em Gerenciador de Soluções>Gerenciar Pacotes NuGet.
  • Selecione a guia Procurar.
  • Insira 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.

Adicionar greet.proto

  • Crie uma pasta Protos no projeto do cliente gRPC.

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

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

    option csharp_namespace = "GrpcGreeterClient";

  • Edite o arquivo de projeto GrpcGreeterClient.csproj:

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

  • Adicione um grupo de itens com um elemento <Protobuf> que faça referência ao arquivo greet.proto:

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

Criar o cliente Greeter

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

Observação

Os tipos GrpcGreeterClient são gerados automaticamente pelo processo de build. 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 do 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, confira Serviços gRPC com C#: ativos C# gerados.

  • Atualize o cliente gRPC Program.cs com o seguinte código.

    using System.Threading.Tasks;
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 localhost 7042 pelo número da porta HTTPS especificado em Properties/launchSettings.json no 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 da seguinte forma:

  • Criando uma instância de GrpcChannel que contém as informações para criar a conexão com o serviço gRPC.
  • Como usar 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 SayHello assíncrono. O resultado da chamada SayHello é 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();

Testar o cliente gRPC com o serviço de Boas-vindas do gRPC

Atualize o arquivo appsettings.Development.json adicionando as seguintes linhas em destaque:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
      ,"Microsoft.AspNetCore.Hosting": "Information",
      "Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"
    }
  }
}
  • No serviço Greeter, pressione Ctrl+F5 para iniciar o servidor sem o depurador.
  • No projeto GrpcGreeterClient, pressione Ctrl+F5 para iniciar o cliente sem o depurador.

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

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

O serviço gRPC registra os detalhes da chamada bem-sucedida nos logs gravados no prompt de comando:

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 in 78.32260000000001ms 200 application/grpc

Observação

O código neste artigo requer o certificado de desenvolvimento HTTPS do ASP.NET Core para proteger o serviço gRPC. Se houver falha no cliente gRPC e for exibida 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 será confiável. Para consertar esse problema, consulte Chamar um serviço gRPC com um certificado não confiável/inválido.

Próximas etapas

Este tutorial mostra como criar um cliente gRPC do .NET Core e um servidor gRPC do ASP.NET Core. No final, você terá um cliente gRPC que se comunica com o serviço de Boas-vindas do gRPC.

Neste tutorial, você:

  • Criará um servidor gRPC.
  • Criará um cliente gRPC.
  • Testar o cliente gRPC com o serviço de Boas-vindas do gRPC.

Pré-requisitos

Criar um serviço gRPC

  • Inicie o Visual Studio 2022 e selecione Criar um novo projeto.
  • Na caixa de diálogo Criar um novo projeto, faça a busca por gRPC. Selecione Serviço gRPC ASP.NET Core e selecione Avançar.
  • Na caixa de diálogo Configurar seu novo projeto, insira GrpcGreeter no Nome do projeto. É importante nomear o projeto GrpcGreeter de modo que os namespaces façam a correspondência quando você copiar e colar o código.
  • Selecione Avançar.
  • No diálogo Informações adicionais, selecione .NET 6.0 (Suporte de longo prazo) e escolha Criar.

Executar o serviço

  • Pressione Ctrl + F5 para execução sem o depurador.

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

    Este projeto está configurado para usar SSL. para evitar avisos de SSL no navegador, você pode optar por confiar no certificado autoassinado que o IIS Express gerou. Gostaria de confiar no certificado SSL do IIS Express?

    Selecione Sim se você confia no certificado SSL do IIS Express.

    A seguinte caixa de diálogo é exibida:

    Caixa de diálogo de aviso de segurança

    Selecione Sim se você concordar com confiar no certificado de desenvolvimento.

    Para obter informações sobre como confiar no navegador Firefox, confira Erro de certificado Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

    Visual Studio:

    • Inicia o servidor Kestrel.
    • Inicia um navegador.
    • Navega para http://localhost:port, como por exemplo http://localhost:7042.
      • portz: um número de porta atribuído aleatoriamente para o aplicativo.
      • localhost: o nome do host padrão de seu computador local. Localhost serve somente solicitações da Web do computador local.

Os logs mostram o serviço escutando em https://localhost:<port>, em que <port> é o número da porta localhost atribuído aleatoriamente quando o projeto é criado 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

Observação

O modelo gRPC é configurado para usar o protocolo TLS. 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 definido no arquivo Properties\launchSettings.json do projeto de serviço gRPC.

O macOS não é compatível com gRPC do ASP.NET Core com TLS. É necessária uma configuração adicional para executar com êxito os serviços gRPC no macOS. Para obter mais informações, confira Não é possível iniciar o aplicativo ASP.NET Core gRPC no macOS.

Examinar os arquivos de projeto

Arquivos de projeto GrpcGreeter:

  • Protos/greet.proto: define o gRPC de Greeter e é usado para gerar os ativos do servidor gRPC. Para obter mais informações, confira Introdução ao gRPC.
  • Pasta Services: 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:

Criar o cliente gRPC em um aplicativo de console .NET

  • Abra uma segunda instância do Visual Studio e selecione Criar um novo projeto.
  • Na caixa de diálogo Criar um novo projeto, selecione Aplicativo de Console e Avançar.
  • Na caixa de texto Nome do projeto, digite GrpcGreeterClient e selecione Avançar.
  • No diálogo Informações adicionais, selecione .NET 6.0 (Suporte de longo prazo) e escolha Criar.

Adicionar os pacotes NuGet necessários

O projeto do cliente gRPC requer os seguintes pacotes NuGet:

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

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

Opção do PMC para instalar pacotes

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

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

  • 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 mouse no projeto em Gerenciador de Soluções>Gerenciar Pacotes NuGet.
  • Selecione a guia Procurar.
  • Insira 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.

Adicionar greet.proto

  • Crie uma pasta Protos no projeto do cliente gRPC.

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

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

    option csharp_namespace = "GrpcGreeterClient";

  • Edite o arquivo de projeto GrpcGreeterClient.csproj:

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

  • Adicione um grupo de itens com um elemento <Protobuf> que faça referência ao arquivo greet.proto:

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

Criar o cliente Greeter

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

Observação

Os tipos GrpcGreeterClient são gerados automaticamente pelo processo de build. 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 do 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, confira Serviços gRPC com C#: ativos C# gerados.

  • Atualize o cliente gRPC Program.cs com o seguinte código.

    using System.Threading.Tasks;
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 localhost 7042 pelo número da porta HTTPS especificado em Properties/launchSettings.json no 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 da seguinte forma:

  • Criando uma instância de GrpcChannel que contém as informações para criar a conexão com o serviço gRPC.
  • Como usar 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 SayHello assíncrono. O resultado da chamada SayHello é 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();

Testar o cliente gRPC com o serviço de Boas-vindas do gRPC

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

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

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

O serviço gRPC registra os detalhes da chamada bem-sucedida nos logs gravados no prompt de comando:

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 in 78.32260000000001ms 200 application/grpc

Atualize o arquivo appsettings.Development.json adicionando as linhas a seguir:

"Microsoft.AspNetCore.Hosting": "Information",
"Microsoft.AspNetCore.Routing.EndpointMiddleware": "Information"

Observação

O código neste artigo requer o certificado de desenvolvimento HTTPS do ASP.NET Core para proteger o serviço gRPC. Se houver falha no cliente gRPC e for exibida 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 será confiável. Para consertar esse problema, consulte Chamar um serviço gRPC com um certificado não confiável/inválido.

Próximas etapas

Este tutorial mostra como criar um cliente gRPC do .NET Core e um servidor gRPC do ASP.NET Core.

No final, você terá um cliente gRPC que se comunica com o serviço de Boas-vindas do gRPC.

Exibir ou baixar um código de exemplo (como baixar).

Neste tutorial, você:

  • Criará um servidor gRPC.
  • Criará um cliente gRPC.
  • Testar o cliente gRPC com o serviço de Boas-vindas do gRPC.

Pré-requisitos

Criar um serviço gRPC

  • Inicie o Visual Studio e selecione Criar um novo projeto.
  • Na caixa de diálogo Criar um novo projeto, selecione Serviço gPRC e selecione Avançar.
  • Na caixa de diálogo Configurar seu novo projeto, insira GrpcGreeter no Nome do projeto. É importante nomear o projeto GrpcGreeter de modo que os namespaces façam a correspondência quando você copiar e colar o código.
  • Selecione Avançar.
  • Na página Informações adicionais, selecione .NET 5.0 na lista suspensa Estrutura de Destino.
  • Selecione Criar.

Executar o serviço

  • Pressione Ctrl + F5 para execução sem o depurador.

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

    Este projeto está configurado para usar SSL. para evitar avisos de SSL no navegador, você pode optar por confiar no certificado autoassinado que o IIS Express gerou. Gostaria de confiar no certificado SSL do IIS Express?

    Selecione Sim se você confia no certificado SSL do IIS Express.

    A seguinte caixa de diálogo é exibida:

    Caixa de diálogo de aviso de segurança

    Selecione Sim se você concordar com confiar no certificado de desenvolvimento.

    Para obter informações sobre como confiar no navegador Firefox, confira Erro de certificado Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

    O Visual Studio inicia o IIS Express e executa o aplicativo. A barra de endereços mostra localhost:port# e não algo como example.com. Isso ocorre porque localhost é o nome do host padrão do computador local. Localhost serve somente solicitações da Web do computador local. Quando o Visual Studio cria um projeto Web, uma porta aleatória é usada para o servidor Web.

Os logs mostram o serviço escutando em https://localhost:5001.

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

Observação

O modelo gRPC é configurado para usar o protocolo TLS. Os clientes gRPC precisam usar HTTPS para chamar o servidor.

O macOS não é compatível com gRPC do ASP.NET Core com TLS. É necessária uma configuração adicional para executar com êxito os serviços gRPC no macOS. Para obter mais informações, confira Não é possível iniciar o aplicativo ASP.NET Core gRPC no macOS.

Examinar os arquivos de projeto

Arquivos de projeto GrpcGreeter:

  • greet.proto: o arquivo Protos/greet.proto define o gRPC de Greeter e é usado para gerar os ativos do servidor gRPC. Para obter mais informações, confira Introdução ao gRPC.
  • Pasta de Serviços: 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: contém o ponto de entrada para o serviço gRPC. Para saber mais, confira Host Genérico .NET no ASP.NET Core.
  • Startup.cs: contém o código que configura o comportamento do aplicativo. Para obter mais informações, veja Inicialização do aplicativo.

Criar o cliente gRPC em um aplicativo de console .NET

  • Abra uma segunda instância do Visual Studio e selecione Criar um novo projeto.
  • Na caixa de diálogo Criar um novo projeto, selecione Aplicativo de Console (.NET Core) e Avançar.
  • Na caixa de texto Nome do projeto, digite GrpcGreeterClient e selecione Criar.

Adicionar os pacotes necessários

O projeto cliente gRPC requer os seguintes pacotes:

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

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

Opção do PMC para instalar pacotes

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

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

  • 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 mouse no projeto em Gerenciador de Soluções>Gerenciar Pacotes NuGet.
  • Selecione a guia Procurar.
  • Insira 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.

Adicionar greet.proto

  • Crie uma pasta Protos no projeto do cliente gRPC.

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

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

    option csharp_namespace = "GrpcGreeterClient";

  • Edite o arquivo de projeto GrpcGreeterClient.csproj:

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

  • Adicione um grupo de itens com um elemento <Protobuf> que faça referência ao arquivo greet.proto:

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

Criar o cliente Greeter

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

Observação

Os tipos GrpcGreeterClient são gerados automaticamente pelo processo de build. 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 do 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, confira Serviços gRPC com C#: ativos C# gerados.

  • Atualize o cliente gRPC Program.cs com o seguinte código:

    using System;
using System.Net.Http;
using System.Threading.Tasks;
using Grpc.Net.Client;

namespace GrpcGreeterClient
{
    class Program
    {
        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();
        }
    }
}

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

O cliente Greeter é criado da seguinte forma:

  • Criando uma instância de GrpcChannel que contém as informações para criar a conexão com o serviço gRPC.
  • Como usar o GrpcChannel para construir o cliente Greeter:
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();
}

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

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

Testar o cliente gRPC com o serviço de Boas-vindas do gRPC

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

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

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

O serviço gRPC registra os detalhes da chamada bem-sucedida nos logs gravados no prompt de comando:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:5001/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 in 78.32260000000001ms 200 application/grpc

Observação

O código neste artigo requer o certificado de desenvolvimento HTTPS do ASP.NET Core para proteger o serviço gRPC. Se houver falha no cliente gRPC e for exibida 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 será confiável. Para consertar esse problema, consulte Chamar um serviço gRPC com um certificado não confiável/inválido.

Próximas etapas

Este tutorial mostra como criar um cliente gRPC do .NET Core e um servidor gRPC do ASP.NET Core.

No final, você terá um cliente gRPC que se comunica com o serviço de Boas-vindas do gRPC.

Exibir ou baixar um código de exemplo (como baixar).

Neste tutorial, você:

  • Criará um servidor gRPC.
  • Criará um cliente gRPC.
  • Testar o cliente gRPC com o serviço de Boas-vindas do gRPC.

Pré-requisitos

Criar um serviço gRPC

  • Inicie o Visual Studio e selecione Criar um novo projeto. Como alternativa, no menu Arquivo do Visual Studio, selecione Novo>Projeto.

  • Na caixa de diálogo Criar um novo projeto, selecione o Serviço gPRC e selecione Avançar:

    Criar uma nova caixa de diálogo de projeto no Visual Studio

  • Nomeie o projeto GrpcGreeter. É importante nomear o projeto GrpcGreeter de modo que os namespaces façam a correspondência quando você copiar e colar o código.

  • Selecione Criar.

  • Na caixa de diálogo Criar um novo serviço gRPC:

    • O modelo de Serviço gRPC está selecionado.
    • Selecione Criar.

Executar o serviço

  • Pressione Ctrl + F5 para execução sem o depurador.

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

    Este projeto está configurado para usar SSL. para evitar avisos de SSL no navegador, você pode optar por confiar no certificado autoassinado que o IIS Express gerou. Gostaria de confiar no certificado SSL do IIS Express?

    Selecione Sim se você confia no certificado SSL do IIS Express.

    A seguinte caixa de diálogo é exibida:

    Caixa de diálogo de aviso de segurança

    Selecione Sim se você concordar com confiar no certificado de desenvolvimento.

    Para obter informações sobre como confiar no navegador Firefox, confira Erro de certificado Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

    O Visual Studio inicia o IIS Express e executa o aplicativo. A barra de endereços mostra localhost:port# e não algo como example.com. Isso ocorre porque localhost é o nome do host padrão do computador local. Localhost serve somente solicitações da Web do computador local. Quando o Visual Studio cria um projeto Web, uma porta aleatória é usada para o servidor Web.

Os logs mostram o serviço escutando em https://localhost:5001.

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

Observação

O modelo gRPC é configurado para usar o protocolo TLS. Os clientes gRPC precisam usar HTTPS para chamar o servidor.

O macOS não é compatível com gRPC do ASP.NET Core com TLS. É necessária uma configuração adicional para executar com êxito os serviços gRPC no macOS. Para obter mais informações, confira Não é possível iniciar o aplicativo ASP.NET Core gRPC no macOS.

Examinar os arquivos de projeto

Arquivos de projeto GrpcGreeter:

  • greet.proto: o arquivo Protos/greet.proto define o gRPC de Greeter e é usado para gerar os ativos do servidor gRPC. Para obter mais informações, confira Introdução ao gRPC.
  • Pasta de Serviços: 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: contém o ponto de entrada para o serviço gRPC. Para saber mais, confira Host Genérico .NET no ASP.NET Core.
  • Startup.cs: contém o código que configura o comportamento do aplicativo. Para obter mais informações, veja Inicialização do aplicativo.

Criar o cliente gRPC em um aplicativo de console .NET

  • Abra uma segunda instância do Visual Studio e selecione Criar um novo projeto.
  • Na caixa de diálogo Criar um novo projeto, selecione Aplicativo de Console (.NET Core) e Avançar.
  • Na caixa de texto Nome do projeto, digite GrpcGreeterClient e selecione Criar.

Adicionar os pacotes necessários

O projeto cliente gRPC requer os seguintes pacotes:

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

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

Opção do PMC para instalar pacotes

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

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

  • 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 mouse no projeto em Gerenciador de Soluções>Gerenciar Pacotes NuGet.
  • Selecione a guia Procurar.
  • Insira 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.

Adicionar greet.proto

  • Crie uma pasta Protos no projeto do cliente gRPC.

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

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

    option csharp_namespace = "GrpcGreeterClient";

  • Edite o arquivo de projeto GrpcGreeterClient.csproj:

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

  • Adicione um grupo de itens com um elemento <Protobuf> que faça referência ao arquivo greet.proto:

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

Criar o cliente Greeter

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

Observação

Os tipos GrpcGreeterClient são gerados automaticamente pelo processo de build. 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 do 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, confira Serviços gRPC com C#: ativos C# gerados.

Atualize o cliente gRPC Program.cs com o seguinte código:

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Grpc.Net.Client;

namespace GrpcGreeterClient
{
    class Program
    {
        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();
        }
    }
}

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

O cliente Greeter é criado da seguinte forma:

  • Criando uma instância de GrpcChannel que contém as informações para criar a conexão com o serviço gRPC.
  • Como usar o GrpcChannel para construir o cliente Greeter:
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();
}

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

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

Testar o cliente gRPC com o serviço de Boas-vindas do gRPC

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

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

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

O serviço gRPC registra os detalhes da chamada bem-sucedida nos logs gravados no prompt de comando:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:5001/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 in 78.32260000000001ms 200 application/grpc

Observação

O código neste artigo requer o certificado de desenvolvimento HTTPS do ASP.NET Core para proteger o serviço gRPC. Se houver falha no cliente gRPC e for exibida 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 será confiável. Para consertar esse problema, consulte Chamar um serviço gRPC com um certificado não confiável/inválido.

Próximas etapas