从经典 CLI 迁移到 Azure Sphere CLI

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

如果仍在使用 Azure Sphere 经典 CLI，建议迁移到 新的 Azure Sphere CLI。 目前，两个版本的 CLI 都可以安装并同时使用，但经典 CLI 已不再更新或维护，并将在未来某个日期（不会在 2022 年底之前）从 SDK 中移除。 我们鼓励你熟悉这些差异，并在 2022 年底之前迁移流程和脚本，以避免中断。

要更新到最新 SDK，请参阅在 Linux 上安装 Azure Sphere SDK 或安装用于 Windows 的 Azure Sphere SDK。

若要在 Windows 上使用 Azure Sphere CLI，请使用 PowerShell 或标准 Windows 命令提示符。 对于 Linux，可使用任何命令 shell。 有关详细信息，请参阅运行 Azure Sphere CLI。

在 Windows 上，即将退休的自定义Azure Sphere 开发人员命令提示符（可在开始菜单Azure Sphere下作为快捷方式使用）只能与 Azure Sphere classic CLI 一起使用。 有关详细信息，请参阅运行 Azure Sphere 经典 CLI。

主要区别

• 在 Azure Sphere 经典 CLI 中，可以使用多个参数来标识每个对象类型。 在 Azure Sphere CLI 中，一个参数用于标识每个对象类型。 这意味着可以使用名称或 ID 来指定参数值。 这已针对--device参数--tenant--product--device-group和参数实现。

  对象类型	Azure Sphere CLI	Azure Sphere 经典 CLI（即将停用）
  设备	--device	--deviceid、--deviceip 或 --devicelocation
  设备组	--device-group	--devicegroupid 或 --devicegroupname
  产品	--product	--productid 或 --productname
  租户	--tenant	--tenantid

• 经典版本中支持命令的简短形式。 在 Azure Sphere CLI 中，建议使用 Tab 完成 或 交互式 功能查看可用命令列表。 例如，在经典 CLI 中，可以使用任一 azsphere device enable-development 或 azsphere dev edv 命令，而在新的 Azure Sphere CLI 中，可以使用自动完成快速键入命令 azsphere device enable-development 。

• 某些命令允许单个参数的多个值。 在 Azure Sphere CLI 中，可以提供一个参数，后跟一个由空格分隔的值列表，在 Azure Sphere 经典 CLI 中，值列表用逗号分隔。 例如：

  Azure Sphere CLI

  azsphere image-package pack-application --package-directory myDirectory --destination myImagePackage --executables filepath-1 filepath-2
  

  Azure Sphere 经典 CLI

  azsphere image-package pack-application --input myDirectory --output myImagePackage --executables filepath-1,filepath-2
  

• 在新 CLI 中，创建租户时不会自动选择默认租户。 必须运行 azsphere tenant select 命令，以选择要用于电脑上当前用户的默认租户。 这是为了确保默认租户是执行一次性操作时使用的正确租户，就像声明设备一样无法撤消。

  使用脚本时，可以使用参数选择默认租户 --tenant <tenant ID or tenant name> 。

  使用以下命令在脚本开头设置默认租户：

  azsphere tenant select --tenant <tenant ID or tenant name>
  

  还可以在运行命令时覆盖默认租户或指定所需的租户。 例如：

  azsphere get-support-data --destination logs.zip --tenant <tenant ID or tenant name>
  

• 参数 --device-group 标识设备组。 设备组 ID 提供 GUID，用于在所有产品中唯一标识设备组。 或者，可以使用产品名称>/<device-group-name 格式的产品名称和设备组名称>对<。 这对名称唯一地标识了特定产品的设备组。

• 以下命令是经典 CLI 中的复合命令。 这意味着一个命令执行了多个任务。 在新 CLI 中，需要运行两个命令。

  • 在经典 CLI 中， azsphere device-group deployment create 命令上传了映像包并创建了一个新部署。

    在新 CLI 中，需要：

    1. 使用 azsphere image add 将映像包上传到 Azure Sphere 租户。
    2. 使用 azsphere device-group deployment create 为上传的图像创建设备组的新部署。

  • 在经典 CLI 中， azsphere 设备功能下载 --select 命令已下载并临时选择附加设备的设备功能配置。

    在新 CLI 中，需要：

    1. 使用 azsphere device capability download 下载功能文件。
    2. 使用 azsphere device capability select 选择该功能。

  • 在经典 CLI 中， azsphere device capability download --apply 命令已下载并应用附加设备的设备功能配置。

    在新 CLI 中，需要：

    1. 使用 azsphere device capability download 下载功能文件。
    2. 使用 azsphere 设备功能更新应用该功能。

• 在经典 CLI 中， -o 或 --output 参数用于指定用于保存文件的路径和文件名。 在新 Azure Sphere CLI 中，使用特定于上下文的参数来 --destination 指定 输入和输出路径。

• 在经典 CLI 中，-dazsphere device app start 命令中使用或--debug参数以调试模式启动应用程序。 在新 Azure Sphere CLI 中，该 --debug-mode 参数用于在调试模式下启动应用程序，参数 --debug 用作全局参数，以增加日志记录详细程度以显示所有调试日志。

• 在经典 CLI 中，无法控制输出格式。 在 Azure Sphere CLI 中， -o 或 --output 参数用于指定 用于设置 CLI 输出格式的输出格式。

• 从版本 21.02 开始，显式版本号已从 Azure Sphere CLI 产品名称中删除。 此更改消除了引用产品不同版本的混淆。

  • Azure Sphere CLI v2 及更高版本现在仅称为“Azure Sphere CLI”。
  • 早期 Azure Sphere CLI 版本（CLI v1 和更低版本）现在称为“Azure Sphere 经典 CLI”。

• 如果使用脚本，则由于上述差异，它们可能与新的 Azure Sphere CLI 不兼容。 对脚本进行所需的更新，以便在新 CLI 中正确运行。

另请参阅

• 开始使用 Azure Sphere CLI
• Azure Sphere 经典 CLI（即将停用）