19 de Novembro de 2021

Teste suas APIs .Net5 com Httprepl

Por Fernando C.

Neste artigo irei apresentar uma nova maneira de testar suas Web APIs .Net5 usando Httprepl.

Httprepl (HTTP Read-Eval-Print Loop) é uma ferramenta de linha comando que nos permite testar web apis de forma simples e rápida e é uma alternativa á outras soluções como Swagger e Postman. Vamos ver a seguir como instalar, configurar e como usá-la.

Procedimento para instalação

  1. Certifique-se que você tem a sdk do dotnet instalado
fernando@fernando-System-Product-Name:~$ dotnet --version
6.0.100
  1. Instale a ferramenta Httprepl
fernando@fernando-System-Product-Name:~$ dotnet tool install -g Microsoft.dotnet-httprepl
O diretório de ferramentas '/home/fernando/.dotnet/tools' não está na variável de ambiente PATH no momento.
Se você estiver usando o Bash, adicione-o ao seu perfil executando o seguinte comando

cat << \EOF >> ~/.bash_profile
# Add .NET Core SDK tools
export PATH="$PATH:/home/fernando/.dotnet/tools"
EOF

Você pode adicioná-lo à sessão atual executando o seguinte comando:

export PATH="$PATH:/home/fernando/.dotnet/tools"

Você pode invocar a ferramenta usando o comando a seguir: httprepl
A ferramenta 'microsoft.dotnet-httprepl' (versão '6.0.0') foi instalada com êxito

Se tudo ocorrer bem, aparecerá uma mensagem informando que a instalação foi bem sucedida. No caso da minha instalação, a mensagem também informava que o caminho “.dotnet/tools” não estava na varíavel de ambiente PATH e sugere que seja usado o comando EXPORT para fazer esta adição na seção atual.

  1. Execute o comando httprepl. Você deve ver algo como isto:
fernando@fernando-System-Product-Name:~$ httprepl
(Disconnected)> 

Sucesso 😎 ? Ótimo, a ferramenta está instalada e pronta para usar

Ainda não 🙁 ? Encontrou uma mensagem como esta abaixo?

fernando@fernando-System-Product-Name:~$ httprepl
A fatal error occurred. The required library libhostfxr.so could not be found.
If this is a self-contained application, that library should exist in [/home/fernando/.dotnet/tools/.store/microsoft.dotnet-httprepl/6.0.0/microsoft.dotnet-httprepl/6.0.0/tools/net6.0/any/].
If this is a framework-dependent application, install the runtime in the global location [/usr/share/dotnet] or use the DOTNET_ROOT environment variable to specify the runtime location or register the runtime location in [/etc/dotnet].

The .NET runtime can be found at:
  - https://aka.ms/dotnet-core-applaunch?missing_runtime=true&arch=x64&rid=linuxmint.20.2-x64&apphost_version=6.0.0

Tudo bem, basta criar a variável de ambiente DOTNET_ROOT usando o seguinte comando : export DOTNET_ROOT=/snap/dotnet-sdk/current

Optei por colocar as duas variáveis de ambiente dentro do arquivo /etc/bash.bashrc, do contrário teria que executar os dois comandos EXPORT sempre que o computador fosse ligado ou quisesse executar a ferramenta em uma nova janela do terminal.

Testando uma Web API com HttpRepl

  1. Criar uma nova API com dotnet CLI em uma nova pasta chamada HelloAPI
fernando@fernando-System-Product-Name:~/repo/youtube$ dotnet new webapi --no-https -o HelloAPI
O modelo "ASP.NET Core Web API" foi criado com êxito.

Processando ações pós-criação...
Executando 'dotnet restore' em /home/fernando/repo/youtube/HelloAPI/HelloAPI.csproj...
  Determinando os projetos a serem restaurados...
  /home/fernando/repo/youtube/HelloAPI/HelloAPI.csproj restaurado (em 232 ms).
A restauração foi bem-sucedida.
  1. Abrir o Visual Studio Code
fernando@fernando-System-Product-Name:~/repo/youtube$ code HelloAPI
  1. Com o Visual Studio Code aberto, apagar os arquivos WeatherForecast e o controlador WeatherForecastController
  1. Criar um novo controlador HelloController com as ações GetHelloMessage e PostHelloMessage
using Microsoft.AspNetCore.Mvc;

namespace HelloAPI.Controllers;

[ApiController]
[Route("[controller]")]
public class HelloController : ControllerBase
{
    public HelloController()
    {}

    [HttpGet]
    public string GetHelloMessage()
    {
        return "Hello API";
    }

    [HttpPost]
    public string  PostHelloMessage([FromBody]string name)
    {
        return ($"Hello, {name}");
    }
}
  1. No Visual Studio Code, abrir um novo terminal ( Ctrl + ` ) e executar o comando dotnet run para excutar sua API em localhost. Preste atenção ao número da porta que será usado. Neste exemplo, estou usando a porta de número 5002 (este número pode variar).
fernando@fernando-System-Product-Name:~/repo/youtube/HelloAPI$ dotnet run
Compilando...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5002
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: /home/fernando/repo/youtube/HelloAPI/

Abrir um novo terminal e executar o comando httprepl, seguido do endereço de execução da sua api. No meu caso, ficou assim.

fernando@fernando-System-Product-Name:~/repo/youtube/HelloAPI$ httprepl http://localhost:5002/
(Disconnected)> connect http://localhost:5002/
Using a base address of http://localhost:5002/
Using OpenAPI description at http://localhost:5002/swagger/v1/swagger.json
For detailed tool info, see https://aka.ms/http-repl-doc

http://localhost:5002/>

Se você recebeu a mensagem da listagem acima, parabéns! A ferramenta está em execução e conseguiu se conectar à sua api.

Agora podemos listar e navegar pelas APIs em execução em localhost e suas ações usando os comando ls e cd, da mesma forma que faríamos se estivéssemos navegando em uma estrutura de diretórios.

  • Listando todas APIs/ controladores em localhost :
http://localhost:5002/> ls
.       []
Hello   [GET|POST]
  • Conectando a um controlador (HelloController)
http://localhost:5002/> cd Hello
/Hello    [GET|POST]

http://localhost:5002/Hello> 
  • Listando todas as ações do controlador HelloController
http://localhost:5002/Hello> ls
.    [GET|POST]
..   []

Testando o método GetHelloMessage

Para testar o método GetHelloMessage é muito simples, basta estar no “diretório” Hello e digitar Get.

http://localhost:5002/Hello> get
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Sun, 21 Nov 2021 19:39:47 GMT
Server: Kestrel
Transfer-Encoding: chunked

Hello API

Testando o método PostHelloMessage

Antes de testar as ações PUT e POST devemos especificar um editor padrão onde poderemos editar o payload da chamada (você só precisa fazer isso uma vez)

(Obs: Confira antes o diretório de instalação do Visual Studio Code, o meu está instalado em /snap/bin/code)

http://localhost:5002/Hello> pref set editor.command.default "/snap/bin/code"
If your default editor is Visual Studio Code, you should set the default command arguments (`editor.command.default.arguments`) to include `-w` or `--wait` to ensure proper integration between HttpRepl and Visual Studio Code.

Se indicarmos o Visual Studio Code como editor padrão, ainda devemos fazer uma configuração adicional para que a execução do comando prossiga apenas quando o arquivo de payload for fechado.

http://localhost:5002/Hello> pref set editor.command.default.arguments "-w"

Um pouco trabalhoso 🙄 , mas lembre-se que vamos fazer isto apenas uma vez.

Agora podemos seguir com o teste das ações POST/ PUT:

  1. Finalmente, entre no “diretório” Hello e digite Post.
http://localhost:5002/Hello/Hello> post
Se esta janela aparecer, basta clicar no botão Abrir.

Um novo arquivo com a extensão .json vai se abrir na janela do editor. Não se preocupe, este arquivo não fará parte do seu projeto, ele é apenas temporário.

  1. Digite os parâmetros de entrada do método PostHelloMessage.
  1. Salve e feche o arquivo .json e observe a saída na janela do terminal.
http://localhost:5002/hello> post
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Sun, 21 Nov 2021 21:37:34 GMT
Server: Kestrel
Transfer-Encoding: chunked

Hello, Desenvolvedor Fernando


http://localhost:5002/hello> 

Conclusão

Usar Httprepl é uma nova opção para testes de APIs, além dos já conhecidos Postman e Swagger.

No início achei um pouco complicado mas já estou me acostumando à linha de comando. Outro benefício que tenho encontrado é possibilidade de continuar trabalhando na própria IDE do Visual Studio Code sem precisar navegar entre abas do Postman e do navegador, parece bobagem mas evita a perda de foco.

Materiais de referência

Microsoft Docs: https://docs.microsoft.com/en-us/aspnet/core/web-api/http-repl/?view=aspnetcore-6.0&tabs=linux

GitHub: https://github.com/dotnet/HttpRepl