Compartilhar via


Testar serviços gRPC com gRPCurl e gRPCui no ASP.NET Core

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Por James Newton-King

As ferramentas estão disponíveis para gRPC que permite aos desenvolvedores testar serviços sem criar aplicativos cliente:

  • gRPCurl é uma ferramenta de linha de comando de código aberto que fornece interação com serviços gRPC.
  • gRPCui tem base em gRPCurl e adiciona uma interface do usuário da Web interativa de código aberto para gRPC.

Este artigo discute como:

  • Configurar a reflexão do servidor gRPC com um aplicativo gRPC ASP.NET Core.
  • Interagir com gRPC usando ferramentas de teste:
    • Descubrir e testar serviços gRPC com grpcurl.
    • Interagir com serviços gRPC por meio de um navegador usando grpcui.

Observação

Para saber como testar a unidade de serviços gRPC, confira Testar serviços gRPC no ASP.NET Core.

Configurar reflexão gRPC

As ferramentas devem conhecer o contrato de serviços de Protobuf antes de poder chamá-los. Há duas maneiras de fazer isso:

  • Configure a reflexão gRPC no servidor. Ferramentas, como gRPCurl, usam reflexão para descobrir automaticamente contratos de serviço.
  • Adicione arquivos .proto à ferramenta manualmente.

É mais fácil usar a reflexão gRPC. A reflexão gRPC adiciona um novo serviço gRPC ao aplicativo que os clientes podem chamar para descobrir serviços.

gRPC ASP.NET Core tem suporte interno para reflexão gRPC com o pacote Grpc.AspNetCore.Server.Reflection. Para configurar a reflexão em um aplicativo:

  • Adicione uma referência de pacote para Grpc.AspNetCore.Server.Reflection.
  • Registrar reflexão em Program.cs:
    • AddGrpcReflection para registrar serviços que habilitam a reflexão.
    • MapGrpcReflectionService para adicionar um ponto de extremidade de serviço de reflexão.
builder.Services.AddGrpc();
builder.Services.AddGrpcReflection();

var app = builder.Build();

app.MapGrpcService<GreeterService>();

IWebHostEnvironment env = app.Environment;

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

Quando a reflexão gRPC é configurada:

  • Um serviço de reflexão gRPC é adicionado ao aplicativo de servidor.
  • Aplicativos cliente que dão suporte à reflexão gRPC podem chamar o serviço de reflexão para descobrir os serviços hospedados pelo servidor.
  • Os serviços gRPC ainda são chamados do cliente. A reflexão apenas habilita a descoberta de serviço e não ignora a segurança do lado do servidor. Os pontos de extremidade protegidos por autenticação e autorização exigem que o chamador passe credenciais para que o ponto de extremidade seja chamado com êxito.

Segurança do serviço de reflexão

A reflexão gRPC retorna uma lista de APIs disponíveis, que podem conter informações confidenciais. Deve-se tomar cuidado para limitar o acesso ao serviço de reflexão gRPC.

A reflexão gRPC geralmente é necessária apenas em um ambiente de desenvolvimento local. Para o desenvolvimento local, o serviço de reflexão só deve ser mapeado quando IsDevelopment retornar true:

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

O acesso ao serviço pode ser controlado por meio de métodos padrão de extensão de autorização do ASP.NET Core, como AllowAnonymous e RequireAuthorization.

Por exemplo, se um aplicativo tiver sido configurado para exigir a autorização por padrão, configure o ponto de extremidade de reflexão gRPC com AllowAnonymous para ignorar a autenticação e a autorização.

if (env.IsDevelopment())
{
    app.MapGrpcReflectionService().AllowAnonymous();
}

gRPCurl

gRPCurl é uma ferramenta de linha de comando criada pela comunidade gRPC. Seus recursos incluem:

  • Chamando serviços gRPC, incluindo serviços de streaming.
  • Descoberta de serviço usando reflexão de gRPC.
  • Listando e descrevendo serviços gRPC.
  • Funciona com servidores seguros (TLS) e inseguros (texto sem formatação).

Para obter informações sobre como baixar e instalar grpcurl, confira a página inicial do GitHub gRPCurl.

Linha de comando de gRPCurl

Use grpcurl.

O argumento -help explica as opções de linha de comando de grpcurl:

$ grpcurl -help

Descobrir serviços

Use o verbo describe para exibir os serviços definidos pelo servidor. Especifique <port> como o número da porta localhost do servidor gRPC. O número de porta é atribuído aleatoriamente quando o projeto do servidor gRPC é criado e definido em Properties/launchSettings.json:

$ grpcurl localhost:<port> describe
greet.Greeter is a service:
service Greeter {
  rpc SayHello ( .greet.HelloRequest ) returns ( .greet.HelloReply );
  rpc SayHellos ( .greet.HelloRequest ) returns ( stream .greet.HelloReply );
}
grpc.reflection.v1alpha.ServerReflection is a service:
service ServerReflection {
  rpc ServerReflectionInfo ( stream .grpc.reflection.v1alpha.ServerReflectionRequest ) returns ( stream .grpc.reflection.v1alpha.ServerReflectionResponse );
}

No exemplo anterior:

  • Executa o verbo describe no servidor localhost:<port>. Em que <port> é atribuído aleatoriamente quando o projeto do servidor gRPC é criado e definido em Properties/launchSettings.json
  • Imprime serviços e métodos retornados pela reflexão gRPC.
    • Greeter é um serviço implementado pelo aplicativo.
    • ServerReflection é o serviço adicionado pelo pacote Grpc.AspNetCore.Server.Reflection.

Combine describe com um serviço, um método ou um nome de mensagem para exibir seus detalhes:

$ grpcurl localhost:<port> describe greet.HelloRequest
greet.HelloRequest is a message:
message HelloRequest {
  string name = 1;
}

Chamar serviços gRPC

Chame um serviço gRPC especificando um nome de serviço e método junto com um argumento JSON que representa a mensagem de solicitação. O JSON é convertido em Protobuf e enviado para o serviço.

$ grpcurl -d '{ \"name\": \"World\" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

No exemplo anterior:

  • O argumento -d especifica uma mensagem de solicitação com JSON. Esse argumento deve vir antes do endereço do servidor e do nome do método.
  • Chama o método SayHello no serviço greeter.Greeter.
  • Imprime a mensagem de resposta como JSON.
  • Em que <port> é atribuído aleatoriamente quando o projeto do servidor gRPC é criado e definido em Properties/launchSettings.json

O exemplo anterior usa \ para escapar o caractere ". O escape de " é necessário em um console do PowerShell, mas não deve ser usado em alguns consoles. Por exemplo, o comando anterior para um console macOS:

$ grpcurl -d '{ "name": "World" }' localhost:<port> greet.Greeter/SayHello
{
  "message": "Hello World"
}

gRPCui

gRPCui é uma interface do usuário da Web interativa para gRPC. gRPCui se baseia em gRPCurl. gRPCui oferece uma GUI para descobrir e testar serviços gRPC, semelhantes a ferramentas HTTP, como a interface do usuário do Swagger.

Para obter informações sobre como baixar e instalar grpcui, confira a página inicial do gRPCurl no GitHub.

Usando grpcui

Execute grpcui com o endereço do servidor com o qual interagir como um argumento:

$ grpcui localhost:<port>
gRPC Web UI available at http://127.0.0.1:55038/

No exemplo anterior, especifique <port> como o número da porta localhost do servidor gRPC. O número da porta é atribuído aleatoriamente quando o projeto é criado e definido em Properties/launchSettings.json

A ferramenta inicia uma janela do navegador com a interface do usuário da Web interativa. Os serviços do gRPC são descobertos automaticamente usando a reflexão gRPC.

Interface de usuário da Web de gRPCui

Recursos adicionais

As ferramentas estão disponíveis para gRPC que permite aos desenvolvedores testar serviços sem criar aplicativos cliente:

  • gRPCurl é uma ferramenta de linha de comando de código aberto que fornece interação com serviços gRPC.
  • gRPCui tem base em gRPCurl e adiciona uma interface do usuário da Web interativa de código aberto para gRPC.

Este artigo discute como:

  • Configurar a reflexão do servidor gRPC com um aplicativo gRPC ASP.NET Core.
  • Interagir com gRPC usando ferramentas de teste:
    • Descubrir e testar serviços gRPC com grpcurl.
    • Interagir com serviços gRPC por meio de um navegador usando grpcui.

Observação

Para saber como testar a unidade de serviços gRPC, confira Testar serviços gRPC no ASP.NET Core.

Configurar reflexão gRPC

As ferramentas devem conhecer o contrato de serviços de Protobuf antes de poder chamá-los. Há duas maneiras de fazer isso:

  • Configure a reflexão gRPC no servidor. Ferramentas, como gRPCurl, usam reflexão para descobrir automaticamente contratos de serviço.
  • Adicione arquivos .proto à ferramenta manualmente.

É mais fácil usar a reflexão gRPC. A reflexão gRPC adiciona um novo serviço gRPC ao aplicativo que os clientes podem chamar para descobrir serviços.

gRPC ASP.NET Core tem suporte interno para reflexão gRPC com o pacote Grpc.AspNetCore.Server.Reflection. Para configurar a reflexão em um aplicativo:

  • Adicione uma referência de pacote para Grpc.AspNetCore.Server.Reflection.
  • Registrar reflexão em Startup.cs:
    • AddGrpcReflection para registrar serviços que habilitam a reflexão.
    • MapGrpcReflectionService para adicionar um ponto de extremidade de serviço de reflexão.
public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
    services.AddGrpcReflection();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();
    
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGrpcService<GreeterService>();

        if (env.IsDevelopment())
        {
            endpoints.MapGrpcReflectionService();
        }
    });
}

Quando a reflexão gRPC é configurada:

  • Um serviço de reflexão gRPC é adicionado ao aplicativo de servidor.
  • Aplicativos cliente que dão suporte à reflexão gRPC podem chamar o serviço de reflexão para descobrir os serviços hospedados pelo servidor.
  • Os serviços gRPC ainda são chamados do cliente. A reflexão apenas habilita a descoberta de serviço e não ignora a segurança do lado do servidor. Os pontos de extremidade protegidos por autenticação e autorização exigem que o chamador passe credenciais para que o ponto de extremidade seja chamado com êxito.

gRPCurl

gRPCurl é uma ferramenta de linha de comando criada pela comunidade gRPC. Seus recursos incluem:

  • Chamando serviços gRPC, incluindo serviços de streaming.
  • Descoberta de serviço usando reflexão de gRPC.
  • Listando e descrevendo serviços gRPC.
  • Funciona com servidores seguros (TLS) e inseguros (texto sem formatação).

Para obter informações sobre como baixar e instalar grpcurl, confira a página inicial do GitHub gRPCurl.

Linha de comando de gRPCurl

Use grpcurl.

O argumento -help explica as opções de linha de comando de grpcurl:

$ grpcurl -help

Descobrir serviços

Use o verbo describe para exibir os serviços definidos pelo servidor:

$ grpcurl localhost:5001 describe
greet.Greeter is a service:
service Greeter {
  rpc SayHello ( .greet.HelloRequest ) returns ( .greet.HelloReply );
  rpc SayHellos ( .greet.HelloRequest ) returns ( stream .greet.HelloReply );
}
grpc.reflection.v1alpha.ServerReflection is a service:
service ServerReflection {
  rpc ServerReflectionInfo ( stream .grpc.reflection.v1alpha.ServerReflectionRequest ) returns ( stream .grpc.reflection.v1alpha.ServerReflectionResponse );
}

No exemplo anterior:

  • Executa o verbo describe no servidor localhost:5001.
  • Imprime serviços e métodos retornados pela reflexão gRPC.
    • Greeter é um serviço implementado pelo aplicativo.
    • ServerReflection é o serviço adicionado pelo pacote Grpc.AspNetCore.Server.Reflection.

Combine describe com um serviço, um método ou um nome de mensagem para exibir seus detalhes:

$ grpcurl localhost:5001 describe greet.HelloRequest
greet.HelloRequest is a message:
message HelloRequest {
  string name = 1;
}

Chamar serviços gRPC

Chame um serviço gRPC especificando um nome de serviço e método junto com um argumento JSON que representa a mensagem de solicitação. O JSON é convertido em Protobuf e enviado para o serviço.

$ grpcurl -d '{ \"name\": \"World\" }' localhost:5001 greet.Greeter/SayHello
{
  "message": "Hello World"
}

No exemplo anterior:

  • O argumento -d especifica uma mensagem de solicitação com JSON. Esse argumento deve vir antes do endereço do servidor e do nome do método.
  • Chama o método SayHello no serviço greeter.Greeter.
  • Imprime a mensagem de resposta como JSON.

O exemplo anterior usa \ para escapar o caractere ". O escape de " é necessário em um console do PowerShell, mas não deve ser usado em alguns consoles. Por exemplo, o comando anterior para um console macOS:

$ grpcurl -d '{ "name": "World" }' localhost:5001 greet.Greeter/SayHello
{
  "message": "Hello World"
}

gRPCui

gRPCui é uma interface do usuário da Web interativa para gRPC. gRPCui se baseia em gRPCurl. gRPCui oferece uma GUI para descobrir e testar serviços gRPC, semelhantes a ferramentas HTTP, como a interface do usuário do Swagger.

Para obter informações sobre como baixar e instalar grpcui, confira a página inicial do gRPCurl no GitHub.

Usando grpcui

Execute grpcui com o endereço do servidor com o qual interagir como um argumento:

$ grpcui localhost:5001
gRPC Web UI available at http://127.0.0.1:55038/

A ferramenta inicia uma janela do navegador com a interface do usuário da Web interativa. Os serviços do gRPC são descobertos automaticamente usando a reflexão gRPC.

Interface de usuário da Web de gRPCui

Recursos adicionais