Explore o projeto padrão - Internet Computer

Se você começou sua turnê pelo SDK com o Quick start, você já viu o fluxo de trabalho básico para criar dapps executados no Internet Computer. Agora, vamos dar uma olhada mais de perto nesse fluxo de trabalho, explorando os arquivos e pastas padrão que são adicionados ao seu espaço de trabalho quando você cria um novo projeto.

Como amostra, o diagrama a seguir ilustra o fluxo de trabalho de desenvolvimento ao executar o Internet Computer localmente no seu computador.

Antes de começar

Antes de iniciar este tutorial, verifique o seguinte:

• Se você tem uma conexão com a Internet e acesso a um terminal shell no seu computador macOS ou Linux local.

• Se você tem node.js instalado, se você deseja incluir os arquivos de modelo padrão para o desenvolvimento do front-end em seu projeto.

• Se você baixou e instalou o pacote SDK conforme descrito em Download and install.

• Se você instalou a extensão Motoko, conforme descrito em  Install the language editor plug-in  se você estiver usando o Visual Studio Code como seu IDE.

• Se você interrompeu qualquer processo local do ambiente de execução canister em execução no computador local.

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

Crie um novo projeto

Como discutido em Quick start, os dapps no Internet Computer começam como projetos que você cria. Você pode criar projetos usando a interface executável da linha de comando ( CLI - command-line interface no original) dfx .

Para examinar mais de perto os arquivos e pastas incluídos em um projeto padrão, vamos criar um novo projeto para trabalhar.

Para criar um novo projeto:

1. Abra um terminal shell no computador local, se você ainda não tiver um aberto.

2. Navegue até a pasta que você está usando para seus projetos do Internet Computer, se estiver usando uma pasta de trabalho separada.

3. Crie um novo projeto executando o seguinte comando:

dfx new explore_hello

O comando dfx new explore_hello cria um novo projeto explore_hello, incluindo uma estrutura de diretório padrão sob o novo nome do projeto e um novo repositório Git para o mesmo. Se você tem node.js instalado localmente, a criação de um novo projeto também adiciona alguns códigos e dependências de front-end ao modelo.

Para garantir que os nomes dos projetos sejam válidos quando usados em JavaScript, Motoko e outros contextos, você deve usar apenas caracteres alfanuméricos e sublinhados. Você não pode incluir traços ou caracteres especiais.

1. Veja a estrutura de diretórios padrão executando o seguinte comando:

ls -l explore_hello

Por padrão, a estrutura do diretório do projeto inclui pelo menos um subdiretório de origem, um modelo de arquivo README.md e um arquivo padrão dfx.json de configuração.

Dependendo se você tem node.js instalado, seu diretório de projeto pode incluir alguns ou todos os seguintes arquivos:

explore_hello/

├── README.md      # documentação padrão do projeto

├── dfx.json       # arquivo de configuração do projeto

├── node_modules   # bibliotecas para desenvolvimento frontend

├── package-lock.json

├── package.json

├── src            # diretório de arquivos de origem

│   ├── explore_hello

│   │   └── main.mo

│   └── explore_hello_assets

│       ├── assets

│       │   ├── logo.png

│       │   ├── main.css

│       │   └── sample-asset.txt

│       └── src

│           ├── index.html

│           └── index.js

└── webpack.config.js

No mínimo, o diretório padrão do projeto inclui as seguintes pastas e arquivos:

Um arquivo padrão README para documentar seu projeto no repositório.

Um arquivo padrão dfx.json de configuração para definir opções configuráveis para o seu projeto.

Um diretório padrão src para todos os arquivos de origem exigidos pelo seu dapp.

O diretório padrão src inclui um arquivo modelo  main.mo que você pode modificar ou substituir para incluir sua lógica de programação principal.

Como este tutorial se concentra no básico para começar, você só usará o arquivo main.mo . Se você tem o node.js instalado, o diretório do projeto inclui arquivos e diretórios adicionais que você pode usar para definir a interface do front-end do seu dapp. O desenvolvimento do front-end e os arquivos de modelo na pasta de assets são discutidas um pouco mais tarde.

Revise a configuração padrão

Por padrão, a criação de um novo projeto adiciona alguns arquivos de modelo ao diretório do projeto. Você pode editar esses arquivos de modelo para personalizar as configurações do seu projeto e incluir seu próprio código para acelerar o ciclo de desenvolvimento.

Para revisar o arquivo de configuração padrão do seu projeto:

1. Abra um shell de terminal no computador local, se você ainda não tiver um aberto.

2. Mude para o diretório do projeto, executando o seguinte comando:
   

cd explore_hello

1. Abra o arquivo dfx.json  de configuração em um editor de texto para revisar as configurações padrão.

Pode ficar semelhante a isto.

Vamos dar uma olhada em algumas das configurações padrão.

• A seção settings especifica o nome do módulo WebAssembly para que seu projeto explore_hello  seja explore_hello.

• A chave canisters.explore_hello especifica que o programa principal a ser compilado está localizado no caminho especificado pelo main definindo, neste caso, src/explore_hello/main.mo e o type de configuração indica que este é um programa motoko.

• A chave canisters.explore_hello_assets especifica detalhes de configuração sobre os ativos de front-end para este projeto. Vamos pular isso por enquanto.

• A configuração dfx é usada para identificar a versão do software usado para criar o projeto.

• A seção networks especifica informações sobre as redes às quais você se conecta. As configurações padrão vinculam o ambiente de execução do canister local ao endereço do host local 127.0.0.1 e porta 8000.

Se você tiver acesso a outros provedores de rede do Internet Computer, a seção  networks  pode incluir aliases de rede e URLs para conectar-se a esses provedores.

Você pode deixar as configurações padrão como estão.

1. Feche o arquivo dfx.json  para continuar.

Revise o código padrão do programa

Novos projetos sempre incluem um  arquivo de código fonte modelo main.mo. Você pode editar este arquivo para incluir seu próprio código para acelerar o ciclo de desenvolvimento.

Vamos dar uma olhada no programa de amostra no arquivo de modelo padrão main.mo  como ponto de partida para criar um dapp simples usando a linguagem de programação Motoko.

Revise o programa de amostra padrão para o seu projeto:

1. Verifique se você ainda está no diretório do projeto executando o seguinte comando:

pwd

1. Abra o arquivo src/explore_hello/main.mo  em um editor de texto e revise o código no modelo:

actor {

    public func greet(name : Text) : async Text {

        return "Hello, " # name # "!";

    };

};

Vamos dar uma olhada em alguns elementos-chave deste programa:

• Você pode notar que este código de amostra define um actor em vez de uma função main, que algumas linguagens de programação exigem. Para Motoko, a função  main está implícita no próprio arquivo.

• Embora o tradicional programa "Hello, World!" ilustre como você pode imprimir uma string usando uma função print ou println, esse programa tradicional não representaria um caso de uso típico para os dapps Motoko executados no Internet Computer.

• Em vez de uma função de impressão, este programa de amostra define um actor com uma função pública greet que recebe um name como argumento com um tipo  Text.

• O programa, então, usa a  palavra-chave async para indicar que o programa retorna uma mensagem assíncrona que consiste em uma sequência de texto concatenada usando "Hello, ",  operador #, o argumento name e o "!".

Exploraremos códigos que usam  objetos actor  e mensagens assíncronas um pouco mais tarde. Por enquanto, você pode continuar indo para a próxima seção.

   3.  Feche o  arquivo main.mo para continuar.

Inicie o ambiente de execução do canister local

Antes de implantar o projeto padrão, você precisa se conectar ao ambiente de execução do canister local ou à rede principal da blockchain do Internet Computer.

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

Para iniciar o ambiente de execução do canister local:

1. Abra uma nova janela do terminal ou uma nova guia do terminal no seu computador local.

2. Navegue até o diretório raiz do seu projeto, se necessário.

• Você deve ter agora dois terminais abertos.

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

1. Inicie o ambiente de execução do canister local executando o seguinte comando:

dfx start

Dependendo da plataforma e das configurações de segurança local, você poderá ver um aviso exibido. Se você for solicitado a permitir ou negar conexões de rede recebidas, clique em Permitir.

Depois de iniciar o ambiente de execução do canister local, você tem um terminal que exibe mensagens sobre operações de rede e outro para executar tarefas relacionadas ao projeto.

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

Registre identificadores de canister

Depois de se conectar ao ambiente de execução do canister local, você pode se registrar na rede para gerar um sistema exclusivo e específico da rede identificadores de canister para o seu projeto.

No Início do Quick start, esta etapa foi realizada como parte do fluxo de trabalho  dfx deploy. Este tutorial demonstra como executar cada uma das operações de forma independente.

Para registrar identificadores de canister para a rede local:

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

2. Registre identificadores de canister exclusivos para os canisters no projeto executando o seguinte comando:

dfx canister create --all

O comando exibe os identificadores de canister específicos da rede para os canisters definidos no arquivo de configuração dfx.json.

Creating a wallet canister on the local network.

The wallet canister on the "local" network for user "pubs-id" is "rwlgt-iiaaa-aaaaa-aaaaa-cai"

Creating canister "explore_hello"...

"explore_hello" canister created with canister id: "rrkah-fqaaa-aaaaa-aaaaq-cai"

Creating canister "explore_hello_assets"...

"explore_hello_assets" canister created with canister id: "ryjl3-tyaaa-aaaaa-aaaba-cai"

Como você está conectado ao ambiente de execução do canister local, esses identificadores do canister são válidos apenas localmente e são armazenados para o projeto no arquivo .dfx/local/canister_ids.json.

Por exemplo:

{

  "explore_hello": {

    "local": "rrkah-fqaaa-aaaaa-aaaaq-cai"

  },

  "explore_hello_assets": {

    "local": "ryjl3-tyaaa-aaaaa-aaaba-cai"

  }

}

Construa o dapp

Agora que você explorou as configurações padrão e o código do programa e iniciou o ambiente de execução do canister local, vamos compilar o programa padrão em um módulo executável do WebAssembly.

Para criar o executável do programa:

1. No shell do terminal no seu computador local, navegue até o seu diretório do projeto explore_hello.  Você deve executar o comando dfx build de dentro da estrutura do diretório do  projeto.

2. Crie o canister executável, executando o seguinte comando:

dfx build

Você deve ver uma saída semelhante à seguinte:

Building canisters...

Building frontend...

Como você está conectado ao ambiente de execução do canister local, o comando dfx build adiciona o diretório canisters sob o diretório .dfx/local/ para o projeto.

1. Verifique se o diretório .dfx/local/canisters/explore_hello criado pelo comando dfx build  contém o WebAssembly e os arquivos de aplicativos relacionados executando o seguinte comando.

ls -l .dfx/local/canisters/explore_hello/

Por exemplo, o comando retorna uma saída semelhante à seguinte:

-rw-r--r--  1 pubs  staff     178 Apr  6 14:25 explore_hello.d.ts

-rw-r--r--  1 pubs  staff      41 Apr  6 14:25 explore_hello.did

-rw-r--r--  1 pubs  staff     155 Apr  6 14:25 explore_hello.did.js

-rw-r--r--  1 pubs  staff     142 Apr  6 14:25 explore_hello.js

-rw-r--r--  1 pubs  staff  157613 Apr  6 14:25 explore_hello.wasm

O diretório canisters/explore_hello contém os seguintes arquivos chave:

• O arquivo explore_hello.did contém uma descrição da interface para o seu dapp principal.

• O arquivo  explore_hello.did.js contém uma representação JavaScript da interface do canister para as funções no seu dapp.

• O arquivo explore_hello.js contém uma representação JavaScript da interface do canister para o seu dapp.

• O arquivo explore_hello.wasm contém o WebAssembly compilado para os ativos usados no seu projeto.

1. Verifique se uma nova pasta foi criada, src/declarations.

Esta pasta incluirá cópias das pastas .dfx/local, exceto pelo wasm. Eles não contêm segredos e recomendamos que você confirme esses arquivos junto com o restante do código-fonte.

Implante o projeto localmente

Você viu que o comando dfx build cria vários artefatos em um diretório canisters para o seu projeto. Os módulos WebAssembly e o canister_manifest.json  são necessários para que o arquivo seja implantado na rede de Internet Computer.

Para implantar no ambiente de execução do canister local:

1. Em um shell de terminal no seu computador local, navegue até o diretório explore_hello  do projeto.

2. Implante seu projeto explore_hello na rede local executando o seguinte comando:

dfx canister install --all

O comando exibe uma saída semelhante à seguinte:

Installing code for canister explore_hello, with canister_id rrkah-fqaaa-aaaaa-aaaaq-cai

Installing code for canister explore_hello_assets, with canister_id ryjl3-tyaaa-aaaaa-aaaba-cai

Authorizing our identity (pubs-id) to the asset canister...

Uploading assets to asset canister...

  /index.html 1/1 (480 bytes)

  /index.js 1/1 (296836 bytes)

  /main.css 1/1 (484 bytes)

  /sample-asset.txt 1/1 (24 bytes)

  /logo.png 1/1 (25397 bytes)

  /index.js.map 1/1 (964679 bytes)

  /index.js.LICENSE.txt 1/1 (499 bytes)

1. Execute o comando dfx canister call e especifique o dapp e a função a ser chamada executando o seguinte comando:

dfx canister call explore_hello greet '("everyone": text)'

Este comando especifica:

• explore_hello como o nome do canister ou dapp que você quer chamar.

• greet como o método específico ou função que você deseja chamar.

• everyone como o argumento a passar para a função greet.

1. Verifique se o comando exibe o valor de retorno da função greet.

Por exemplo:

("Hello, everyone!")

Veja o frontend padrão

Se você tem o  node.js instalado no seu ambiente de desenvolvimento, seu projeto inclui um exemplo simples de front-end que usa um modelo de arquivo JavaScript index.js para acessar o dapp  explore_hello em um navegador.

Para explorar o modelo de front-end padrão:

1. Abra um shell de terminal no computador local, se você ainda não tiver um aberto, e navegue até o seu diretório explore_hello do projeto.

2. Abra o arquivo src/explore_hello_assets/src/index.js em um editor de texto e revise o código no script de modelo:
   

import { explore_hello } from "../../declarations/explore_hello";



document.getElementById("clickMeBtn").addEventListener("click", async () => {

  const name = document.getElementById("name").value.toString();

  // Interage com explore_hello actor, chamando o método greet

  const greeting = await explore_hello.greet(name);



  document.getElementById("greeting").innerText = greeting;

});

O modelo index.js importa um agente explore_hello de nosso recém-criado diretório declarations. O agente é configurado automaticamente para interagir com a interface que criamos Main.mo, e faz chamadas para o nosso canister usando um AnonymousIdentity quando o usuário clica no botão greeting.

Este arquivo funciona em conjunto com o modelo do arquivo index.html para exibir uma página HTML com um ativo de imagem, um campo de entrada e um botão para a função greet.

1. Feche o arquivo index.js para continuar.

2. Veja os ativos de front-end criados para o projeto executando o seguinte comando:
   

ls -l .dfx/local/canisters/explore_hello_assets/

O comando exibe uma saída semelhante à seguinte:

drwxr-xr-x  9 pubs  staff     288 Apr  6 14:25 assets

-r--r--r--  1 pubs  staff    2931 Dec 31  1969 assetstorage.did

-r--r--r--  1 pubs  staff  265823 Dec 31  1969 assetstorage.wasm

-rw-r--r--  1 pubs  staff    3651 Apr  6 14:25 explore_hello_assets.d.ts

-rw-rw-rw-  1 pubs  staff    2931 Dec 31  1969 explore_hello_assets.did

-rw-r--r--  1 pubs  staff    4236 Apr  6 14:25 explore_hello_assets.did.js

-rw-r--r--  1 pubs  staff     149 Apr  6 14:25 explore_hello_assets.js

-rw-rw-rw-  1 pubs  staff  265823 Dec 31  1969 explore_hello_assets.wasm

Esses arquivos foram gerados automaticamente pelo comando dfx build usando módulos de nós e o arquivo modelo index.js .

1. Inicie um servidor de desenvolvimento com npm start.

2. Abra um navegador e navegue para rede local e na porta número —+127.0.0.1:8080

3. Verifique se você vê a página HTML do aplicativo de amostra.

Por exemplo:

1. Digite uma saudação e clique em Click Me  para o retorno de  uma saudação.

Por exemplo:

Interrompa o ambiente de execução do canister local

Depois de terminar de testar o seu dapp, você pode parar o ambiente de execução do canister local para que ele não continue sendo executado em segundo plano.

Para interromper o ambiente de execução do canister 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 canister local e interrompe-o executando o seguinte comando:
   

dfx stop

Este artigo foi escrito por Internet Computer e traduzido por Adriano P. de Araujo. O original em inglês pode ser encontrado aqui.