研究命令行工具的语法和输出

重要

截至2026年5月，Crescendo项目已不再积极维护。 该项目应从工程角度视为存档。

之前的 文章 提供了选择你想用Crescendo放大的命令行工具的标准。 本文介绍了如何收集关于使用 Crescendo 设计 cmdlet 的工具信息的方法。

本文示例中使用Azure Connected Machine 代理工具（azcmagent）。 我们选择这个工具是因为：

  • 安装和拆卸都很简单
  • 它不需要激活的 Azure 订阅即可基本使用。
  • 它有实用的主机内帮助和在线文档
  • 它能产出易于消化的产物

小窍门

如果你没有这个工具，除非你想试试这些示例，否则不需要安装。

更多信息请参阅本文的 “安装azcmagent工具 ”部分。

从命令行帮助和文档开始

许多命令行工具都包含开关或参数，用于显示帮助内容。 大多数现代命令行工具为工具提供的各种用例场景提供了多层次的帮助。 例如，运行时不带参数， azcmagent 会显示顶层帮助，其中包含一个子命令列表。

...
Usage:
  azcmagent [command]

Available Commands:
  check       Runs connectivity checks
  config      Change configuration settings for this machine
  connect     Connects this machine to Azure
  disconnect  Disconnects this machine from Azure
  help        Help about any command
  license     Display the End-user license agreement file
  logs        Creates a .zip file containing relevant logs. This is primarily useful for troubleshooting.
  show        Gets machine metadata and Agent status. This is primarily useful for troubleshooting.
  version     Display the Hybrid Management Agent version
...

每个子指令都可以有自己的子指令和参数。 例如， config 子指令有五个子指令。

PS> azcmagent config --help
Change configuration settings for this machine

Usage:
  azcmagent config [command]

Available Commands:
  clear       Clear a configuration property's value
  get         Get a configuration property's value
  info        Describes the config properties users can set
  list        List all configuration properties and values
  set         Set a value for a configuration property

Flags:
  -h, --help      help for config
      --version   version for config

Global Flags:
      --config string   config file (default is $HOME/.azcmagent.yaml)
  -j, --json            Output in JSON format
      --log-stderr      Redirect error and verbose messages to stderr
  -v, --verbose         Increase logging verbosity to show all logs

Use "azcmagent config [command] --help" for more information about a command.

使用命令行帮助来发现可能的使用场景。 你可以将每个帮助命令的输出重定向到一个文件，方便你在创建 Crescendo 指令时使用。

小窍门

如果帮助内容结构一致，可能可以通过解析这些帮助输出来创建代码来构建 cmdlet。 Crescendo 附带了一些实验性的帮助解析器，用来演示如何实现这一点。 请查看Microsoft根文件夹中的Experimental文件夹。PowerShell.Crescendo module.

注意命令行工具提供的输出格式。 许多命令行工具可以输出 CSV 或 JSON 等格式的信息。 这些结构化格式可以轻松转换为PowerShell对象。

解析用的捕获示例输出

一旦你决定了要用Crescendo放大工具的哪个指令，就从这些指令中收集采样输出。 每个命令的输出重定向到一个文件。 利用这些示例数据帮助你设计Crescendo cmdlet的输出处理程序（解析器）。

检查样本输出时，考虑返回的数据类型。 在构建对象时，你应该把命令行工具输出的字符串转换成 .NET 类型。 例如，时间戳信息可以转换为.NET [DateTime]类型。 另外，检查输出格式中分隔数据字段的标记。 这些标记可以用来解析信息，同时构建输出对象。

该 azcmagent 工具支持输出 JSON 格式的信息。 这使得转换为PowerShell对象变得非常简单。 例如：

PS> $agentStatus = azcmagent show --json | ConvertFrom-Json
PS> $agentStatus.services

displayName       serviceName      status
-----------       -----------      ------
GC Service        gcarcservice     running
Extension Service extensionservice running
Agent Service     himds            running

关于更复杂的解析输出示例，请参阅PowerShell社区博客中的这篇 博客文章 。

注释

azcmagent该工具必须以管理员权限运行。 这也意味着你创建的模块必须以管理员权限运行。

安装 azcmagent 工具

您可以从以下列出的地点下载Windows和Linux的Azure Connected Machine代理包。

有关Azure连接机代理的更多信息，请参见 管理与维护连接机代理。

后续步骤

创建一个 cmdlet 配置

  • Last updated on