Incrementar um Número Natural - Internet Computer

Neste tutorial, você vai escrever um programa que cria um único ator e fornece algumas funções básicas para incrementar um contador e ilustrar a persistência de um valor.

Para este tutorial, o ator é chamado de Counter. O programa usa a variável currentValue para conter um número natural que representa o valor atual do contador. Este programa suporta as seguintes chamadas de função:

• A chamada de função increment atualiza o valor atual, incrementando-o em 1 (sem valor de retorno).
• A chamada de função get consulta e retorna o valor atual do contador.
• A chamada de função set atualiza o valor atual para um valor numérico arbitrário que você especifica como argumento.

Este tutorial fornece um exemplo simples de como você pode incrementar um contador através da chamada de funções em um cânister implantado. Ao chamar as funções para incrementar e consultar o valor do contador várias vezes, você pode verificar o estado da variável - isto é, o valor da variável entre chamadas-persiste.

Antes de você começar

Antes de iniciar o tutorial, verifique o seguinte:

• Você baixou e instalou o pacote SDK como descrito em Baixar e instalar.
• Você parou qualquer ambiente local de execução do cânister rodando no computador.

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

Criar um novo projeto

Para criar um novo diretório de projeto para este tutorial:

• Abra um terminal em seu computador local, se você ainda não tiver um aberto.
• Mude para a pasta que você está usando para seus projetos da Internet Computador, se você estiver usando uma.
• Crie um novo projeto executando o seguinte comando:

dfx new my_counter

O comando cria um novo projeto my_counter para seu projeto.

• Mude para o diretório de seu projeto executando o seguinte comando:

cd my_counter

Modificar a configuração padrão

Você já viu que a criação de um novo projeto adiciona um arquivo de configuração padrão dfx.json ao seu diretório de projetos. Neste tutorial, você modificará as configurações padrão para usar um nome diferente para o programa principal em seu projeto.

Para modificar o arquivo de configuração dfx.json:

• Abra o arquivo de configuração dfx.json em um editor de texto e altere a configuração main padrão de main.mo para increment_counter.mo.

Por exemplo:

"main": "src/my_counter/increment_counter.mo",

Para este tutorial, alterar o nome do arquivo fonte de main.mo para increment_counter.mo, simplesmente ilustra como a configuração no arquivo de configuração dfx.json determina o arquivo fonte a ser compilado.

Em um dapp mais complexo, você pode ter múltiplos arquivos fonte com dependências que você precisa gerenciar usando as configurações no arquivo de configuração dfx.json. Em um cenário como esse - com múltiplos cânisters e programas definidos em seu arquivo dfx.json - ter múltiplos arquivos todos nomeados main.mo pode ser confuso.

Você pode deixar o resto das configurações padrão como elas estão.

• Salve sua mudança e feche o arquivo dfx.json para continuar.
• Mude o nome do arquivo principal do programa no diretório do código-fonte src para corresponder ao nome especificado no arquivo de configuração dfx.json executando o seguinte comando

mv src/my_counter/main.mo src/my_counter/increment_counter.mo

Modificar o programa padrão

Até agora, você só mudou o nome do programa principal para seu projeto. O próximo passo é modificar o código no arquivo src/my_counter/increment_counter.mo para definir um ator chamado Counter e implementar as funções , increment, get, e , set, .

Para modificar o código fonte padrão do modelo:

1. Verifique se você ainda está no diretório de seu projeto, se necessário.
2. Abrir o arquivo src/my_counter/increment_counter.mo em um editor de texto e exclua o conteúdo existente.
3. Copie e cole este código no arquivo increment_counter.mo.

Vamos dar uma olhada mais detalhada neste programa de exemplo:

• Você pode ver que a declaração da variável currentValue neste exemplo inclui a palavra chave stable para indicar o estado - o valor que pode ser definido, incrementado e recuperado - os persistentes.
• Esta palavra chave garante que o valor da variável não será alterada quando o programa for atualizado.
• A declaração para a variável currentValue também especifica que seu tipo é um número natural (Nat).
• O programa inclui dois métodos de atualização públicos - as funções increment e set - e um método de consulta - função get.

Para mais informações sobre variáveis estáveis e flexíveis, consulte Variáveis estáveis e métodos de atualização no Guia de Linguagem de Programação Motoko.

Para mais informações sobre as diferenças entre uma consulta e uma atualização, veja Métodos de consulta e atualização em Cânisters incluem tanto o programa quanto o estado.

• Salve suas alterações e feche o arquivo para continuar.

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

Antes de poder construir o projeto my_counter, você precisa se conectar a um ambiente local de execução do cânister, simulando a blockchain Internet Computer ou à rede principal da blockchain Internet Computer.

Iniciar o ambiente local de execução do cânister requer um arquivo dfx.json, portanto, você deve ter certeza de que está no diretório raiz do seu projeto. Para este tutorial, você deve ter dois shells de terminais separados, para que possa iniciar e ver as operações de rede em um terminal e gerenciar seu projeto em outro.

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

• Abra uma nova janela de terminal ou uma aba em seu computador local.

• Navegue até o diretório raiz de seu projeto, se necessário.

• Agora você deve ter dois terminais abertos.

• Você deve ter o diretório do projeto como seu diretório de trabalho atual.

• Inicie o ambiente local de execução do cânister em seu computador, executando o seguinte comando:

dfx start

Depois de iniciar o ambiente local de execução do cânister, o terminal exibe mensagens sobre as operações de rede.

• Deixe o terminal que exibe as operações de rede aberto e mude seu foco para seu terminal original, onde você criou seu novo projeto.

Registre, construa e implante o dapp

Depois de conectar-se ao ambiente local de execução do cânister em seu ambiente de desenvolvimento, você pode registrar, construir e implantar seu dapp localmente.

Para implantar o dapp localmente:

1. Verifique se você ainda está no diretório raiz do seu projeto, se necessário.
2. Registre, construa e implemente seu dapp executando o seguinte comando:

dfx deploy

A saída do comando dfx deploy exibe informações sobre as operações que ele realiza.

Métodos de chamada do cânister implantado

Depois de ter implantado o cânister com sucesso, você pode simular um usuário final chamando os métodos fornecidos pelo cânister. Para este tutorial, você chama o método get para consultar o valor de um contador, o método increment que incrementa o contador cada vez que ele é chamado, e o método set para passar um argumento para atualizar o contador para um valor arbitrário especificado por você.

Para testar os métodos de chamada do cânister implantado:

• Execute o seguinte comando para chamar a função get, que lê o valor atual da variável currentValue no cânister implantado:

dfx canister call my_counter get

O comando retorna o valor atual da variável currentValue como zero:

(0 : nat)

• Execute o seguinte comando para chamar a função increment para incrementar o valor da variável currentValue no cânister implantado por:

dfx canister call my_counter increment

Este comando incrementa o valor da variável - mudando seu estado - mas não retorna o resultado.

• Execute novamente o seguinte comando para obter o valor atual da variável currentValue no cânister implantado:

dfx canister call my_counter get

O comando retorna o valor atualizado da variável currentValue como um:

(1 : nat)

• Executar comandos adicionais para experimentar a chamada de outros métodos e o uso de valores diferentes.

Por exemplo, tente comandos semelhantes aos seguintes para definir e retornar o valor do contador:

dfx canister call my_counter set '(987)'
dfx canister call my_counter get

Isto retorna o valor atualizado do currentValue para ser 987. Executando os comandos adicionais

dfx canister call my_counter increment
dfx canister call my_counter get

retorna currentValue incremental de 988.

• Teste seu código usando o candid ui.

Para testar seu código, siga as instruções aqui.

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

Depois de terminar de experimentar seu dapp, você pode parar o ambiente local de execução do cânister para que ele não continue funcionando em segundo plano.

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

1. No terminal que exibe as operações de rede, pressione Control-C para interromper o ambiente local de execução do cânister.

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

dfx stop

Este artigo foi publicado no Portal do Desenvolvedor Internet Computer. Traduzido por Marcelo Panegali.