dfx 容器
使用带有标志和子命令的 dfx canister 命令来管理容器操作以及与 Internet Computer platform 或本地容器执行环境的交互。
在大多数情况下，您在编译程序后使用 dfx canister 子命令来管理容器生命周期并执行关键任务，例如调用程序函数。
运行 dfx canister 命令的基本语法是:
dfx canister [subcommand] [flag]根据您指定的 dfx canister 子命令，可能会应用或需要其他参数、选项和标志。
要查看特定 dfx canister 子命令的帮助信息，请指定子命令和 --help 标志。
例如，要查看 dfx canister call 的帮助信息，可以运行以下命令:
dfx canister call --help有关说明使用 dfx canister 命令的参考信息和示例，请选择适当的命令。
| 命令 | 描述 |
|---|---|
调用已部署容器上的指定方法。 |
|
通过在 Internet Computer platform 或本地容器执行环境上注册容器标识符来创建新的“空”容器。 |
|
删除当前停止的容器。 |
|
|
显示指定子命令的帮助信息消息。 |
显示容器的标识符。 |
|
将编译后的代码作为容器安装在 Internet Computer platform 或本地容器执行环境中。 |
|
请求容器的调用状态。 |
|
指定要用作 Internet Computer platform 上指定容器的新控制器的身份名称或principal。 |
|
将先前签名的 |
|
在调用指定的容器标识符之前创建一个签名的 |
|
重新启动停止的容器。 |
|
请求容器的运行状态。 |
|
停止当前正在运行的容器。 |
覆盖默认部署环境
默认情况下，dfx canister 命令在 dfx.json 文件中指定的本地容器执行环境中运行。
如果您想在不更改 dfx.json 配置文件中的设置的情况下向 Internet Computer platform 或测试网发送 dfx canister 子命令，则可以使用 `-- 显式指定要连接的 URL 网络`选项。
例如，要在本地容器执行环境中为项目注册唯一容器标识符，您可以运行以下命令:
dfx canister create --all如果要在 Internet Computer platform 上为同一项目注册唯一容器标识符，可以运行以下命令:
dfx canister --network ic create --all{sdk-short-name} 带有一个别名 ic，它被配置为指向 Internet Computer platform。 您还可以将 URL 作为网络选项传递，或者您可以在 networks 配置下的 dfx.json 中配置其他别名。
为了说明，您可以使用类似于以下的命令调用在测试网上运行的容器和函数:
dfx canister --network \http://192.168.3.1:5678 call counter get请注意，您必须在容器操作（create 或 call）之前指定 --network 参数以及任何其他参数，例如容器名称（counter）和函数（`get `）。
dfx 容器调用
使用 dfx canister call 命令调用已部署容器上的指定方法。
标志
您可以在 dfx canister call 命令中使用以下可选标志。
| 标志 | 说明 |
|---|---|
|
通过轮询本地容器执行环境或Internet Computer platform，使您无需等待返回调用结果即可继续。 |
|
显示帮助信息。 |
|
使您能够向已部署的容器发送查询请求。 为了获得最佳性能，当您明确想要使用查询方法检索信息时，您应该使用此标志。 有关查询和更新调用之间差异的信息，请参阅容器包括程序和状态。 |
|
使您能够向已部署的容器发送更新请求。 默认情况下，容器调用使用更新方法。 |
|
显示版本信息。 |
选项
您可以在 dfx canister call 命令中使用以下选项。
| 选项 | 说明 |
|---|---|
|
指定显示方法返回结果时使用的输出格式。
有效值为 |
|
使用参数进行调用时指定参数的数据格式。
有效值为 |
参数
您可以为 dfx canister call 命令指定以下参数。
canister_name |
指定要调用的容器的名称。 容器名称是必需的参数，并且应该与您在 dfx.json 配置文件的 canisters 部分中为项目配置的名称匹配。 |
|---|---|
|
指定要在容器上调用的方法名称。 canister 方法是必需的参数。 |
|
指定要传递给方法的参数。
根据您的程序逻辑，参数可以是必需参数或可选参数。
如果将参数传递给容器，则可以使用 |
例子
在使用 dfx canister install 命令部署容器后，可以使用 dfx canister call 命令调用特定方法（带或不带参数）。
例如，要为 canister_name 为 counter 的容器调用 get 方法，可以运行以下命令:
dfx canister call counter get --async在此示例中，该命令包含 --async 选项以指示您要进行单独的 request-status 调用，而不是等待轮询本地容器执行环境或 Internet Computer platform 以获取结果。
当处理操作可能需要一些时间才能完成时，--async 选项很有用。
该选项使您能够继续执行其他操作，然后使用单独的 dfx canister request-status 命令检查结果。
返回的结果将显示为 IDL 文本格式。
使用 IDL 语法
您可以通过对 Text 数据类型运行类似于以下的命令来显式指定使用 IDL 语法传递参数:
dfx canister call hello greet --type idl '("Lisa")'
("Hello, Lisa!")
dfx canister call hello greet '("Lisa")' --type idl
("Hello, Lisa!")您还可以通过运行类似于以下的命令来隐式使用 IDL:
dfx canister call hello greet '("Lisa")'
("Hello, Lisa!")要使用 IDL 语法指定多个参数，请在参数之间使用逗号。 例如:
dfx canister call contacts insert '("Amy Lu","01 916-335-2042")'
dfx canister call hotel guestroom '("Deluxe Suite",42,true)'您可以通过运行类似于以下内容的命令以字节为单位传递原始数据:
dfx canister call hello greet --type raw '4449444c00017103e29883'此示例使用原始数据类型将十六进制传递给 hello 容器的 greet 函数。
dfx 容器创建
使用 dfx canister create 命令注册一个或多个容器标识符，无需编译代码。
您必须连接到本地容器执行环境或 Internet Computer platform 才能运行此命令。
请注意，您只能从项目目录结构中运行此命令。
例如，如果您的项目名称是 hello_world，那么您当前的工作目录必须是 hello_world 顶级项目目录或其子目录之一。
第一次运行 dfx canister create 命令注册标识符时，您的公钥/私钥对凭据将用于创建 default 用户身份。
default 用户的凭据从 $HOME/.dfinity/identity/creds.pem 迁移到 $HOME/.config/dfx/identity/default/identity.pem。
dfx 容器删除
使用 dfx canister delete 命令从本地容器执行环境或 Internet Computer platform 上删除已停止的容器。
请注意，您只能从项目目录结构中运行此命令。
例如，如果您的项目名称是 hello_world，那么您当前的工作目录必须是 hello_world 顶级项目目录或其子目录之一。
dfx canister id
使用 dfx canister id 命令输出特定容器名称的容器标识符。
请注意，您只能从项目目录结构中运行此命令。
例如，如果您的项目名称是 hello_world，那么您当前的工作目录必须是 hello_world 顶级项目目录或其子目录之一。
dfx 容器安装
使用 dfx canister install 命令将编译后的代码作为容器安装在 Internet Computer platform 或本地容器执行环境中。
标志
您可以在 dfx canister install 命令中使用以下可选标志。
| 标志 | 说明 |
|---|---|
|
通过轮询 Internet Computer platform 或本地容器执行环境，使您无需等待返回安装结果即可继续。 |
|
显示帮助信息。 |
|
显示版本信息。 |
选项
您可以在 dfx canister install 命令中使用以下选项。
| Option | Description |
|---|---|
|
指定在安装期间传递给容器的参数。 |
|
使用 |
|
为容器执行定义计算分配（本质上相当于设置 CPU 分配）。 您可以将此值设置为 0 到 100 范围内的百分比。 |
|
指定容器总共允许使用多少内存。 您可以在 0 到 8MB 的范围内设置此值。 |
|
指定您是要 |
参数
您可以在 dfx canister install 命令中使用以下参数。
| 参数 | 描述 |
|---|---|
|
如果您有一个包含多个容器的项目 |
|
指定要部署的容器的名称。
如果您没有使用 |
例子
您可以使用 dfx canister install 命令将使用 dfx build 命令编译的 WebAssembly 部署为 Internet Computer platform 或本地容器执行环境上的容器。
最常见的用例是通过运行以下命令来安装所有容器:
dfx canister install --all安装特定的容器
您还可以使用 dfx canister install 命令部署特定的容器，而不是项目中的所有容器。
例如，如果您有一个带有 hello_world 容器和 hello_world_assets 容器的项目，但只想部署 hello_world 容器，则可以通过运行以下命令仅部署该容器:
dfx canister install hello_world发送异步请求
如果您想提交安装容器的请求并返回请求标识符以稍后检查您的请求状态，而不是等待命令完成，您可以运行类似于以下的命令:
dfx canister install hello_world --async此命令提交安装容器的请求并返回类似于以下内容的请求标识符:
0x58d08e785445dcab4ff090463b9e8b12565a67bf436251d13e308b32b5058608然后，您可以稍后使用请求标识符来检查请求的状态，就像您运送包裹时的跟踪号一样。
dfx 容器请求状态
使用 dfx canister request-status 命令请求对容器的指定调用的状态。
此命令要求您指定在容器上调用方法后收到的请求标识符。
请求标识符是一个以 0x 开头的十六进制字符串。
标志
您可以在 dfx canister request-status 命令中使用以下可选标志。
| Flag | Description |
|---|---|
|
显示帮助信息。 |
|
显示版本信息。 |
dfx 容器组控制器
使用 dfx canister set-controller 命令指定身份名称或principal以用作 Internet Computer platform 上指定容器的新 controller。
控制器身份具有管理其控制的容器的特殊权限。
例如，只能使用控制身份来安装、升级或删除其控制下的容器。
请注意，您可以将用户身份或容器指定为控制器。 您还可以通过使用其名称或其principal来指定控制器身份。
参数
您必须在 dfx canister set-controller 命令中使用以下参数。
| 参数 | 描述 |
|---|---|
|
指定由您使用 |
|
指定控制器的身份名称或principal。 |
例子
您可以使用 dfx canister set-controller 命令将用户或容器指定为特定容器的控制标识。
例如，您可以创建一个名为 pubsadmin 的新身份，然后运行 dfx canister set-controller 以指定您希望 pubsadmin 身份成为 hello_world 容器的控制器，方法是运行 以下命令:
dfx identity new pubsadmin dfx canister set-controller hello_world pubsadmin
要使用身份principal的文本表示来设置控制身份，您可以运行类似于以下内容的命令:
dfx canister set-controller hello_world wcp5u-pietp-k5jz4-sdaaz-g3x4l-zjzxa-lxnly-fp2mk-j3j77-25qat-pqe
尽管指定用户身份名称或委托人是一个潜在的用例，但更常见的场景是指定要用于向容器发送周期的钱包容器。 以下步骤说明了您进行本地开发时的这种情况。 对于此示例，假设您创建了一个名为“open_sf”的项目，其中两个容器部署在本地容器执行环境中。
-
创建一个身份——例如，
sf-controller——作为控制器。dfx identity new sf-controller Creating identity: "sf-controller". Created identity: "sf-controller".
-
使新身份成为活动身份。
dfx identity use sf-controller Using identity: "sf-controller".
-
为新身份生成钱包容器标识符。
dfx identity get-wallet 在本地容器执行环境中创建钱包容器。 r7inp-6aaaa-aaaaa-aaabq-cai 用户“sf-controller”的本地容器执行环境上的钱包容器是“r7inp-6aaaa-aaaaa-aaabq-cai”
-
将活动标识切换到容器的当前控制器。 例如，如果使用默认身份创建容器，您将运行以下命令:
dfx identity use default Using identity: "default".
-
将指定容器的控制器设置为使用与 sf-controller 身份关联的钱包。
dfx 容器组控制器 open_sf_assets r7inp-6aaaa-aaaaa-aaabq-cai 将“r7inp-6aaaa-aaaaa-aaabq-cai”设置为“open_sf_assets”的控制器。
您现在可以使用钱包容器“r7inp-6aaaa-aaaaa-aaabq-cai”发送燃料费或将保管人添加到“open_sf_assets”容器。
dfx 容器发送
当您想要分离这些步骤时，在使用 dfx canister sign 命令签署消息后使用 dfx canister send 命令，而不是使用单个 dfx canister call 命令。 使用单独的调用可以增加事务的安全性。
例如，在创建神经元股权时，您可能希望使用 dfx canister sign 命令使用气隙计算机创建签名的 message.json 文件，然后使用 dfx canister send 命令 传递签名的消息。
dfx 容器标志
当您想要分离这些步骤时，在使用 dfx canister send 命令发送消息之前使用 dfx canister sign 命令，而不是使用单个 dfx canister call 命令。 使用单独的调用可以增加事务的安全性。
例如，在创建神经元股权时，您可能希望使用 dfx canister sign 命令使用气隙计算机创建签名的 message.json 文件，然后使用 dfx canister send 命令 从连接到 Internet Computer platform 的计算机传递签名消息。
标志
您可以在 dfx canister sign 命令中使用以下可选标志。
| 标志 | 说明 |
|---|---|
|
显示帮助信息。 |
|
向容器发送查询请求。 |
|
向容器发送更新请求。 如果不使用 |
|
显示版本信息。 |
选项
您可以为 dfx canister sign 命令指定以下选项。
| 选项 | 说明 |
|---|---|
|
指定在过期和无法发送之前有效的时间。 以秒为单位指定。 如果不定义，默认为300s（5m） |
|
指定输出文件名。 默认是`message.json`。 |
|
指定生成随机参数的配置。 |
|
使用参数进行调用时指定参数的数据类型。 默认情况下，您可以使用以下链接指定参数Candid ( |
参数
您可以为 dfx canister sign 命令指定以下参数。
| 参数 | 描述 |
|---|---|
|
指定要调用的容器的名称。 容器名称是必需的参数，并且应该与您在 |
|
指定要在容器上调用的方法名称。 canister 方法是必需的参数。 |
|
指定要传递给方法的参数。
根据您的程序逻辑，参数可以是必需参数或可选参数。
如果将参数传递给容器，则可以使用 |
例子
使用 dfx canister sign 命令创建一个签名的 message.json 文件，该文件使用与您使用隐私增强邮件 (PEM) 文件创建的身份相关联的principal，方法是运行类似于以下内容的命令:
dfx canister --network=ic sign --expire-after=1h rno2w-sqaaa-aaaaa-aaacq-cai create_neurons ‘(“PUBLIC_KEY”)’
该命令说明了如何创建一个 message.json 文件以在由 ic 别名指定的 Internet Computer platform 上创建神经元，该别名使用您的principal标识符作为消息发送者进行签名，并且到期窗口结束于一小时。
请注意，分配给发送签名消息的时间是固定的 5 分钟窗口。 --expire-after 选项使您能够指定发送签名消息的 5 分钟窗口应该结束的时间点。 例如，如果您将 --expire-after 选项设置为一小时（1h），则必须等待至少 55 分钟才能发送生成的消息，并且消息的签名仅在 5 分钟窗口在第 60 分钟结束。
因此，在此示例中，您需要在 55 分钟之后和 60 分钟之前发送消息，才能将消息识别为有效。
如果您不指定 --expire-after 选项，则默认过期时间为 5 分钟。
通过运行以下命令将签名的消息发送到创世代币容器 (GTC) 以代表您创建神经元:
dfx canister send message.json
dfx 容器启动
使用 dfx canister start 命令在 Internet Computer platform 或本地容器执行环境中重新启动已停止的容器。
在大多数情况下，您在停止容器后运行此命令以正确终止任何挂起的请求，这是升级容器的先决条件。
请注意，您只能从项目目录结构中运行此命令。
例如，如果您的项目名称是 hello_world，那么您当前的工作目录必须是 hello_world 顶级项目目录或其子目录之一。
dfx 容器状态
使用 dfx canister status 命令检查容器当前是否正在运行、正在停止或当前在 Internet Computer platform 或本地容器执行环境中停止。
请注意，您只能从项目目录结构中运行此命令。
例如，如果您的项目名称是 hello_world，那么您当前的工作目录必须是 hello_world 顶级项目目录或其子目录之一。
dfx 容器停止
使用 dfx canister stop 命令停止当前在 Internet Computer platform 或本地容器执行环境上运行的容器。
在大多数情况下，您运行此命令以正确终止任何挂起的请求，这是升级容器的先决条件。
请注意，您只能从项目目录结构中运行此命令。
例如，如果您的项目名称是 hello_world，那么您当前的工作目录必须是 hello_world 顶级项目目录或其子目录之一。