Query using an actor

In the Quick start, you had your first look at a simple program for the Internet Computer involving an actor object and asynchronous messaging. As the next step in learning to write programs that take advantage of actor-based messaging, this tutorial illustrates how to modify a traditional Hello, World! program to define an actor, then deploy and test your program on a local network.

Before you begin

Before starting the tutorial, verify the following:

You have downloaded and installed the DFINITY Canister SDK package as described in Download and install.
You have stopped any Internet Computer network processes running on the local computer.

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:
```
cd actor_hello
```

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:

Open the dfx.json configuration file in a text editor.
Check the default settings for the actor_hello project.
Notice that the names and paths to source and output files all use the actor_hello project name.

For example, the default canister name is actor_hello and the default path to the main program file is src/actor_hello/main.mo.

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.json configuration file. If you plan to use the default directory and file names, no changes are necessary.

Remove all of the actor_hello_assets configuration settings from the file.

The sample program for this tutorial doesn’t use any front-end assets, so you can remove those settings from the configuration file.

For example, the configuration file looks like this after you remove the actor_hello_assets section:

{
  "canisters": {
    "actor_hello": {
      "main": "src/actor_hello/main.mo",
      "type": "motoko"
    }
  },
  "defaults": {
    "build": {
      "packtool": ""
    }
  },
  "dfx": "0.7.2",
  "networks": {
    "local": {
      "bind": "127.0.0.1:8000",
      "type": "ephemeral"
    }
  },
  "version": 1
}

Save your changes and close the file to continue.

Modify the default program

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!" program that uses an actor.

To modify the default template source code:

Change to the source code directory for your project by running the following command:
```
cd src/actor_hello
```
Open the template main.mo file in a text editor and delete the existing content.

The next step is to write a program that prints a statement like the traditional "Hello, World!" sample program. To compile the program for the Internet Computer, however, your program must include an actor object with a public function.
Copy and paste the following sample code into the main.mo file:
```
import Debug "mo:base/Debug";
actor HelloActor {
   public query func hello() : async () {
      Debug.print ("Hello, World from DFINITY \n");
   }
};
```
Let’s take a closer look at this simple program:
- The program imports a Debug module to provide the print functionality.
- The program uses the public query func to define a query method because, in this case, the actor_hello program doesn’t make any changes to the state of the canister or perform any operations that would update the data you are accessing.
For more information about using a query call, see query calls in Canisters include both program and state.
Save your changes and close the main.mo file.

Build the program with a local identifier

You are probably only going to use this simple program for some local testing. Therefore, there’s no need to reserve a unique canister identifier on the Internet Computer network to hold the compiled output for the program.

In this scenario, you can compile the program without connecting to an Internet Computer network at all. Instead, the dfx build command creates a local, hard-coded canister identifier for you to use.

You can use this local identifier while you are testing your program or any time you want to compile your program without starting the Internet Computer replica process locally or connecting to a replica on a remote subnet.

To build the program executable:

Navigate back to the root of your project directory.
Build the program with a locally-defined identifier by running the following command:
```
dfx build --check
```
The --check option enables you to build a project locally to verify that it compiles and to inspect the files produced. Because the dfx build --check command only generates a temporary identifier, you should see output similar to the following:
```
Building canisters to check they build ok. Canister IDs might be hard coded.
Building canisters...
```
If the program compiles successfully, you can inspect the output in the default .dfx/local/canisters directory and .dfx/local/canisters/actor_hello/ subdirectory.

For example, you might use the tree command to review the files created:
```
tree .dfx/local/canisters
```
The command displays output similar to the following

.dfx/local/canisters
├── actor_hello
│   ├── actor_hello.d.ts
│   ├── actor_hello.did
│   ├── actor_hello.did.js
│   ├── actor_hello.js
│   └── actor_hello.wasm
└── idl

2 directories, 5 files

Deploy the project

You cannot deploy the output from the dfx build --check command to any Internet Computer network. If you wanted to deploy this project, you would need to do the following:

Connect to the Internet Computer network.
Register a network-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 the Internet Computer network either running locally in your development environment or running remotely on a subnet that you can access. After you connect to a local or remote network, you must also generate a unique, network-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 Internet Computer network on your local computer by running the following command:
```
dfx start --background
```
For this tutorial, you can use the --background option to start the Internet Computer network 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 Internet Computer network 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"

The dfx canister create command also stores the network-specific canister identifier in a canister_ids.json file in the .dfx/local directory.

For example:

{
  "actor_hello": {
    "local": "rrkah-fqaaa-aaaaa-aaaaq-cai"
  }
}

Deploy your actor_hello project on the local network 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 program deployed as a canister on your local Internet Computer network and can test your program by using the dfx canister call command.

To test the program you have deployed on the local network:

Use dfx canister call to call the hello function by running the following command:
```
dfx canister call actor_hello hello
```
Verify that the command returns the text specified for the hello function along with a checkpoint message in the terminal running the local network process.

For example, the program 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 network in a separate terminal instead of in the background, the "Hello, World from DFINITY" message is displayed in the terminal that displays network activity.

Stop the local network

After you finish experimenting with your program, you can stop the local Internet Computer network so that it doesn’t continue running in the background.

To stop the local network:

In the terminal that displays network operations, press Control-C to interrupt the local network process.
Stop the Internet Computer network by running the following command:
```
dfx stop
```