Compartilhar via

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

Este tutorial mostra como criar um cliente gRPC do .NET e um ASP.NET Core gRPC Server. 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.

Prerequisites

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 para que os namespaces correspondam quando você copia e cola o código.
  • Selecione Próximo.
  • No diálogo Informações adicionais, selecione .NET 9.0 (Suporte a Termos Standard) 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.
      • porta: 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

Note

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 Propriedades\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 , insira GrpcGreeterClient e selecioneAvançar.
  • No diálogo Informações adicionais, selecione .NET 9.0 (Suporte a Termos Standard) 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 .NET.
  • Google.Protobuf, que contém APIs de mensagem protobuf para C#.
  • Grpc.Tools, que contém suporte a ferramentas em 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 comandos a seguir:

    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 no Gerenciador> de Soluçõespara Gerenciar Pacotes NuGet.
  • Selecione a guia Navegar.
  • 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 cliente gRPC.

  • Copie o arquivo Protos\greet.proto do serviço gRPC Greeter para a pasta Protos no projeto 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 <Protobuf> elemento que se refere 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.

Note

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 em C# gerados automaticamente pelo Grpc.Tools, consulte os serviços gRPC com C#: ativos C# gerados.

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

    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 projeto de serviços GrpcGreeter, pressione Ctrl+F5 para iniciar o servidor sem o depurador.
  • No projeto de console GrpcGreeterClient, pressione Ctrl+F5 para iniciar o cliente sem o depurador.

O cliente envia uma saudação ao 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 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 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 e um ASP.NET Core gRPC Server. 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.

Prerequisites

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 para que os namespaces correspondam quando você copia e cola o código.
  • Selecione Próximo.
  • Na caixa de diálogo Informações Adicionais , selecione .NET 8.0 (Suporte a Longo Prazo) e, em seguida, 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.
      • porta: 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

Note

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 Propriedades\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 , insira GrpcGreeterClient e selecioneAvançar.
  • Na caixa de diálogo Informações Adicionais , selecione .NET 8.0 (Suporte a Longo Prazo) e, em seguida, selecione 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 .NET.
  • Google.Protobuf, que contém APIs de mensagem protobuf para C#.
  • Grpc.Tools, que contém suporte a ferramentas em 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 comandos a seguir:

    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 no Gerenciador> de Soluçõespara Gerenciar Pacotes NuGet.
  • Selecione a guia Navegar.
  • 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 cliente gRPC.

  • Copie o arquivo Protos\greet.proto do serviço gRPC Greeter para a pasta Protos no projeto 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 <Protobuf> elemento que se refere 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.

Note

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 em C# gerados automaticamente pelo Grpc.Tools, consulte os 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 ao 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

Note

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 e um ASP.NET Core gRPC Server. 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.

Prerequisites

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 para que os namespaces correspondam quando você copia e cola o código.
  • Selecione Próximo.
  • Na caixa de diálogo Informações adicionais , selecione .NET 6.0 (suporte a longo prazo) e, em seguida, 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.
      • porta: 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

Note

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 Propriedades\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 , insira GrpcGreeterClient e selecioneAvançar.
  • Na caixa de diálogo Informações adicionais , selecione .NET 6.0 (suporte a longo prazo) e, em seguida, selecione 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 .NET.
  • Google.Protobuf, que contém APIs de mensagem protobuf para C#.
  • Grpc.Tools, que contém suporte a ferramentas em 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 comandos a seguir:

    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 no Gerenciador> de Soluçõespara Gerenciar Pacotes NuGet.
  • Selecione a guia Navegar.
  • 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 cliente gRPC.

  • Copie o arquivo Protos\greet.proto do serviço gRPC Greeter para a pasta Protos no projeto 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 <Protobuf> elemento que se refere 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.

Note

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 em C# gerados automaticamente pelo Grpc.Tools, consulte os 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 ao 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

Note

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 e um ASP.NET Core gRPC Server. 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.

Prerequisites

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 para que os namespaces correspondam quando você copia e cola o código.
  • Selecione Próximo.
  • Na caixa de diálogo Informações adicionais , selecione .NET 6.0 (suporte a longo prazo) e, em seguida, 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.
      • porta: 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

Note

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 Propriedades\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 , insira GrpcGreeterClient e selecioneAvançar.
  • Na caixa de diálogo Informações adicionais , selecione .NET 6.0 (suporte a longo prazo) e, em seguida, selecione 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 .NET.
  • Google.Protobuf, que contém APIs de mensagem protobuf para C#.
  • Grpc.Tools, que contém suporte a ferramentas em 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 comandos a seguir:

    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 no Gerenciador> de Soluçõespara Gerenciar Pacotes NuGet.
  • Selecione a guia Navegar.
  • 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 cliente gRPC.

  • Copie o arquivo Protos\greet.proto do serviço gRPC Greeter para a pasta Protos no projeto 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 <Protobuf> elemento que se refere 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.

Note

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 em C# gerados automaticamente pelo Grpc.Tools, consulte os 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 ao 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"

Note

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 e um ASP.NET Core gRPC Server.

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

Exibir ou baixar 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.

Prerequisites

Criar um serviço gRPC

  • Inicie o Visual Studio e selecione Criar um 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 para que os namespaces correspondam quando você copia e cola o código.
  • Selecione Próximo.
  • Na caixa de diálogo Informações adicionais, selecione .NET 5.0 na lista suspensa do Target Framework.
  • 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. Uma porta aleatória é usada para o servidor Web quando o Visual Studio cria um projeto 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

Note

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 Greeter gRPC 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 Greeter serviço.
  • 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, consulte a 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) e selecione Avançar.
  • Na caixa de texto Nome do Projeto , insira GrpcGreeterClient e selecioneCriar.

Adicionar os pacotes necessários

O projeto cliente gRPC requer os seguintes pacotes:

  • 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 em 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 comandos a seguir:

    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 no Gerenciador> de Soluçõespara Gerenciar Pacotes NuGet.
  • Selecione a guia Navegar.
  • 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 cliente gRPC.

  • Copie o arquivo Protos\greet.proto do serviço gRPC Greeter para a pasta Protos no projeto 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 <Protobuf> elemento que se refere 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.

Note

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 em C# gerados automaticamente pelo Grpc.Tools, consulte os 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 ao 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

Note

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 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.

Prerequisites

Criar um serviço gRPC

  • Inicie o Visual Studio e selecione Criar um 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 para que os namespaces correspondam quando você copia e cola o código.

  • Selecione Criar.

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

    • O modelo de serviço gRPC foi 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. Uma porta aleatória é usada para o servidor Web quando o Visual Studio cria um projeto 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

Note

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 Greeter gRPC 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 Greeter serviço.
  • 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, consulte a 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 , insira GrpcGreeterClient e selecioneCriar.

Adicionar os pacotes necessários

O projeto cliente gRPC requer os seguintes pacotes:

  • Grpc.Net.Client, que contém o cliente .NET Core.
  • Google.Protobuf, que contém APIs de mensagem protobuf para C#.
  • Grpc.Tools, que contém suporte a ferramentas em 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 comandos a seguir:

    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 no Gerenciador> de Soluçõespara Gerenciar Pacotes NuGet.
  • Selecione a guia Navegar.
  • 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 cliente gRPC.

  • Copie o arquivo Protos\greet.proto do serviço gRPC Greeter para a pasta Protos no projeto 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 <Protobuf> elemento que se refere 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.

Note

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 em C# gerados automaticamente pelo Grpc.Tools, consulte os 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 ao 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

Note

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

  • Last updated on