This post will be about my first experiences with the PowerShell Crescendo module, which was just released in Preview 1.

Now, why would I care to write a post about a preview of a module?

The reason is quite simple. This module is, in my opinion, covering something that was missing in PowerShell. Namely the possibility to use native commands, and present the results as objects.

The blog post by Jason Helmick I linked to earlier explains this all in more detail.

What follows are my first, admittedly simple, trials using the Crescendo module. If you don’t want to copy code from this post, I created the VMW-Crescendo repository that contains all the files.

An Example

The first example I tackled is the DOS command tasklist, which displays a list of the running processes. 

Not to complicate things at the start, I decided to only implement the module for running tasklist on the local computer.

And needless to say, since this is a DOS command, it will not run on other platforms besides Windows.

The idea behind the Crescendo module is that you write in JSON, how the cmdlet(s) you will create use the native command. This not only includes specifying which parameters are used but also how the returned output will be converted to an object.

Since PowerShell contains cmdlets to convert to and from JSON, I decided to try and write those definitions in PowerShell. And then convert that code to JSON format, which I could then feed to the Crescendo cmdlet.

The Code

#Requires -Version 7.0

#region An example

$taskConfig = @{
  '$schema' = './Microsoft.PowerShell.Crescendo.Schema.json'
  'Verb' = 'Get'
  'Noun' = 'TaskList'
  'OriginalName' = 'tasklist'
  'OriginalCommandElements' = @("/V")
  'OutputHandlers' = @(
        @{
            'ParameterSetName' = 'Default'
            'Handler' = {
              $labels = $args[0][1]
              $index = 0
              $fieldInfo = $args[0][2].Split(' ') | ForEach-Object -Process {
                @{
                  start = $index
                  length = $_.Length
                }
                $index += $_.Length + 1
              }
              $args[0] | Select-Object -skip 3 -PipelineVariable row | ForEach-Object -Process {
                $obj = [ordered]@{}
                $fieldInfo | ForEach-Object -Process {
                  $obj.Add($labels.SubString($_.start,$_.length).Trim(' '),$row.SubString($_.start,$_.length).Trim(' '))
                }
                New-Object -TypeName PSObject -Property $obj
              }
            }
        }
  )
}

$taskConfig | ConvertTo-Json | Set-Content -Path "$PSScriptRoot\tasklist.json"

Export-CrescendoModule -ConfigurationFile "$PSScriptRoot\tasklist.json" -ModuleName "$PSScriptRoot\TaskList.psm1" -Force -Confirm:$false

#endregion

Annotations

Line 1: Although the blog post mentions that a module generated with Crescendo can be used on PowerShell 5.1 and 7, I noticed that since the generated code uses the ternary operator, this not really the case. Hence the requirement to run this on PowerShell v7.

Line 5-35: As I mentioned earlier, I created the definition of the cmdlets to be created in PowerShell.

Line 10: By default, the tasklist command is started with the /V (for verbose) parameter.

Line 11-33: The OutputHandler is where you define how the output of the native command will be converted to an object. I did have to use some ‘trickery’ to avoid having to use hard-coded offset. Luckily the one can use the underlining to determine the start and length of each column.

Line 37: The Powershell object is converted to JSON code, and saved to a file.

Line 39: The Export-CrescendoModule cmdlet takes the JSON file and generates the module.

Sample Run

The generated modules, at least in this Preview 1, only generate a .psm1 file. You can use the Import-Module pointing to that .psm1 file.

The module contains the Get-TaskList cmdlet, that requires no further parameters and returns a series of objects, containing the results.

Since the Get-TaskList cmdlet returns objects, we can now easily use other PowerShell cmdlets to further handle the returned data. For example:

Get-TaskList | Export-Csv -Path .\TaskList.Csv -NoTypeInformation -UseCulture

The resulting CSV file contains all the data.

VMware Tools Debug Levels

The second example I concocted, uses one of the native commands that come with the installation of the VMware Tools. The VMwareToolboxCmd.exe has the option to get and set the debug levels on the VMware Tools services. 

Note that you need to run this command in Administrator mode.

The Code

#Requires -Version 7.0

#region VMware Tools debug levels

$getDebugConfig = @{
  '$schema' = './Microsoft.PowerShell.Crescendo.Schema.json'
  'Verb' = 'Get'
  'Noun' = 'ToolsDebugSetting'
  'OriginalName' = "$($env:ProgramFiles)\VMware\VMware Tools\VMwareToolboxCmd.exe"
  'Description' = 'Retrieve the debug levels for VMware Tools'
  'OriginalCommandElements' = 'logging','level','get'
  'Parameters' = @(
    @{
      'Name' = 'Svc'
      'OriginalName' = 'vmsvc'
      'ParameterType' = 'switch'
      'Description' = 'Primary VMware Tools service'
    },
    @{
      'Name' = 'Vss'
      'OriginalName' = 'vmvss'
      'ParameterType' = 'switch'
      'Description' = 'Volume Shadow Copy service'
    },
    @{
      'Name' = 'Resolution'
      'OriginalName' = 'vmresset'
      'ParameterType' = 'switch'
      'Description' = 'Resolution Set Tool'
    },
    @{
      'Name' = 'Tray'
      'OriginalName' = 'vmtray'
      'ParameterType' = 'switch'
      'Description' = 'The Tray icon in Windows'
    },
    @{
      'Name' = 'User'
      'OriginalName' = 'vmusr'
      'ParameterType' = 'switch'
      'Description' = 'The VMware Tools user service'
    },
    @{
      'Name' = 'Toolbox'
      'OriginalName' = 'toolbox'
      'ParameterType' = 'switch'
      'Description' = 'Toolbox UI'
    },
    @{
      'Name' = 'ToolBoxCmd'
      'OriginalName' = 'toolboxcmd'
      'ParameterType' = 'switch'
      'Description' = 'Toolbox command line'
    }
  )
  'OutputHandlers' = @(
        @{
            'ParameterSetName' = 'Default'
            'Handler' = {
              $service,$level = $args[0].Split('=')
              New-Object -TypeName PSObject -Property @{
                "$($service -replace '.level','')" = $level.Trim(' ')
              }
            }
        }
  )
}
$getDebugConfig | ConvertTo-Json | Set-Content -Path "$PSScriptRoot\getdebug.json"

$setDebugConfig = @{
  '$schema' = './Microsoft.PowerShell.Crescendo.Schema.json'
  'Verb' = 'Set'
  'Noun' = 'ToolsDebugSetting'
  'OriginalName' = "$($env:ProgramFiles)\VMware\VMware Tools\VMwareToolboxCmd.exe"
  'Description' = 'Retrieve the debug levels for VMware Tools'
  'OriginalCommandElements' = 'logging', 'level', 'set'
  'Parameters' = @(
    @{
      'Name' = 'Svc'
      'OriginalName' = 'vmsvc'
      'ParameterType' = 'switch'
      'Description' = 'Primary VMware Tools service'
    },
    @{
      'Name' = 'Vss'
      'OriginalName' = 'vmvss'
      'ParameterType' = 'switch'
      'Description' = 'Volume Shadow Copy service'
    },
    @{
      'Name' = 'Resolution'
      'OriginalName' = 'vmresset'
      'ParameterType' = 'switch'
      'Description' = 'Resolution Set Tool'
    },
    @{
      'Name' = 'Tray'
      'OriginalName' = 'vmtray'
      'ParameterType' = 'switch'
      'Description' = 'The Tray icon in Windows'
    },
    @{
      'Name' = 'User'
      'OriginalName' = 'vmusr'
      'ParameterType' = 'switch'
      'Description' = 'The VMware Tools user service'
    },
    @{
      'Name' = 'Toolbox'
      'OriginalName' = 'toolbox'
      'ParameterType' = 'switch'
      'Description' = 'Toolbox UI'
    },
    @{
      'Name' = 'ToolBoxCmd'
      'OriginalName' = 'toolboxcmd'
      'ParameterType' = 'switch'
      'Description' = 'Toolbox command line'
    },
    @{
      'Name' = 'Level'
      'OriginalName' = ''
      'ParameterType' = 'string'
      'Mandatory' = $true
      'Description' = 'New debug level'
    }
    )
    }
$setDebugConfig | ConvertTo-Json | Set-Content -Path "$PSScriptRoot\setdebug.json"

$sCrecendo = @{
  ConfigurationFile = "$($PSScriptRoot)\getdebug.json", "$($PSScriptRoot)\setdebug.json"
  ModuleName = "$($PSScriptRoot)\ToolsDebug.psm1"
  Force = $true
  Confirm = $false
  Verbose = $true
}
Export-CrescendoModule @sCrecendo
#endregion

Annotations

Line 1: Although the blog post mentions that a module generated with Crescendo can be used on PowerShell 5.1 and 7, I noticed that since the generated code uses the ternary operator, this not really the case. Hence the requirement to run this on PowerShell v7.

Line 5-66: This part is the definition for the Get-ToolsDebugSettings cmdlet.

Line 11: With the OriginalCommandElements property we define which parameters shall be always added to the native command.

Line 12-55: Each possible service is defined as a Switch parameter. Each entry also has the cmdlet parameter name (Name) and how it shall be translated to a native command parameter (OriginalName).

Line 59-63: The Output Handler takes the line that is returned and converts it into an object.

Line 68: The PowerShell object is converted into JSON and save to a file.

Line 70-128: This part is the definition for the Set-ToolsDebugSettings cmdlet.

Line 120-126: The Set cmdlet will have an additional parameter (Level) that indicates which new debug level shall be set for the selected service. Note that the debuglevel is added as-is, no parameter on the native command.

Sample Run

The cmdlets from the generated module need to be called from an elevated prompt (same as the native command).

#Requires -Version 7.0

Import-Module "$PSScriptRoot\ToolsDebug.psm1" -Force

Get-ToolsDebugSetting -Vss
Set-ToolsDebugSetting -Vss -Level debug
Get-ToolsDebugSetting -Vss

And just as with the native command we can query and set the debug levels.

In Conclusion

Is this new Crescendo module something that you should be using immediately?

Definitely not, this is a module, based on an interesting concept, that only just entered Preview 1.

But it is surely a concept that is interesting.
I’ll be watching where this goes, and what can be done with it.

Enjoy!