Announcing Crescendo 0.7.0-Preview.4

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

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

• Microsoft.PowerShell.Crescendo Preview 4

To install Microsoft.PowerShell.Crescendo:

Install-Module Microsoft.PowerShell.Crescendo -AllowPrerelease

Crescendo Preview 4 Updates

Crescendo 0.7.0-Preview.4 adds global schema support and experimental help parsing for modern native commands. Read the full list of changes below:

• Added global schema support
• Added experimental native command help parser. Issue #99
• New-CrescendoCommand should include an OriginalName parameter. Issue #82
• Added Export-CrescendoCommand to create a configuration file. Issue #80
• Added support for the ConfirmImpact CmdletBinding() argument.
• Default parameter values are not used. Issue #101

Global Schema support

In preview 4, we’ve published the authoring schema for PowerShell Crescendo at a well-known URL. This URL can be referenced instead of a local file path as in previous preview versions. The schema works with supported tools like Visual Studio Code to provide intellisense and tooltips during the authoring experience.

URL location of the always-available Crescendo schema:

{
   "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2021-11",
   "Commands": []
}

Experimental native command Help parsers

Modern commands that produce structured help output may be parsed for parameter and argument information to build a PowerShell Crescendo configuration file. This reduces the time to discover and handle changes, making maintaining Crescendo modules that contain complex native commands easier to maintain.

The Preview 4 release includes several help parsers for native commands. These parsers are experimental and have limitations. For a full discussion about the design and limitations of help parsers as well as how to use them, see the help parser README file.

The experimental help parsers can be found in the HelpParsers folder in the GitHub repository.

The experimental help parsers may also be found locally in the module folder <PathToModule>/Microsoft.PowerShell.Crescendo/src/experimental/HelpParsers/.

New-CrescendoCommand now includes the OriginalName parameter

The cmdlet New-CrescendoCommand includes the OriginalName parameter that specifies the name and location of the native command to be wrapped by Crescendo.

New-CrescendoCommand -Verb Get -Noun MyFeature -OriginalName "<Path><Command>"

Creating a command configuration with Export-CrescendoCommand

PowerShell Crescendo users may choose to start a configuration file with a partially populated template. New-CrescendoCommand can create the command object that can be converted to JSON using the Export-CrescendoCommand cmdlet.

To create a JSON configuration file for a single command:

New-CrescendoCommand -Verb Get -Noun MyFeature -OriginalName MYCommand.exe |
    Export-CrescendoCommand -TargetDirectory C:MyConfig

For this example, Export-CrescendoCommand creates the file C:MyConfigGet-MyFeature.config.json.

Support for the ConfirmImpact argument

When you define a cmdlet that alters the system state you should include the SupportsShouldProcess argument in the CmdletBinding() attribute for the cmdlet. The Crescendo JSON schema includes SupportsShouldProcess. Preview 4 adds the ConfirmImpact argument. Supported values for ConfirmImpact are: Low, Medium, or High.

Default parameter values are not used

In previous previews, specifying the default value of a parameter was not recognized and respected in the generated Crescendo module. This resulted in a cmdlet parameter without the expected default value. Starting in Preview 4, parameters defined with default values will now use those default values unless overridden by the user.

{
  "ParameterSetName": ["Default"],
  "Name":"ProductName",
  "OriginalName": "-pn",
  "ParameterType": "string",
  "DefaultValue": "WinGet",
  "Description": "This switch provides product name for display"
}

In the example above, the argument default value “WinGet” will be applied to the parameter ProductName when the user executes the cmdlet.

More information about Microsoft.PowerShell.Crescendo

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

• Announcing PowerShell Crescendo Preview.3
• Announcing PowerShell Crescendo Preview.2
• Announcing PowerShell Crescendo Preview.1
• Native Commands in PowerShell Part 1
• Native Commands in PowerShell Part 2

For more information using Microsoft.PowerShell.Crescendo, check out this excellent blog series by Sean Wheeler posted to the PowerShell Community.

• My Crescendo journey
• Converting string output to objects
• A closer look at the parsing code of a Crescendo output handler
• A closer look at the Crescendo configuration

Future plans

The plans for the general release will be based on community feedback and include improved tooling and guidance for Crescendo cmdlets. 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. Stop by our GitHub repository and let us know of any issues you find or features you would like added.