|
| 1 | +--- |
| 2 | +title: What's new in Crescendo 1.1 |
| 3 | +description: New features and changes released in Crescendo 1.1 |
| 4 | +ms.date: 12/13/2022 |
| 5 | +--- |
| 6 | +# What's new in Crescendo 1.1 |
| 7 | + |
| 8 | +This preview includes a new cmdlet, a new schema, support for argument value transformation, the |
| 9 | +ability to bypass the output handler, and improved error handling. |
| 10 | + |
| 11 | +## New schema version |
| 12 | + |
| 13 | +The Crescendo schema has been updated to include support for two new members to the **Parameter** |
| 14 | +class, `ArgumentTransform` and `ArgumentTransformType`. The schema works with supported tools like |
| 15 | +Visual Studio Code to provide IntelliSense and tooltips during the authoring experience. |
| 16 | + |
| 17 | +URL location of the always-available Crescendo schema: |
| 18 | + |
| 19 | +```json |
| 20 | +{ |
| 21 | + "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2022-06", |
| 22 | + "Commands": [] |
| 23 | +} |
| 24 | +``` |
| 25 | + |
| 26 | +## New `Export-CrescendoCommand` cmdlet |
| 27 | + |
| 28 | +This cmdlet creates JSON configuration files for Crescendo **Command** objects. It can create one |
| 29 | +JSON file per **Command** object or create one JSON file containing all objects passed to it. |
| 30 | + |
| 31 | +Crescendo **Command** objects can be created using `New-CrescendoCommand` or imported from an |
| 32 | +existing configuration using `Import-CommandConfiguration`. |
| 33 | + |
| 34 | +For more information, see [Export-CrescendoCommand][01]. |
| 35 | + |
| 36 | +## Prevent overwriting of the module manifest |
| 37 | + |
| 38 | +Crescendo creates both the module `.psm1` and the module manifest `.psd1` when |
| 39 | +`Export-CrescendoModule` is executed. This can create problems when you have customized the module |
| 40 | +manifest beyond the scope of Crescendo. The `Export-CrescendoModule` cmdlet now provides a |
| 41 | +**NoClobberManifest** switch parameter to prevent the manifest from being overwritten. |
| 42 | + |
| 43 | +```powershell |
| 44 | +Export-CrescendoModule -ConfigurationFile .\myconfig.json -ModuleName .\Mymodule -NoClobberManifest |
| 45 | +``` |
| 46 | + |
| 47 | +> [!NOTE] |
| 48 | +> The **NoClobberManifest** parameter prevents Crescendo from updating the module manifest. You are |
| 49 | +> responsible for manually updating the manifest with any new cmdlets and settings. |
| 50 | +
|
| 51 | +## Bypass output handling entirely |
| 52 | + |
| 53 | +Some native commands create different output depending on whether the output is sent to the screen |
| 54 | +or the pipeline. [Pastel][02] is an example of a command that changes its output from a graphical |
| 55 | +screen representation to a single string value when used in a pipeline. Crescendo output handling is |
| 56 | +pipeline based and can cause these applications to return unwanted results. Crescendo now supports |
| 57 | +the ability to bypass the output handler entirely. |
| 58 | + |
| 59 | +To bypass all output handling by Crescendo: |
| 60 | + |
| 61 | +```json |
| 62 | +"OutputHandlers": [ |
| 63 | + { |
| 64 | + "ParameterSetName": "Default", |
| 65 | + "HandlerType": "ByPass" |
| 66 | + } |
| 67 | +] |
| 68 | +``` |
| 69 | + |
| 70 | +## Handling error output |
| 71 | + |
| 72 | +Previously, native command errors weren't captured by Crescendo and allowed to stream directly to |
| 73 | +the user. This prevented you from creating enhanced error handling. Crescendo now captures the |
| 74 | +generated command error output (stderr) and it's now available to the output handler . Error messages |
| 75 | +are placed in a queue. You can access the queue in your output handler using a new internal |
| 76 | +function, `Pop-CrescendoNativeError`. |
| 77 | + |
| 78 | +If you don't define an output handler, Crescendo uses the default handler. The default output |
| 79 | +handler ensures that errors respect the `-ErrorVariable` and `-ErrorAction` parameters and adds |
| 80 | +errors to `$Error`. |
| 81 | + |
| 82 | +Adding an output handler that includes `Pop-CrescendoNativeError` allows you to inspect errors in |
| 83 | +the output handler so you can handle them or pass them through to the caller. |
| 84 | + |
| 85 | +```json |
| 86 | +"OutputHandlers": [ |
| 87 | + { |
| 88 | + "ParameterSetName": "Default", |
| 89 | + "StreamOutput": true, |
| 90 | + "HandlerType": "Inline", |
| 91 | + "Handler": "PROCESS { $_ } END { Pop-CrescendoNativeError -EmitAsError }" |
| 92 | + } |
| 93 | +] |
| 94 | +``` |
| 95 | + |
| 96 | +## Argument value transformation |
| 97 | + |
| 98 | +You may find situations where the input values handed to a Crescendo wrapped command should be |
| 99 | +translated to a different value for the underlying native command. Crescendo now supports argument |
| 100 | +transformation to support these scenarios. We updated the schema to add two new members to the |
| 101 | +**Parameter** class, `ArgumentTransform` and `ArgumentTransformType`. Use these members to transform |
| 102 | +parameter arguments inline or invoke a script block that takes the parameter value as an argument. |
| 103 | +The default value for `ArgumentTransformType` is inline. |
| 104 | + |
| 105 | +Example: Multiplication of a value. |
| 106 | + |
| 107 | +```json |
| 108 | +"Parameters": [ |
| 109 | + { |
| 110 | + "Name": "mult2", |
| 111 | + "OriginalName": "--p3", |
| 112 | + "ParameterType": "int", |
| 113 | + "OriginalPosition": 2, |
| 114 | + "ArgumentTransform": "param([int]$v) $v * 2" |
| 115 | + } |
| 116 | +] |
| 117 | +``` |
| 118 | + |
| 119 | +Example: Accepting an ordered hashtable. |
| 120 | + |
| 121 | +```json |
| 122 | +"Parameters": [ |
| 123 | + { |
| 124 | + "Name": "hasht2", |
| 125 | + "OriginalName": "--p1ordered", |
| 126 | + "ParameterType": "System.Collections.Specialized.OrderedDictionary", |
| 127 | + "OriginalPosition": 0, |
| 128 | + "ArgumentTransform": "param([System.Collections.Specialized.OrderedDictionary]$v) $v.Keys.ForEach({''{0}={1}'' -f $_,$v[$_]}) -join '',''" |
| 129 | + } |
| 130 | +] |
| 131 | +``` |
| 132 | + |
| 133 | +Example: Argument transformation with join. |
| 134 | + |
| 135 | +```json |
| 136 | +"Parameters": [ |
| 137 | + { |
| 138 | + "Name": "join", |
| 139 | + "OriginalName": "--p2", |
| 140 | + "ParameterType": "string[]", |
| 141 | + "OriginalPosition": 1, |
| 142 | + "ArgumentTransform": "param([string[]]$v) $v -join '',''" |
| 143 | + } |
| 144 | +] |
| 145 | +``` |
| 146 | + |
| 147 | +Example: Calling a script based transformation. |
| 148 | + |
| 149 | +```json |
| 150 | +"Parameters": [ |
| 151 | + { |
| 152 | + "Name" : "Param1", |
| 153 | + "ArgumentTransform": "myfunction", |
| 154 | + "ArgumentTransformType" : "function" |
| 155 | + } |
| 156 | +] |
| 157 | +``` |
| 158 | + |
| 159 | +## Installing Crescendo |
| 160 | + |
| 161 | +Requirements: |
| 162 | + |
| 163 | +- **Microsoft.PowerShell.Crescendo** requires PowerShell 7.0 or higher |
| 164 | + |
| 165 | +To install **Microsoft.PowerShell.Crescendo** using the new **PowerShellGet** v2.x: |
| 166 | + |
| 167 | +```powershell |
| 168 | +Install-Module -Name Microsoft.PowerShell.Crescendo -AllowPreRelease |
| 169 | +``` |
| 170 | + |
| 171 | +To install **Microsoft.PowerShell.Crescendo** using the new [PowerShellGet v3][03]: |
| 172 | + |
| 173 | +```powershell |
| 174 | +Install-PSResource -Name Microsoft.PowerShell.Crescendo -AllowPreRelease |
| 175 | +``` |
| 176 | + |
| 177 | +<!-- link references --> |
| 178 | +[01]: /powershell/module/microsoft.powershell.crescendo/export-crescendocommand |
| 179 | +[02]: https://github.com/sharkdp/pastel |
| 180 | +[03]: https://www.powershellgallery.com/packages/PowerShellGet/3.0.17-beta |
0 commit comments