自然数をインクリメントする

このチュートリアルでは、カウンターをインクリメントするひとつの Actor を作成し、いくつかの基本的な関数を提供するプログラムを書くことで値の永続性を説明します。

このチュートリアルでは、Actor は Counter と名付けます。このプログラムは currentValue 変数を使用して、カウンターの現在値を表す自然数を格納します。このプログラムは以下の関数呼び出しをサポートしています：

• increment 関数の呼び出しは、現在の値を更新し、1 だけ増加させます （返り値はありません）。

• get 関数呼び出しは、カウンタの現在値を照会して返します。

• set 関数呼び出しは、現在の値を引数として指定した任意の数値に更新します。

このチュートリアルでは、配置された Canister で関数を呼び出してカウンタをインクリメントする方法を簡単に説明します。カウンタ値をインクリメントしてクエリする関数を複数回呼び出すことで、変数のステート、つまり呼び出し間の変数値が永続していることを確認できます。

始める前に

チュートリアルを始める前に、以下を確認してください：

• ダウンロードとインストールの説明に従って、SDK パッケージをダウンロードし、インストールする。

• ローカルコンピューターで動作しているすべての Canister 実行環境を停止する。

このチュートリアルの所要時間は約 20分です。

新しいプロジェクトを作成する

このチュートリアルのための新しいプロジェクトを作成します：

1. ローカルコンピューターでターミナルシェルを開きます（まだ開いていない場合）。

2. Internet Computer のブロックチェーン・プロジェクトに使用しているフォルダがある場合は、そこに移動します。

3. 以下のコマンドを実行し、新しいプロジェクトを作成します：

   dfx new my_counter

   このコマンドは、あなたのプロジェクトに新しい my_counter プロジェクトを作成します。

4. 次のコマンドを実行して、プロジェクトディレクトリに移動します：

   cd my_counter

デフォルトの設定を修正する

新しいプロジェクトを作成すると、デフォルトの dfx.json 設定ファイルがプロジェクトディレクトリに追加されることはすでにおわかりいただけたと思います。このチュートリアルでは、デフォルトの設定を変更して、プロジェクトのメインプログラムに別の名前を使用するようにします。

設定ファイル dfx.json を修正するには、以下の手順に従います：

1. テキストエディタで dfx.json 設定ファイルを開き、デフォルトの main 設定を main.mo から increment_counter.mo に変更します。

   例：

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

   このチュートリアルでは、ソースファイルの名前を main.mo から increment_counter.mo に変更してどのように設定ファイル dfx.json の設定がコンパイルするソースファイルを決定するかを簡単に説明しています。

   より複雑な Dapp では、複数のソースファイルがあり、その依存関係を dfx.json 設定ファイルの設定で管理する必要があるかもしれません。このようなシナリオでは、複数の Canister とプログラムが dfx.json ファイルに定義されているため、複数のファイルに main.mo という名前を付けると混乱する可能性があります。

   それ以外の初期設定はそのままで問題ありません。

2. 変更を保存し、dfx.json ファイルを閉じて続行します。

3. ソースコードディレクトリ src にあるメインプログラムのファイル名を、設定ファイル dfx.json で指定された名前に合わせます。以下のコマンドを実行します：

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

デフォルトのプログラムを修正する

これまでのところ、プロジェクトのメインプログラムの名前を変更しただけです。次のステップは src/my_counter/increment_counter.mo ファイルにあるコードを修正して、 Counter という名前の Actor を定義し、 increment、get、set という関数を実装することです。

デフォルトのテンプレートのソースコードを変更するには、以下のようにします：

1. 必要であれば、プロジェクトディレクトリに留まっていることを確認します。

2. src/my_counter/increment_counter.mo ファイルをテキストエディタで開き、既存の内容を削除してください。

3. このコード をコピーして increment_counter.mo ファイルに貼り付けてください。

   このサンプルプログラムを詳しく見てみましょう：

   • この例では、変数 currentValue の宣言に stable キーワードが含まれており、ステート（set、increment、retrieved が可能な値）が永続することを示していることがわかります。

     このキーワードは、プログラムがアップグレードされたときに、変数の値が変更されないようにするためのものです。

   • 変数 currentValue の宣言では、その型が自然数（Nat）であることも指定されています。

   • このプログラムには、2つの更新メソッド（increment と set 関数）とひとつのクエリメソッド（get 関数）が含まれています。

   ステーブル変数とフレキシブル変数については、Motoko Programming Language Guide の Stable variables and upgrade methods を参照してください。

   クエリとアップデートの違いについては、Canisters include both program and state にある Query and update methods を参照してください。

4. 変更を保存して、ファイルを閉じて続行します。

ローカル canister 実行環境を起動する

my_counter プロジェクトをビルドする前に、Internet Computer ブロックチェーンをシミュレートするローカル Canister 実行環境か、Internet Computer ブロックチェーンメインネットに接続する必要があります。

ローカル Canister 実行環境を起動するには dfx.json ファイルが必要なので、プロジェクトのルートディレクトリにいることを確認する必要があります。このチュートリアルでは、ターミナルシェルをふたつ用意して、ひとつのターミナルでネットワーク操作を開始・確認し、もうひとつのターミナルでプロジェクトを管理できるようにします。

ローカル Canister の実行環境を起動するには、次のようにします：

1. ローカルコンピューターで新しいターミナルウィンドウまたはタブを開きます。

2. 必要であれば、プロジェクトのルートディレクトリに移動します。

   • これで、ふたつのターミナルが開いた状態になっているはずです。

   • プロジェクトディレクトリを、現在の作業ディレクトリとする必要があります。

3. 以下のコマンドを実行して、お使いのマシンのローカル Canister 実行環境を起動します：

   dfx start

   ローカルネットワークを起動すると、ターミナルにネットワーク操作に関するメッセージが表示されます。

4. ネットワーク操作を表示しているターミナルは開いたままにして、新しいプロジェクトを作成した元のターミナルをフォーカスしてください。

Dapp の登録、ビルド、デプロイ

ローカルの Canister 実行環境に接続した後、ローカルで Dapp の登録、ビルド、デプロイができます。

ローカルに Dapp をデプロイするには：

1. 必要に応じて、まだプロジェクトのルートディレクトリにいることを確認します。

2. 以下のコマンドを実行して、Dapp を登録、ビルド、デプロイしてください：

   dfx deploy

   dfx deploy コマンドの出力は、実行した操作に関する情報を表示します。

デプロイされた Canister メソッドを呼び出す

Canister のデプロイに成功したら、エンドユーザーが Canister が提供するメソッドを呼び出す様子をシミュレートしてみましょう。このチュートリアルでは、カウンターの値を問い合わせる get メソッド、呼び出されるたびにカウンターを増加させる increment メソッド、そしてカウンターを指定した任意の値に更新するための引数を渡す set メソッドを呼び出します。

デプロイされた Canister でメソッドを呼び出すテストを行うには、以下のようにします：

1. 以下のコマンドを実行して get 関数を呼び出し、デプロイされた Canister の currentValue 変数の現在値を読み取ります：

   dfx canister call my_counter get

   このコマンドは、変数 currentValue の現在値を 0 として返します：

   (0 : nat)

2. 以下のコマンドを実行して increment 関数を呼び出し、デプロイされた Canister の currentValue 変数の値をひとつ増やします：

   dfx canister call my_counter increment

   このコマンドは変数の値を増加させ、そのステートを変化させるが、結果は返しません。

3. 以下のコマンドを再実行して、デプロイされた canister の currentValue 変数の現在値を取得します：

   dfx canister call my_counter get

   このコマンドは、更新された currentValue 変数の値、1 を返します：

   (1 : nat)

4. 他のコマンドを実行して、他のメソッドを呼び出したり、異なる値を使用したりテストをしてください。

   例えば、次のようなコマンドで、カウンターの値を設定したり、戻したりしてみてください：

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

   これにより、currentValueの更新された値は987となります。追加コマンドの実行：

   dfx canister call my_counter increment
   dfx canister call my_counter get

   インクリメントされた currentValue の 988 を返します。

5. Candid UI を使用してコードをテストしてください。

   コードをテストするには、こちらに従ってください。

ローカル Canister の実行環境を停止する

Dapp のテストが終了したら、ローカル Canister 実行環境を停止して、バックグラウンドで実行し続けないようにします。

ローカル Canister の実行環境を停止するには、以下の手順に従います：

1. 操作が表示されているターミナルで、Control-C キーを押して処理を中断します。

2. 以下のコマンドを実行して、ローカル Canister の実行環境を停止します：

   dfx stop