As a shell, PowerShell is intended to work with native commands in addition to cmdlets. However,\nnative commands have their own unique syntax, sometimes containing many subcommands and\nparameters\/switches, and are often like its own language. Wouldn’t it be great to have an option to\nleverage your PowerShell skills to use new commands or be even more proficient with native\ncommands you are already using? As a PowerShell user, it would be great if those native commands\nsupported PowerShell features like:<\/p>\n
Verb-Noun<\/code><\/li>\n- Consistent parameter naming for similar uses<\/li>\n
- Output consisting of objects<\/li>\n
- Common method of getting command help<\/li>\n
- Easy to work with objects in a pipeline<\/li>\n
- Easy to share using Modules<\/li>\n<\/ul>\n
We are pleased to announce the first preview of PowerShell Crescendo<\/strong>, a framework to rapidly\ndevelop PowerShell cmdlets for native commands, regardless of platform.<\/p>\nMany of today’s modern native commands are complex, they themselves are mini-shells<\/em> with their own\nmini-language<\/em> containing sub levels, or sub contexts. If you’ve worked with kubectl<\/code>, docker<\/code> or\nnetsh.exe<\/code>, you have experienced the complexity of executing and automating these commands.<\/p>\nTo make native commands have a more PowerShell-like feel and offer a similar experience, you could\nre-write the tool yourself, or if the tool uses REST<\/code>, directly call the web APIs using\nAutoRest<\/a>. These options work very well, but require more\ndevelopment experience and can be harder to maintain over time.<\/p>\nCrescendo provides the tools to easily wrap a native command to gain the benefits of PowerShell\ncmdlets. Wrapping native commands into Crescendo cmdlets can provide parameter handling like\nprompting for mandatory parameters and tab-completion for parameter values. Crescendo cmdlets\ncan take the text output from the native application and parse it into objects. The output objects\nallow you to take advantage of all the post processing tools such as Sort-Object<\/code>, Where-Object<\/code>,\netc.<\/p>\nWhat’s supported<\/h2>\n
Microsoft.PowerShell.Crescendo 0.4.1 Preview.1 is currently available for download from the\nPowerShell Gallery<\/a><\/p>\nSupported PowerShell versions for authoring a module with Crescendo:<\/p>\n
\n- PowerShell 7.0+<\/li>\n<\/ul>\n
Supported PowerShell versions that can execute a Crescendo module:<\/p>\n
\n- Windows PowerShell 5.1+<\/li>\n
- PowerShell 7.0+<\/li>\n<\/ul>\n
What’s next<\/h2>\n
Next\/Future plans for preview.2 will be based on feedback and include a few items under investigation:<\/p>\n
\n- Create cmdlet aliases when generating a module<\/li>\n
- Investigate parsing man pages and documentation to improve automatic JSON generation<\/li>\n<\/ul>\n
Installing Crescendo<\/h2>\n
To create a Crescendo cmdlet, you will need the module\nMicrosoft.PowerShell.Crescendo<\/strong> from the PowerShell Gallery.<\/p>\nInstall-Module Microsoft.PowerShell.Crescendo\r\n<\/code><\/pre>\nDocumentation<\/h2>\n
We’ve included the about_Crescendo<\/code> and we’ll be adding more documentation in the future.\nMake sure to check out the Samples folder in the module.<\/p>\nGet-Help about_Crescendo\r\n<\/code><\/pre>\nTo author a Crescendo module, you create a JSON configuration file describing how you want the\nnative command projected as a cmdlet. You need the Microsoft.PowerShell.Crescendo<\/strong> module to\nbuild the finished module containing the Crescendo proxy cmdlets. The\nMicrosoft.PowerShell.Crescendo<\/strong> module runs on PowerShell 7+.<\/p>\nTo consume a module built with Crescendo, you don’t need to have Microsoft.PowerShell.Crescendo<\/strong>\ninstalled. Simply download or install the generated module and you’re good to go. Because a\nCrescendo-built module is just like any other module, these are supported on Windows PowerShell 5.1\nand above. Your work can help others in the community automate native commands. Fortunately,\nbuilding and sharing Crescendo modules is easy when you publish to the PowerShell Gallery.<\/p>\nFor more information about the concepts and design approach, see:<\/p>\n
\n- Native Commands in PowerShell Part 1<\/a><\/li>\n
- Native Commands in PowerShell Part 2<\/a><\/li>\n<\/ul>\n
Examples<\/h2>\nCreating a new cmdlet<\/h3>\n
This example builds on a common Linux packaging utility apt<\/code> for displaying, installing and\nremoving software. The properties Verb<\/strong> and Noun<\/strong> define the name of the new cmdlet\nGet-InstalledPackage<\/code>.<\/p>\nThe Crescendo module includes a schema definition file for assistance creating and editing JSON\nconfiguration files. The schema file Microsoft.PowerShell.Crescendo.Schema.json<\/code> is included with\nthe module. In the below example, the schema file is copied to a temporary working directory with\nthe JSON file under development. The location of the schema file is defined in the JSON\nconfiguration and can be located anywhere.<\/p>\nCommon properties defined by the schema:<\/p>\n
\nVerb<\/code>: The name of the cmdlet verb (Check Get-Verb<\/code> for valid verb names)<\/li>\nNoun<\/code>: The name of the cmdlet noun<\/li>\nOriginalName<\/code>: The original native command name and location<\/li>\nOriginalCommandElements<\/code>: Some native commands have additional mandatory switches to execute\nproperly for a given scenario<\/li>\nOutputHandlers<\/code>: The output handler captures the string output from the native command and\ntransforms it into structured data (objects). As with other PowerShell cmdlets, this object output\nmay be manipulated further down the pipeline.<\/li>\n<\/ul>\nNote: The example code contains comments (\/\/ <--<\/code>) in JSON. They are for\ndescriptive purposes only and should be removed.<\/p>\n{\r\n \"$schema\": \".\/Microsoft.PowerShell.Crescendo.Schema.json\", \/\/ <-- Schema definition file\r\n \"Verb\": \"Get\", \/\/ <-- Cmdlet Verb\r\n \"Noun\":\"InstalledPackage\", \/\/ <-- Cmdlet Noun\r\n \"OriginalName\": \"apt\", \/\/ <-- Native command\r\n \"OriginalCommandElements\": [\"-q\",\"list\",\"--installed\"],\r\n \"OutputHandlers\": [ \/\/ <-- Add string output to an object\r\n {\r\n \"ParameterSetName\":\"Default\",\r\n \"Handler\": \"$args[0]| select-object -skip 1 | %{$n,$v,$p,$s = \"$_\" -split ' '; [pscustomobject]@{ Name = $n -replace '\/now'; Version = $v; Architecture = $p; State = $s.Trim('[]') -split ',' } }\"\r\n }\r\n ]\r\n}\r\n<\/code><\/pre>\nThe following example shows how to use the Get-InstalledPackage<\/code> we defined in the JSON file.<\/p>\nPS> Get-InstalledPackage | Where-Object { $_.name -match \"libc\"}\r\n\r\nName Version Architecture State\r\n---- ------- ------------ -----\r\nlibc-bin 2.31-0ubuntu9.1 amd64 {installed, local}\r\nlibc6 2.31-0ubuntu9.1 amd64 {installed, local}\r\nlibcap-ng0 0.7.9-2.1build1 amd64 {installed, local}\r\nlibcom-err2 1.45.5-2ubuntu1 amd64 {installed, local}\r\nlibcrypt1 1:4.4.10-10ubuntu4 amd64 {installed, local}\r\n\r\nPS> Get-InstalledPackage | Group-Object -Property Architecture\r\n\r\nCount Name Group\r\n----- ---- -----\r\n 10 all {@{Name=adduser; Version=3.118ubuntu2; Architecture=all; State=System.String[}, @{Name=debconf; V\u2026\r\n 82 amd64 {@{Name=apt; Version=2.0.2ubuntu0.1; Architecture=amd64; State=System.String[]}, @{Name=base-files\u2026\r\n<\/code><\/pre>\nExample with parameters<\/h3>\n
This example wraps the Windows command ipconfig.exe<\/code> and illustrates how to define parameters. In\naddition to the properties in the above example, the schema supports a Parameters<\/code> section to wrap\nand project descriptively named parameters to the new cmdlet.<\/p>\n\nName<\/code>: Name of parameter that appears in the new cmdlet<\/li>\nOriginalName<\/code>: Name of original parameter that appears in the native command<\/li>\n<\/ul>\n{\r\n \"$schema\" : \".\/Microsoft.PowerShell.Crescendo.Schema.json\",\r\n \"Verb\": \"Get\",\r\n \"Noun\": \"IpConfig\",\r\n \"OriginalName\":\"c:\/windows\/system32\/ipconfig.exe\",\r\n \"Description\": \"This will display the current IP configuration information on Windows\",\r\n\r\n \"Parameters\": [ \/\/ <-- Parameter definition\r\n {\r\n \"Name\":\"All\", \/\/ <-- Name of parameter that appears in cmdlet\r\n \"OriginalName\": \"\/all\", \/\/ <-- Name of original parameter that appears in native cmd\r\n \"ParameterType\": \"switch\",\r\n \"Description\": \"This switch provides all ip configuration details\" \/\/ <-- Help parameter\r\n },\r\n {\r\n \"Name\":\"AllCompartments\",\r\n \"OriginalName\": \"\/allcompartments\",\r\n \"ParameterType\": \"switch\",\r\n \"Description\": \"This switch provides compartment configuration details\"\r\n }\r\n ],\r\n\r\n \"OutputHandlers\": [\r\n {\r\n \"ParameterSetName\": \"Default\",\r\n \"Handler\":\"param ( $lines )\r\n $post = $false;\r\n foreach($line in $lines | ?{$_.trim()}) {\r\n $LineToCheck = $line | select-string '^[a-z]';\r\n if ( $LineToCheck ) {\r\n if ( $post ) { [pscustomobject]$ht |add-member -pass -typename $oName }\r\n $oName = ($LineToCheck -match 'Configuration') { 'IpConfiguration' } else {'EthernetAdapter'}\r\n $ht = @{};\r\n $post = $true\r\n }\r\n else {\r\n if ( $line -match '^ [a-z]' ) {\r\n $prop,$value = $line -split ' :',2;\r\n $pName = $prop -replace '[ .-]';\r\n $ht[$pName] = $value.Trim()\r\n }\r\n else {\r\n $ht[$pName] = .{$ht[$pName];$line.trim()}\r\n }\r\n }\r\n }\r\n [pscustomobject]$ht | add-member -pass -typename $oName\"\r\n }\r\n ]\r\n}\r\n<\/code><\/pre>\nExport the proxy module from JSON configuration<\/h3>\n
Exporting a Crescendo JSON configuration file results in a PowerShell module that can be shared\nlocally, on GitHub, and on the PowerShell Gallery. Crescendo includes the\nExport-CrescendoModule<\/code> cmdlet that generates the proxy module from the JSON configuration file.<\/p>\n\n- The ConfigurationFile<\/strong> parameter should include the name and path to the JSON configuration file.<\/li>\n
- The ModuleName<\/strong> parameter contains the name of the exported module.<\/li>\n<\/ul>\n
Export-CrescendoModule -ConfigurationFile .get-ipconfig.crescendo.json -ModuleName Ipconfig.psm1\r\n<\/code><\/pre>\nUsing your Crescendo module<\/h3>\n
Once you have created the module with Crescendo, you can install and import it like any other\nmodule. Keep in mind you will need the original native command available wherever you install the\nCrescendo module.<\/p>\n
PS> Import-Module .ipconfig.psm1\r\nPS> Get-IpConfig -All | Select-Object -Property ipv4address, DefaultGateway, subnetmask\r\n\r\nipv4address DefaultGateway subnetmask\r\n----------- -------------- ----------\r\n\r\n172.24.112.1 255.255.240.0\r\n192.168.94.2 {fe80::145e:1779:5cfa:c2a5%8, 192.168.94.1} 255.255.255.0\r\n<\/code><\/pre>\nHow you can help<\/h2>\n
Our goal is to make it easier to convert your native commands to PowerShell cmdlets and receive the\nbenefits that PowerShell provides. We value your ideas and feedback and hope you will give Crescendo\na try, then stop by our GitHub repository and let us know of any issues or features you would like\nadded.<\/p>\n