Announcing PowerShell Crescendo Preview.3

Jason

We are pleased to announce the third preview of PowerShell Crescendo, a framework to rapidly develop PowerShell cmdlets for native commands, regardless of platform.

Warning


Preview.3 includes a change to the schema to support multiple command configurations. This is a breaking change from previous previews. To enjoy the new multi-command JSON format, please upgrade to the latest preview.

The updated preview release is now available for download on the PowerShell Gallery:

To install Microsoft.PowerShell.Crescendo:

Install-Module Microsoft.PowerShell.Crescendo -AllowPrerelease

For more information on Microsoft.PowerShell.Crescendo, check out these previous blog posts:

Crescendo Preview 3 Updates

Crescendo 0.6.1-Preview.3 adds support to handle multiple command definitions per JSON configuration and additional output handling options. Read the full list of changes below:

  • Added support for multiple commands per JSON configuration. Issue #49
  • Added additional output handler options inline, function, and script. Issue #33
  • Added additional proxy generation code cleanup

Support multiple command definitions per JSON configuration

To improve the development and distribution of Crescendo wrapped commands, the schema for Crescendo has been extended to support multiple command definitions in a single JSON file. A new keyword Commands creates an additional tier to the hierarchy, followed by single or multiple command definitions. This is a breaking change from previous previews.

In the example below, each command definition is located inside the Commands keyword.

{
    "$schema": "./Microsoft.PowerShell.Crescendo.Schema.json",
    "Commands": [
         {
             "Verb": "New",
             "Noun": "Command1",
             "OriginalName":"<path><command>"
         },
         {
            "Verb": "New",
            "Noun": "Command2",
            "OriginalName":"<path><command>"
         },
         {
            "Verb": "New",
            "Noun": "Command3",
            "OriginalName":"<path><command>"
         }
    ]
}

Additional per command features such as parameter definitions and administrative elevation may be added to single or multiple command definitions. Check out these blogs for more information about parameters and elevation.

Support additional OutputHandlers

Output handlers take the text output (string) from a native command and convert those strings to objects. Crafting custom output handlers is complex unless the native commands produce structured output such as XML or JSON. To provide authors with development and deployment flexibility, Crescendo supports three types of output handlers: inline, script, and function.

  • Inline – Authors construct the output handler code inside the cmdlet definition. When Crescendo generates the module, the output handler code is written directly into the proxy function for the new cmdlet.
  • Script – Authors may choose to develop the output handler in a separate script to isolate troubleshooting. The Handler keyword supports the path and script name to be included. Crescendo generates the module (.psm1) containing the proxy cmdlet, the manifest (.psd1), and includes the specified script as an additional asset.
  • Function – Authors may already have written output handlers that have been imported into PowerShell as functions. Crescendo adds the imported function to the generated module outside of the proxy cmdlet.
{
    "$schema": "./Microsoft.PowerShell.Crescendo.Schema.json",
    "Commands": [
         {
             "Verb": "New",
             "Noun": "Command1",
             "OriginalName":"<path><command>",
             "OutputHandlers": [
                {
                  "ParameterSetName": "viaInline",
                  "HandlerType": "Inline",
                  "Handler": "$args[0] | ConvertFrom-Json"
                }
             ]
         },
         {
            "Verb": "New",
            "Noun": "Command2",
            "OriginalName":"<path><command>",
            "OutputHandlers": [
                {
                  "ParameterSetName": "viaScript",
                  "HandlerType": "Script",
                  "Handler": "Convert-GetDate.ps1"
                }
            ]
         },
         {
            "Verb": "New",
            "Noun": "Command3",
            "OriginalName":"<path><command>",
            "OutputHandlers": [
                {
                  "ParameterSetName": "viaFunction",
                  "HandlerType": "Function",
                  "Handler": "Convert-GetDate"
                }
            ]
         }
    ]
}

information


Both script and function use Get-Command to determine the availability of the handler. Be sure that the handler may be found by Get-Command before using Export-CrescendoModule.

For an example of working with an inline output handler, including parameters, see Announcing PowerShell Crescendo Preview.1

Future plans

Next/Future plans for preview.4 will be based on feedback and include a few items under investigation:

  • Improved tooling for discovery of Crescendo generated modules
  • Improved cmdlet support including New-CrescendoCommand and Export-CrescendoModule

Our goal is to make it easier to convert your native commands to PowerShell cmdlets and receive the benefits that PowerShell provides. We value your ideas and feedback and hope you will give Crescendo a try, then stop by our GitHub repository and let us know of any issues or features you would like added.

For more information about PowerShell Crescendo issues and features, see: Crescendo on GitHub

1 comment

Leave a comment