创建 Crescendo cmdlet

重要

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

现代命令行工具为有效管理领域特定技术提供了命令。管理员用户可以自信地在PowerShell内执行这些命令，并获得预期结果。然而，PowerShell用户更喜欢cmdlet提供的语法、可读性和基于对象的输出，尤其是在自动化领域。

如前所述，你可能有几个原因需要放大命令行工具：

字符串输出在自动化中使用起来很困难
命令语法难以使用或记忆
该工具缺乏有用的帮助文档

在上一篇文章中，我们讨论了如何发现并选择你想用Crescendo放大的工具功能。本文示例中，我们继续使用 azcmagent 之前介绍的命令行工具。

创建 Crescendo cmdlet 的配置

渐强配置描述了一个新的指令小说。 cmdlet定义包括：

原始命令行工具的位置
传递给命令行工具的子命令和参数
Verb-Noun新指令的名称
cmdlet 使用的参数

Crescendo 会根据配置文件生成原始命令行工具的代理 cmdlet。生成的代码存储在 PowerShell 脚本模块中，准备部署。

你可以创建自己的配置文件，复制现有文件并修改它，或者用 New-CrescendoCommand cmdlet 启动新的配置。 Crescendo 配置文件是用 JSON 编写的。

动词参数指定了新指令的动词。用 Get-Verb 来获取批准的动词名称列表。
名词参数指定动词作用的名词。
OriginalName 参数指定了原始命令行工具的路径。

$parameters = @{
    Verb = 'Show'
    Noun = 'AzCmAgent'
    OriginalName = "c:/program files/AzureConnectedMachineAgent/azcmagent.exe"
}
New-CrescendoCommand @parameters | Format-List *

New-CrescendoCommand 创建一个Crescendo命令对象。指令包确实填充了所有可能的属性值。

FunctionName            : Show-AzCmAgent
Verb                    : Show
Noun                    : AzCmAgent
OriginalName            : c:/program files/AzureConnectedMachineAgent/azcmagent.exe
OriginalCommandElements :
Platform                : {Windows, Linux, MacOS}
Elevation               :
Aliases                 :
DefaultParameterSetName :
SupportsShouldProcess   : False
ConfirmImpact           :
SupportsTransactions    : False
NoInvocation            : False
Description             :
Usage                   :
Parameters              : {}
Examples                : {}
OriginalText            :
HelpLinks               :
OutputHandlers          :

以下示例展示了如何创建新的配置文件。

$parameters = @{
    Verb = 'Show'
    Noun = 'AzCmAgent'
    OriginalName = "c:/program files/AzureConnectedMachineAgent/azcmagent.exe"
}
$CrescendoCommands += New-CrescendoCommand @parameters
Export-CrescendoCommand -command $CrescendoCommands -fileName .\AzCmAgent.json

Crescendo 配置文件具有 JSON 模式，可以在数组中包含一个或多个 cmdlet 定义。在这个例子中， $NewConfiguration 是一个包含 JSON 模式链接的对象，以及一个包含 cmdlet 定义的数组。输出的 New-CrescendoCommand 被添加到 Commands 数组中。这些文件 $NewConfiguration 会被转换成JSON并写入文件。 AzCmAgent.json 文件包含以下代码：

{
  "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2022-06",
  "Commands": [
    {
      "Verb": "Show",
      "Noun": "AzCmAgent",
      "OriginalName": "c:/program files/AzureConnectedMachineAgent/azcmagent.exe",
      "Platform": [
        "Windows",
        "Linux",
        "MacOS"
      ],
      "SupportsShouldProcess": false,
      "SupportsTransactions": false,
      "NoInvocation": false,
      "Parameters": [],
      "Examples": []
    }
  ]
}

在Crescendo配置文件里有schema链接很重要。该模式在创作过程中提供了如Visual Studio Code、IntelliSense和工具提示等工具。

完成Crescendo指令配置

在这个例子中，我们正在为该 azcmagent show 命令创建一个配置。命令小工具不需要任何额外参数。由于 azcmagent 是一个提供 JSON 输出的现代工具，示例包含一个简单的输出处理程序，将 JSON 输出转换为对象。

命令定义包括以下属性：

动词：cmdlet 动词的名称
名词：指令重管名词的名称
Platform：Crescendo 命令运行的平台（Windows，Linux，MacOS）
OriginalName：原始本地命令名称和位置
OriginalCommandElements：一些命令行工具在特定场景下有额外的强制开关
描述：帮助中出现的指令包描述
别名：新指令的别名或简称
OutputHandlers：输出处理器，捕获命令行工具的字符串输出并将其转换为PowerShell对象
HandlerType：可以是 Inline、 Function或 Script。此示例使用 Inline

以下示例展示了经过额外编辑后新cmdlet的完整JSON定义。

{
  "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2022-06",
  "Commands": [
    {
      "Verb": "Show",
      "Noun": "AzCmAgent",
      "OriginalName": "c:/program files/AzureConnectedMachineAgent/azcmagent.exe",
      "OriginalCommandElements": [
         "show",
         "--json"
      ],
      "Platform": [
        "Windows"
      ],
      "Description": "Gets machine metadata and Agent status. This is primarily useful for troubleshooting.",
      "Aliases": [
        "azinfo"
      ],
      "OutputHandlers": [
        {
            "ParameterSetName": "Default",
            "HandlerType": "Inline",
            "Handler": "$args[0] | ConvertFrom-Json"
        }
      ],
      "SupportsShouldProcess": false,
      "SupportsTransactions": false,
      "NoInvocation": false,
      "Parameters": [],
      "Examples": []
    }
  ]
}

定义另一个带有参数的 cmdlet

在这个例子中，我们为命令创建一个Crescendo配置 azcmagent config get ，列出属性信息。一个名为 Property 的参数映射到 Get的原始参数。

参数定义包括以下性质：

DefaultParameterSetName：定义如果实现多个参数集时的默认参数集
参数：包含命令参数定义的代码块
名称：这是生成的 cmdlet 的 PowerShell 参数名称
OriginalName：参数名称
ParameterType：定义参数值的数据类型
ParameterSetName：定义该参数所属的参数
强制性：决定参数是否必须有某个值的设置
描述：帮助中看到的参数描述

以下示例展示了新 cmdlet 的完整 JSON 定义。你可以把它放在一个新的 JSON 文件里的定义，或者添加到之前 JSON 文件的 Orders 数组里。

{
    "Verb": "Get",
    "Noun": "AzCmAgentConfigProperty",
    "Platform": [
        "Windows"
    ],
    "OriginalCommandElements": [
        "config",
        "--json"
    ],
    "OriginalName": "c:/program files/AzureConnectedMachineAgent/azcmagent.exe",
    "Description": " Get a configuration property's value",
    "DefaultParameterSetName": "Default",
    "Parameters": [
        {
            "OriginalName": "get",
            "Name": "Property",
            "ParameterType": "string",
            "ParameterSetName": [
                "Default"
            ],
            "Mandatory": true,
            "Description": "Specify the name of the property to return"
        }
    ],
    "OutputHandlers": [
        {
            "ParameterSetName": "Default",
            "HandlerType": "Inline",
            "Handler": "$args[0] | ConvertFrom-Json"
        }
    ],
    "SupportsShouldProcess": false,
    "SupportsTransactions": false,
    "NoInvocation": false,
    "Examples": []
}

更详细的配置示例，请参见博客文章《更深入探讨Crescendo配置》。

后续步骤

既然你已经定义好了指令集，就可以生成新的模块了。

生成并测试你的模块

反馈

此页面是否有帮助？

Last updated on 2026-05-06