Skip to content

Commit 1107dd0

Browse files
sdwheelermichaeltlombardi
sdwheeler
and
michaeltlombardi
authored
Fixes #122 - Update docs for Crescendo 1.1 (#123)
* Update docs for Crescendo 1.1 * Update reference/docs-conceptual/Crescendo/whats-new/whats-new-in-crescendo-11.md Co-authored-by: Mikey Lombardi (He/Him) <[email protected]>
1 parent 341f4d3 commit 1107dd0

15 files changed

+523
-70
lines changed

‎reference/docs-conceptual/Crescendo/overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The Crescendo framework has two main components:
2121
- Output handler functions that parse the output from the command-line tool and return objects
2222

2323
The Crescendo module provides cmdlets to help you create the JSON configurations and build a module
24-
containing the the cmdlets you defined. You must write your own output handler functions that return
24+
containing the cmdlets you defined. You must write your own output handler functions that return
2525
PowerShell objects.
2626

2727
### Crescendo-specific terminology

‎reference/docs-conceptual/Crescendo/whats-new/whats-new-in-crescendo-11.md

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
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

‎reference/docs-conceptual/toc.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ items:
1717
href: Crescendo/get-started/create-new-cmdlet.md
1818
- name: Generate and test a Crescendo module
1919
href: Crescendo/get-started/generate-module.md
20+
- name: What's new
21+
items:
22+
- name: What's new in Crescendo 1.1
23+
href: Crescendo/whats-new/whats-new-in-crescendo-11.md
2024
- name: Advanced topics
2125
items:
2226
- name: Create a configuration using the cmdlets

‎reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Describes the purpose of the Crescendo module.
33
Locale: en-US
4-
ms.date: 08/18/2022
4+
ms.date: 12/13/2022
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.crescendo/about/about_Microsoft.PowerShell.Crescendo?view=ps-modules.1&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about_Microsoft.PowerShell.Crescendo
@@ -36,8 +36,8 @@ authoring process.
3636

3737
## Parameter handling
3838

39-
The PowerShell Crescendo module allows you to interact with parameters of native
40-
commands in the same way you do with cmdlets.
39+
The PowerShell Crescendo module allows you to interact with parameters of
40+
native commands in the same way you do with cmdlets.
4141

4242
## Output Handling
4343

@@ -86,15 +86,14 @@ The following JSON is a minimal example that wraps the unix `/bin/ls` command:
8686

8787
The name of the proxy function is `Get-FileList` and has two parameters:
8888

89-
- **Path**
90-
- Which is Position 0, and has a default value of "."
91-
- **Detail**
92-
- Which is a switch parameter and adds `-l` to the native command parameters
89+
- **Path** - Which is Position 0, and has a default value of "."
90+
- **Detail** - Which is a switch parameter and adds `-l` to the native command
91+
parameters
9392

9493
A couple of things to note about the Path parameter
9594

9695
- The `OriginalPosition` is set to 1 and the `OriginalName` is set to an empty
97-
string. This is because some native commands have a parameter that is _not_
96+
string. This is because some native commands have a parameter that's _not_
9897
named and must be the last parameter when executed. All parameters get
9998
ordered by the value of `OriginalPosition` (the default is 0). When the
10099
native command is called, those parameters (and their values) are put in that
@@ -154,16 +153,15 @@ The PowerShell Crescendo module is still in the development process, so we
154153
expect changes to be made.
155154

156155
The GitHub repository may be found at:
157-
[https://github.com/PowerShell/Crescendo](https://github.com/PowerShell/Crescendo).
156+
[https://github.com/PowerShell/Crescendo][03].
158157

159-
PowerShell Blog posts that present the rational and approaches for native
160-
command wrapping can be found here:
158+
The following PowerShell Blog posts present the rational and approaches for
159+
native command wrapping:
161160

162-
**Native commands in PowerShell a new approach**
161+
- [Native commands in PowerShell a new approach - Part 1][02]
162+
- [Native commands in PowerShell a new approach - Part 2][01]
163163

164-
- [Part 1](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach/)
165-
- [Part 2](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach-part-2)
166-
167-
## Keywords
168-
169-
Native Command
164+
<!-- link references -->
165+
[01]: https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach-part-2
166+
[02]: https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach/
167+
[03]: https://github.com/PowerShell/Crescendo

0 commit comments

Comments
 (0)