Administrando Cânisters

Se você experimentou usar o SDK seguindo os tutoriais desta seção ou copiando exemplos do repositório de exemplos, você já está familiarizado com como construir e implantar programas como cânisters. Esta seção fornece informações adicionais sobre o ciclo de vida e como gerenciar os cânisters.

Obtenção de um identificador de cânisters

Dependendo de seu fluxo de trabalho de desenvolvimento preferido, você pode obter um identificador único para seu cânister, antes ou depois de ter um programa pronto para compilar. Por exemplo, se você quiser reservar um identificador único para seu cânister em uma sub-rede antes de ter escrito qualquer código, você pode fazê-lo executando o comando dfx cânister create. Este comando essencialmente cria um espaço vazio para colocar o cânister, no qual você poderá instalar seu código mais tarde. O cânister resultante obterá um identificador único.

Para obter um identificador único para um cânister:

1° Abra uma nova janela de terminal ou aba em seu computador.

2° Crie um novo projeto para o cânister que você planeja criar executando um comando semelhante ao seguinte:

dfx new YOUR-PROJECT-NAME

Note que o nome que você usa para o projeto também é usado como nome do cânister, por padrão.

3° Mude para seu novo diretório de projetos.

4° Abra o arquivo de configuração dfx.json e defina o host e a porta para o ambiente de execução do cânister que você deseja usar (por exemplo, a blockchain IC).

Se você estiver usando uma implementação local, você pode pular esta etapa.

Você também pode, opcionalmente, mudar os nomes de seus cânisters ou adicionar configurações de cânister ao arquivo de configuração se quiser criar identificadores para qualquer cânister adicional que você achar necessário antes de compilar o código.

5° Inicie o ambiente local de execução de cânisters, se necessário, executando seguinte

comando:

dfx start --background

Na maioria dos casos, esta etapa só é necessária se você estiver operando os cânister localmente.

Se você estivesse registrando os cânisters para executar em um ambiente de execução remota, por exemplo, a blockchain IC, você incluiria a opção de linha de comando --network para executar tarefas no ambiente especificado sob este parâmetro.

6° Registre identificadores únicos para os cânisters definidos no dfx.json, executando o seguinte comando:

dfx canister create --all

O comando cria o diretório .dfx/local e adiciona o arquivo canister_ids.json a esse diretório para o projeto.

Construir um cânister com um identificador local

Após ter escrito o código fonte para seu projeto, você precisa compilá-lo em um módulo WebAssembly antes de implementá-lo como um cânister.

Se você estiver compilando seu projeto apenas para depuração local, você pode gerar um identificador definido localmente para seu projeto.

Para gerar um identificador definido localmente:

1° Crie um projeto com as configurações e a lógica do programa para atender às suas necessidades.

2° Inicie o ambiente local de execução do cânister, se necessário.

Se você estivesse compilando cânister para executar em um ambiente de execução remota, por exemplo, a blockchain IC, você incluiria a opção de linha de comando --network para executar tarefas no ambiente especificado sob este parâmetro.

3° Gerar identificadores locais codificados para os cânisters definidos no dfx.json, executando o seguinte comando:

dfx build --check

Observe que você deve registrar identificadores de cânister únicos para substituir seu identificador definido localmente antes de poder implantar o projeto na blockchain IC.

Implementando cânisters

Após ter compilado um programa, você pode instalar o código compilado em um cânister rodando em um ambiente local de execução de recipientes ou na blockchain IC.

O identificador do cânister que foi criado com antecedência ou durante o processo de construção determina onde seu código é instalado durante a implantação.

Para implantar o código pela primeira vez:

1° Abra um novo terminal e navegue até seu diretório de projetos.

2° Inicie o ambiente local de execução dos cânisters, se necessário.

Na maioria dos casos, esta etapa só é necessária se você estiver executando os cânister localmente.

Se você estivesse registrando os cânisters para executar em um ambiente de execução remota, por exemplo, a blockchain IC, você incluiria a opção de linha de comando --network para executar tarefas no ambiente especificado sob este parâmetro.

3° Verifique se você tem identificadores de cânisters para todas os cânisters que você deseja implantar.

4° Implemente todos os cânisters executando o seguinte comando:

dfx canister install --all

Procure um ID cânister

Todos os cânister têm identificadores únicos. Muitas vezes é preciso usar esses identificadores para interagir com o cânister. Por exemplo, se você quiser acessar o cânister frontal para uma dapp ou interagir com um serviço usando a interface web do Candidato, você deve especificar o identificador apropriado do cânister.

Como os identificadores são específicos do ambiente onde os cânister são instalados, os arquivos usados para armazenar as informações estão em diferentes diretórios. Por exemplo, os identificadores de um cânister implantado localmente estão localizados no arquivo .dfx/local/canister_ids.json do projeto.

Você pode procurar o identificador do cânister para qualquer cânister específico executando o comando dfx canister id. Por exemplo, para procurar o identificador do cânister para o cânister de pesquisa implantado no ambiente local de execução do cânister, você poderia executar o seguinte comando:

dfx canister id lookup

Para procurar o identificador do mesmo cânister implantado no ambiente especificado pelo ic aliás, você executaria o seguinte comando:

dfx canister --network=ic id lookup

Adicionar uma arteira para os cânisters existentes

Quando você está fazendo desenvolvimento local, a criação de um novo projeto cria automaticamente uma carteira padrão para você usar com os cânisters naquele projeto. Se você quiser adicionar uma carteira para projetos com cânisters que você tenha criado anteriormente, você pode forçar a dfx a gerar um, dando alguns passos manuais.

Para adicionar uma carteira para uso com uma lata existente:

1° Abra um terminal e navegue até seu diretório de projetos.

2° Pare o ambiente local de execução do cânister, se necessário, executando o seguinte comando:

dfx stop

3° Excluir o diretório .dfx.

4° Inicie a rede local do ambiente de execução do cânister executando o seguinte comando:

dfx start --clean

Reinstalar um cânister

Durante o ciclo de desenvolvimento, você pode querer instalar, depois substituir seu programa à medida que você o depura e o melhora.

Neste cenário, você pode querer manter o identificador do cânister que você registrou, mas sem preservar nenhum código ou estado do cânister. Por exemplo, seu cânister pode ter apenas dados de teste que você não quer manter ou pode ter decidido mudar o programa completamente, mas quer reinstalar sob um identificador de cânister que você usou para instalar um programa anterior.

Para reinstalar um cânister:

1° Abra um novo terminal e navegue até seu diretório de projetos.

2° Inicie o ambiente local de execução de cânisters, se necessário.

Na maioria dos casos, esta etapa só é necessária se você estiver executando os cânisters localmente.

Se você estivesse registrando os cânister para executar em um ambiente de execução remota, por exemplo, a blockchain IC, você incluiria a opção de linha de comando --network para executar tarefas no ambiente especificado sob este parâmetro.

3° Verifique se você tem identificadores de cânisters para todos os cânisters que você deseja reimplantar.

4° Reimplante todos os cânisters executando o seguinte comando:

dfx canister install --all --mode reinstall

Observe que você pode usar o modo de reinstall para substituir qualquer cânister, independentemente de o cânister ter código ou estado associado a ele.

Defina uma Identidade para possuir um Cânister

Na maioria dos casos, uma identidade de usuário default é criada automaticamente para você na primeira vez que você executar o comando dfx canister create. Esta identidade padrão consiste no par de chaves públicas e privadas geradas para sua conta de usuário local. Normalmente, esta identidade default é também o proprietário padrão de todos os projetos que você cria e de todas os cânisters que você implanta. Você pode, entretanto, criar e usar proativamente identidades de sua escolha para contornar a identidade default do usuário.

Como exemplo, o seguinte cenário ilustra a criação de uma identidade de registered_owner que é então usada para registrar, construir, implantar e chamar o projeto de pubs.

Para definir uma identidade para um projeto:

1° Crie um novo projeto executando o seguinte comando:

dfx new pubs

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

cd pubs

3° Inicie o ambiente local de execução do cânister em segundo plano executando o seguinte comando:

dfx start --background

4° Crie uma nova identidade de registered_owner, executando a seguinte vírgula

dfx identity new registered_owner

5° Defina o contexto do usuário ativo para usar a identidade do registered_owner, executando o seguinte comando:

dfx identity use registered_owner

6° Registrar, construir e distribuir cânisters para o projeto executando os seguintes comandos:

dfx canister create --all
dfx build --all
dfx canister install --all

Estes comandos são executados utilizando a identidade do_registered_owner, fazendo desse usuário o proprietário dos cânisters implantados.

7° Chame a função de greet para verificar um desdobramento bem sucedido executando o seguinte comando:

dfx canister call pubs greet '("Sam")'

Gerenciando o estado de funcionamento de um cânister

Depois que você implanta um cânister, ele pode começar a receber e processar pedidos de usuários e de outros cânisters. Os cânister que estão disponíveis para enviar solicitações e receber respostas são consideradas em estado de Execução.

Embora os cânister sejam normalmente colocados no estado de Execução por padrão, há casos em que você pode querer parar temporária ou permanentemente um cânister. Por exemplo, você pode querer parar um cânister antes de atualizá-lo. A parada de um cânister ajuda a garantir o manuseio adequado de quaisquer mensagens que estejam em andamento e que precisem ou correr até a conclusão ou ser roladas para trás. Você também pode querer parar um cânister para limpar sua fila de mensagens como pré-requisito para apagar o cânister.

Você pode verificar o status atual de todos os cânisters ou de um cânister especificado executando o comando dfx canister status. Por exemplo, para ver o status de todos os cânisters em execução no ambiente local de execução de cânisters, você executaria o seguinte comando:

dfx canisterstatus --all

Este comando retorna uma saída semelhante à seguinte se os cânisters estiverem atualmente em funcionamento:

Canister status_check's status is Running.
Canister status_check_assets's status is Running.

Você pode parar os cânisters que estão atualmente em funcionamento executando o comando dfx canister stop.

dfx canister stop --all

Este comando exibe resultados semelhantes aos seguintes:

Stopping code for canister status_check, with canister_id 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
Stopping code for canister status_check_assets, with canister_id cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q

Se você voltasse a executar o comando dfx canister status, você poderia ver um status de Stopped indicando que não havia mensagens pendentes que precisavam ser processadas ou um status de Stopping indicando que havia mensagens a bordo que precisavam ser endereçadas.

Para reiniciar um cânister - por exemplo, após um upgrade bem sucedido do recipiente - você pode executar o comando dfx canister start. Por exemplo, para reiniciar todos os cânisters, você executaria o seguinte comando:

dfx canister start --all

Este comando exibe resultados semelhantes aos seguintes:

Starting code for cânister status_check, with cânister_id 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
Starting code for cânister status_check_assets, with cânister_id cxeji-wacaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q

Atualizanado um Cânister

Ao contrário de um cânister reinstalado que preserva o identificador do cânister, mas sem estado, uma atualização do cânister permite preservar o estado de um cânister implantado, e alterar o código.

Por exemplo, suponha que você tenha um dapp que gerencie perfis profissionais e conexões sociais. Se você quiser adicionar um novo recurso ao dapp, você precisa ser capaz de atualizar o código do cânister sem perder nenhum dos dados armazenados anteriormente. Uma atualização do cânister permite atualizar os identificadores de cânister existentes com mudanças de programa sem perder o estado do programa.

Para preservar o estado quando você estiver atualizando um cânister escrito em Motoko, certifique-se de usar a palavra-chave stable para identificar as variáveis que você deseja preservar. Para mais informações sobre como preservar o estado das variáveis em Motoko, veja Variáveis estáveis e métodos de atualização. Se você estiver atualizando um cânister escrito em Rust, você deve usar as funções de pre_upgrade e post_upgrade como ilustrado no exemplo de armazenamento de ativos do Rust CDK para garantir que os dados sejam preservados corretamente após uma atualização do cânister

Para atualizar um cânister:

1° Abra um novo terminal e navegue até seu diretório de projetos.

2° Inicie o ambiente local de execução de cânisters, se necessário.

Na maioria dos casos, esta etapa só é necessária se você estiver executando os cânisters localmente.

Se você estivesse registrando os cânisters para executar em um ambiente de execução remota, por exemplo, a blockchain IC, você incluiria a opção de linha de comando --network para executar tarefas no ambiente especificado sob este parâmetro.

3° Verifique se você tem identificadores de cânisters para todos os cânisters que você deseja atualizar.

4° Observe que seu programa deve identificar as variáveis para as quais deseja manter o estado, usando a palavra-chave stable na declaração da variável.

Para mais informações sobre a declaração de variáveis estáveis, consulte o Guia de Linguagem de Programação Motoko.

5° Atualize todos os cânisters executando o seguinte comando:

dfx canister install --all --mode upgrade

Excluir um cânister

Se você quiser excluir permanentemente um cânister específico ou todos os cânisters para um projeto específico em um determinado projeto (seja local ou remoto), você pode fazê-lo executando o comando dfx canister delete.

A exclusão de um cânister remove o identificador, o código e o estado do cânister. Antes de apagar um cânister, entretanto, você deve primeiro parar o cânister para apagar qualquer pedido ou resposta de mensagem pendente.

Para apagar todos os cânister de um projeto:

1° Abra um novo terminal e navegue até seu diretório de projetos.

2° Inicie o ambiente local de execução de cânisters, se necessário.

Na maioria dos casos, esta etapa só é necessária se você estiver executando os cânisters localmente.

Se você estivesse apagando cânisters para executar em um ambiente de execução remota, por exemplo, a blockchain IC, você incluiria a opção de linha de comando --network para executar tarefas no ambiente especificado sob este parâmetro.

3° Verifique o status dos cânisters do projeto rodando no ambiente local de execução do cânister executando o seguinte comando:

dfx canister status --all

4° Pare todos os canisters do projeto executando o seguinte comando:

dfx canister stop --all

5° Apague todos os canisters do projeto executando o seguinte comando:

dfx canister delete --all

Artigo escrito por Severin Siffert e traduzido para o português por Rafael Ojeda

Você pode encontrar o texto original aqui