Importando Módulos de Bibliotecas - Internet Computer

Neste tutorial, você escreverá um dapp simples que permite armazenar e pesquisar números de telefone. Este tutorial ilustra como importar e usar algumas funções básicas da biblioteca Motoko.

Para este tutorial, as funções da biblioteca base do Motoko são definidas nos módulos List e AssocList e permitem que você trabalhe com listas como pares chave-valor vinculados. Neste exemplo, a chave é um nome e o valor é a string de texto do telefone associada a esse nome.

Este dapp suporta as seguintes chamadas de função:

• A função insert aceita o par chave-valor nome e telefone como entrada armazenada na variável book.
• A função lookup é uma consulta que usa a chave de nome especificada como entrada para localizar o número de telefone associado.

Antes de começar

Antes de iniciar o tutorial, verifique o seguinte:

• Você baixou e instalou o pacote SDK conforme descrito em Download and Install.
• Você parou o ambiente de execução do cânister local fornecido pelo dfx.

Este tutorial leva aproximadamente 10 minutos para ser concluído.

Crie um novo projeto

Para criar um novo projeto para este tutorial:

1. Abra um shell de terminal em seu computador local, se você ainda não tiver um aberto.
2. Mude para a pasta que você está usando para seus projetos da Internet Computer, se estiver usando uma.

3. Crie um novo projeto executando o seguinte comando:
   

   dfx new phonebook
   

4. Mude para o diretório do seu projeto executando o seguinte comando:
   

   cd phonebook
   

Modifique o dapp padrão

Para este tutorial, vamos criar um novo arquivo main.mo para o dapp simples de pesquisa de número de telefone.

Para modificar o modelo padrão:

1. Abra o arquivo src/phonebook/main.mo em um editor de texto e exclua o conteúdo existente.

2. Copie e cole este código no arquivo main.mo.

   Ao olhar para este dapp de amostra, você pode notar os seguintes elementos-chave:

• O código define Nome e Telefone como tipos Textuais personalizados. A criação de tipos definidos pelo usuário melhora a legibilidade do código.
• A função insert é uma chamada de atualização e a função lookup é uma chamada de consulta.
• O tipo de telefone é identificado como um valor opcional usando a sintaxe ?Phone.

Inicie o ambiente de execução do cânister local

Para fins de desenvolvimento, o dfx fornece um ambiente de execução de cânister local. Isso requer um arquivo dfx.json, então você deve ter certeza de que está no diretório raiz do seu projeto. Para este tutorial, você deve ter dois shells de terminal separados, para poder iniciar e ver o output do ambiente de execução do cânister local em um terminal e gerenciar seu projeto em outro.

Para iniciar o ambiente de execução do cânister local:

1. Abra uma nova janela de terminal ou guia em seu computador local.
2. Navegue até o diretório raiz do seu projeto, se necessário.
3. Agora você deve ter dois terminais abertos.
4. Você deve ter o diretório do projeto como seu diretório de trabalho atual.

5. Inicie o ambiente de execução local do cânister localmente em seu computador executando o seguinte comando:
   

   dfx start --clean
   

   Para este tutorial, estamos usando a opção --clean para iniciar o ambiente de execução do cânister local em um estado limpo.

   Essa opção remove quaisquer processos esquecidos em segundo plano ou identificadores de cânister que possam interromper as operações normais. Por exemplo, se você esqueceu de executar um dfx stop ao se mover entre projetos, você pode ter um processo em execução em segundo plano ou em outro terminal. A opção --clean garante que você possa iniciar o ambiente de execução do cânister local e continuar para a próxima etapa sem a necessidade de localizar e encerrar manualmente os processos em execução.

6. Deixe o terminal que exibe a saída do ambiente de execução do cânister local aberto e mude seu foco para o terminal original onde você criou seu novo projeto.

Registre, construa e implante o dapp

Assim que o ambiente de execução do cânister local estiver funcionando em seu ambiente de desenvolvimento, você poderá registrar, construir e implementar seu dapp nele.

Para implantar o dapp localmente:

1. Verifique se você ainda está no diretório raiz do seu projeto, se necessário.

2. Registre, crie e implante seu dapp localmente executando o seguinte comando:
   

   dfx deploy phonebook
   

   O arquivo dfx.json fornece configurações padrão para criar um ponto de entrada do front-end e um cânister assets (ativos) para o dapp .

   Nos tutoriais anteriores, excluímos as entradas do cânister de ativos porque não estávamos adicionando um front-end para o dapp de amostra. Essa mudança manteve nosso espaço de trabalho do projeto organizado, eliminando arquivos que não seriam usados. No entanto, não há necessidade de fazer isso e não há problema em deixar a descrição do cânister de ativos no arquivo dfx.json. Por exemplo, talvez você queira usá-lo como um espaço reservado se pretender adicionar ativos de front-end posteriormente.

   Para este tutorial, você pode implantar apenas o cânister de back-end da agenda telefônica usando o comando dfx deploy phonebook, porque o projeto não inclui nenhum ativo de front-end e você interagirá com ele por meio do terminal.

   Embora este tutorial ilustre como pular a compilação de um cânister de front-end, você pode adicionar uma interface de usuário simples a este dapp posteriormente explorando o projeto de agenda telefônica no repositório de exemplos.

Adicione nomes e números usando a função de inserção

Agora você tem um dapp implementado como um cânister em seu ambiente de execução de cânister local e pode testar seu dapp usando comandos dfx canister call.

Para testar o dapp que você implantou:

1. Use o comando dfx canister call para chamar o phonebook do cânister usando a função insert e para passar um nome e número de telefone, executando o seguinte comando:
   

   dfx canister call phonebook insert '("Cristiano", "01 415 792 1333")'
   

2. Adicione um segundo par de nome e número executando o seguinte comando:
   

   dfx canister call phonebook insert '("Maria", "01 408 395 7276")'
   

3. Verifique se o comando retorna o número associado a "Cristiano" usando a função lookup executando o seguinte comando:
   

   dfx canister call phonebook lookup '("Cristiano")'
   

   O comando retorna um output semelhante ao seguinte:
   

   (opt "01 415 792 1333")
   

4. Tente chamar a função lookup com o número associado a "Maria" executando o seguinte comando:
   

   dfx canister call lookup '("01 408 395 7276")'
   

   Observe que, nesse caso, o comando retorna (null) porque o número de telefone não é uma chave associada à entrada do nome "Maria".

5. Tente chamar a função lookup novamente para retornar os números de telefone de "Maria" e "Cristiano" executando o seguinte comando:
   

   dfx canister call phonebook lookup '("Maria","Cristiano")'
   

   Como o dapp é escrito para retornar um valor para uma chave, o comando retorna apenas informações associadas à primeira chave, neste exemplo, o número de telefone da Maria.

6. Teste seu código usando a IU (Interface do Usuário) Candid.
   

   Para testar seu código, siga as instruções [aqui](/docs/current/developer-docs/build/backend/candid-ui).
   

Revise o código-fonte em seu dapp

Para estender o que você aprendeu neste tutorial, você pode tentar modificar o código-fonte para retornar resultados diferentes.

Por exemplo, você pode querer alterar o código-fonte para que, em vez de um dapp que insira e pesquise um par chave-valor atual (nome-telefone), crie um dapp que armazene informações de contato semelhantes a um "registro" de banco de dados no qual uma chave primária está associada a vários campos. Neste exemplo, seu dapp pode permitir que usuários ou outro dapp adicionem informações — como um número de telefone residencial, um número de telefone celular, um endereço de e-mail e um endereço residencial — e retornem seletivamente todos ou valores de campo específicos.

Pare o ambiente de execução do cânister local

Depois de concluir a experiência com seu dapp, você pode parar o ambiente de execução do cânister local para que ele não continue em execução em segundo plano.

Para parar o ambiente de execução do cânister local:

1. No terminal que exibe as operações de rede, pressione Control-C para interromper o processo de rede local.

2. Pare o ambiente de execução do cânister local executando o seguinte comando:
   

   dfx stop
   

Este guia foi publicado nos Docs do Desenvolvedor da Internet Computer. Traduzido por Paulinho Giovannini.