PowerShell Crescendo

Crescendo is a development accelerator designed to help you rapidly build PowerShell cmdlets that wrap existing command-line tools. It transforms text-based command-line tools into robust PowerShell cmdlets by providing:

• Object Output: Converts command-line text output into structured objects suitable for the PowerShell pipeline.
• Privilege Elevation: Handles elevation requirements for the underlying tools.
• Integrated Help: Provides built-in help information for the wrapped commands.

By using Crescendo, you can replace cumbersome CLI tools with standardized, easy-to-use cmdlets that are optimized for automation and easy to distribute within a team.

Crescendo is a development accelerator designed to help you rapidly build PowerShell cmdlets that wrap existing command-line tools.

Instead of manually writing complex wrapper functions, Crescendo allows you to define cmdlets using simple key/value statements in JSON files. This process amplifies the original command-line tool by providing:

• Object Output: Converts text-based command-line output into PowerShell objects for the pipeline.
• Privilege Elevation: Supports elevation mechanisms across Windows, Linux, and macOS.
• Integrated Help: Provides help information for the wrapped tool.
• Deployment Ready: Generates a PowerShell script module that is ready to be shared with team members or used in automation.

Crescendo is a framework used to create PowerShell cmdlets that "amplify" existing command-line tools. Instead of returning plain text (the default behavior of native executables), Crescendo-based cmdlets return structured PowerShell objects, allowing them to participate fully in the PowerShell pipeline.

To create an amplified cmdlet, you need two components:

1. A JSON configuration file: This file describes the cmdlets you want to create, mapping PowerShell parameters to command-line arguments.
2. Output handler functions: You must write these functions yourself to parse the raw text output from the command-line tool and convert it into PowerShell objects.

The Crescendo module provides helper cmdlets to assist in generating these JSON configurations and building the final module.

PowerShell Crescendo is a module that allows you to create proxy functions for native (non-PowerShell) commands using JSON configuration files.

By using Crescendo, you can make native executables behave like PowerShell cmdlets. This provides several key benefits:

• Pipeline Integration: Native commands can participate in the PowerShell pipeline.
• Parameter Handling: You can interact with native command parameters using standard PowerShell parameter behaviors (e.g., switches, positional parameters, and default values).
• Output Transformation: You can use script blocks to convert raw text output from native commands into structured PowerShell objects.

If the input provided to a Crescendo cmdlet needs to be translated before being passed to the underlying native command, use the ArgumentTransform and ArgumentTransformType properties in the Parameter class.

Supported ArgumentTransformType values:

• Inline: ArgumentTransform must be a string containing a scriptblock. (Default)
• Function: ArgumentTransform must be the name of a function loaded in the current session.
• Script: ArgumentTransform must be the path to a script file.

The transformation code receives the parameter's value and must return the transformed value.

"Parameters": [
    {
        "Name": "mult2",
        "OriginalName": "--p3",
        "ParameterType": "int",
        "OriginalPosition": 2,
        "ArgumentTransform": "param([int]$v) $v * 2",
        "ArgumentTransformType": "Inline"
    }
]

When the input format of a PowerShell parameter differs from the format required by the underlying native command, you can use ArgumentTransform and ArgumentTransformType within the Parameter class of your Crescendo configuration.

ArgumentTransform defines the logic used to translate the value, while ArgumentTransformType determines how that logic is interpreted.

Supported ArgumentTransformType values:

• Inline: The ArgumentTransform value is a string evaluated as a script block. This is the default type.
• Function: The ArgumentTransform value is the name of a function loaded in the current session.
• Script: The ArgumentTransform value is the name of a script file found on disk.

When working with Crescendo, the following terms are used to distinguish between native tools and their PowerShell wrappers:

• command-line tool: A native executable file installed on your system (e.g., ipconfig.exe).
• command: The full string used to invoke the executable, including its specific parameters (e.g., ipconfig.exe /all).
• amplified command: The PowerShell cmdlet you created using Crescendo that wraps the command (e.g., Get-IpConfig -All).

Crescendo now captures stderr from native commands. You can inspect and manage these errors within your output handler using two internal functions:

• Push-CrescendoNativeError: Automatically called by the output handler to add an error to the queue.
• Pop-CrescendoNativeError: Used within an output handler to inspect and remove errors from the queue. This allows you to decide whether to handle the error or pass it through to the caller.

To return errors to the user via an Inline handler, use Pop-CrescendoNativeError -EmitAsError in the END block of your handler script.

"OutputHandlers": [
    {
        "ParameterSetName": "Default",
        "StreamOutput": true,
        "HandlerType": "Inline",
        "Handler": "PROCESS { $_ } END { Pop-CrescendoNativeError -EmitAsError }"
    }
]