Query using an actor
In the Quick start, you had your first look at a simple canister for the Internet Computer involving an actor object and asynchronous messaging. As the next step in learning to write canisters that take advantage of actor-based messaging, this tutorial illustrates how to modify a traditional
Hello, World! canister to define an actor, then deploy and test your canister on a local canister execution environment.
Before you begin
Before starting the tutorial, verify the following:
You have downloaded and installed the SDK package as described in Download and install.
You have stopped any local canister execution environment processes
This tutorial takes approximately 20 minutes to complete.
Create a new project
To create a new project for this tutorial:
Open a terminal shell on your local computer, if you don’t already have one open.
Change to the folder you are using for your Internet Computer projects, if you are using one.
Create a new project by running the following command:
dfx new actor_hello
Change to your project directory by running the following command:
Modify the default configuration
In the Exploring the default project tutorial, you saw that creating a new project adds a default
dfx.json configuration file to your project directory. In this tutorial, you need to modify a few of the default settings to reflect your project.
To modify the
dfx.json configuration file:
dfx.jsonconfiguration file in a text editor.
Check the default settings for the
Notice that the names and paths to source and output files all use the
For example, the default canister name is
actor_helloand the default path to the main code file is
You can rename any of these files or directories. If you make any changes, however, be sure that the names you use for your files and directories on the file system match the names you specify in the
dfx.jsonconfiguration file. If you plan to use the default directory and file names, no changes are necessary.
Remove all of the
actor_hello_assetsconfiguration settings from the file.
The sample canister for this tutorial doesn’t use any frontend assets, so you can remove those settings from the configuration file.
For example, the configuration file looks like this after you remove the
Save your changes and close the file to continue.
Modify the default canister
In the Exploring the default project tutorial, you saw that creating a new project creates a default
src directory with a template
main.mo file. In this tutorial, you modify the template code to create a simple "Hello, World!" canister. by defining an actor in Motoko. In Motoko, an Internet Computer canister is representeded as a Motoko actor.
To modify the default template source code:
Change to the source code directory for your project by running the following command:
Open the template
main.mofile in a text editor and delete the existing content.
The next step is to write a canister that prints a statement like the traditional "Hello, World!" sample canister. To compile the canister for the Internet Computer, however, your Motoko code must define an
Copy and paste this code into the
Let’s take a closer look at this Motoko actor defining our canister:
The code imports a
Debugmodule to provide the
The actor uses the
public query funcdeclaration to define an Internet Computer query method. Our method doesn’t need to make any permanent changes to the state of the actor. Declaring it as a query means that any changes it does make are transient and discarded after the query completes.
Save your changes and close the
Checking that the canister builds
Usually, in order to build a canister, it’s necessary to first reserve a unique canister identifier on the Internet Computer blockchain mainnet.
However, it’s also possible to compile your program without connecting to the Internet Computer blockchain mainnet at all. The
dfx build --check command uses a temporary, hard-coded canister identifier to accomplish this.
To check that the canister builds:
Navigate back to the root of your project directory.
Build the canister executable with a temporary, hard-coded identifier by running the following command:
dfx build --check
--checkoption enables you to build a project locally to verify that it compiles and to inspect the files produced. Because the
dfx build --checkcommand only uses a temporary identifier, you should see output similar to the following:
Building canisters to check they build ok. Canister IDs might be hard coded.
If the canister compiles successfully, you can inspect the output in the default
For example, you might use the
treecommand to review the files created:
The command displays output similar to the following
│ ├── actor_hello.d.ts
│ ├── actor_hello.did
│ ├── actor_hello.did.js
│ ├── actor_hello.js
│ └── actor_hello.wasm
2 directories, 5 files
Deploy the project
You cannot deploy the output from the
dfx build --check command to a local canister execution environment or the Internet Computer mainnet. If you wanted to deploy this project, you would need to do the following:
Connect to the either the local canister execution environment or Internet Computer mainnet.
Register a connection-specific canister identifier.
Deploy the canister.
Let’s consider these steps in a bit more detail. Before you can deploy this project, you must connect to either your local canister execution environment, provided by
dfx, or to the Internet Computer blockchain mainnet. After you connect to a local canister execution environment or Internet Computer mainnet, you must also generate a unique, connection-specific canister identifier to replace your locally-defined identifier. To see the steps involved for yourself, let’s deploy the project locally.
To deploy this project locally:
Open a terminal and navigate to your project directory, if needed.
Start the local canister execution environment on your local computer by running the following command:
dfx start --background
For this tutorial, you can use the
--backgroundoption to start the local canister execution environment as background processes. With this option, you can continue to the next step without opening another terminal shell on your local computer.
Generate a new canister identifier for your project on the local canister execution environment by running the following command:
dfx canister create actor_hello
You should see output similar to the following:
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 "actor_hello"...
"actor_hello" canister created with canister id: "rrkah-fqaaa-aaaaa-aaaaq-cai"
dfx canister createcommand also stores the connection-specific canister identifier in a
canister_ids.jsonfile in the
Build the canister by running the following command:
The command displays output similar to the following:
actor_helloproject on the local canister execution environment by running the following command:
dfx canister install actor_hello
The command displays output similar to the following:
Installing code for canister actor_hello, with canister_id rrkah-fqaaa-aaaaa-aaaaq-cai
Query the canister
You now have a canister deployed on your local canister execution environment and can test your canister by using the
dfx canister call command.
To test the canister you have deployed on the local canister execution environment:
dfx canister callto call the
hellofunction by running the following command:
dfx canister call actor_hello hello
Verify that the command returns the text specified for the
hellofunction along with a checkpoint message in the terminal running the local canister execution environment.
For example, the canister displays "Hello, World from DFINITY" in output similar to the following:
[Canister rrkah-fqaaa-aaaaa-aaaaq-cai] Hello, World from DFINITY
Note that if you are running the Internet Computer mainnet in a separate terminal instead of in the background, the "Hello, World from DFINITY" message is displayed in the terminal that displays mainnet activity.
Stop the local canister execution environment
After you finish experimenting with your canister, you can stop the local canister execution environment so that it doesn’t continue running in the background.
To stop the local canister execution environment, you can:
In the terminal used to interact with your canister, issue the command
dfx stop; or
In the terminal that displays operations from the local canister execution environment, press Control-C to interrupt that process; or
replicaprocess using commands or tools of your operating system.
Stop the local canister execution environment by running the following command: