Problem: Figuring out a cmdlet from its syntax can be overwhelming, especially for people new to PowerShell.
PS C:\> get-command get-process -syntax
Get-Process [[-Name] <string[]>] [-ComputerName <string[]>] [-Module] [-FileVersionInfo] [<CommonParameters>]
Get-Process -Id <int[]> [-ComputerName <string[]>] [-Module] [-FileVersionInfo] [<CommonParameters>]
Get-Process -InputObject <Process[]> [-ComputerName <string[]>] [-Module] [-FileVersionInfo] [<CommonParameters>]
Get-command –syntax displays the syntax for the command. The top of get-help will also show this syntax information.
What are all those lines and braces?
If you know the answer, please skip this section.
There is one line per parameter set. The square braces around a parameter indicate the parameter is optional. Square braces around a parameter name, indicate the name is optional (which means the parameter is positional). Angle brackets indicate the parameter type.
A Parameter Set is a mutually exclusive set of parameters. Mutually exclusive means you can either get a process by name, or by id, but not by name and id at the same time. Each parameter set is a different way to interact with the cmdlet, almost like a different cmdlet with the same name.
Some can ask if the parameter sets are a necessary complication. The only way to achieve the same 3 ways to get a process without something like parameter sets would be to have 3 cmdlets like Get-ProcessByName, Get-ProcessById and Get-ProcessByInputObject. If we extend this idea to all cmdlets, Nouns would be on average larger, there would be several names to remember for each cmdlet, separate documentations would be necessary and they would have repeated content referring to what is common between the cmdlets, etc. In summary, Parameter Sets are a great way to solve a somewhat complex problem of different ways to call a cmdlet.
Despite all this greatness, all those braces and lines can be a bit overwhelming for people starting PowerShell and trying to understand a cmdlet (and even for some experts, at a first glance).
Solution: Show-Command is a new cmdlet in PowerShell V3 that displays a graphical user interface for a command with a simpler overview of a cmdlet.
PS C:\> Show-Command Get-Process
Each tab is one Parameter Set for Get-Process. Cmdlets with parameter sets have a default parameter set. In case of get-process the default parameter set is Name, so this is the tab selected by default. Selecting the other tabs will display the following results:
|
|
|
Notice that for Name, the Run button is enabled and for Id and InputObject, Run is disabled. This is because there is no mandatory parameter in the Name parameter set, so it is ready to run, even with no parameter values. The Id parameter in the Id parameter set is mandatory (needs a value). This is indicated by the * near the parameter name. The InputObject parameter in the InputObject parameter set is also mandatory.
It is a very simple GUI, but it achieved some nice results so far regarding the problem it set out to solve:
- Initially, the parameters for only one parameter set are displayed (the default parameter set), reducing the information to be understood compared to the syntax.
- The braces indicating optional parameters are replaced by the friendlier GUI language of * and enabled/disabled buttons.
- The visual separation of the parameter set tabs is an excellent way to convey they are mutually exclusive.
Additional details:
- In each parameter set tab, parameter names are displayed alphabetically, but mandatory parameters are listed first.
- The command run will be placed in history, so if you use “Arrow Up” after running show-command, you can see/modify what was run.
- The Common Parameters section displays Debug, ErrorAction and other parameters common to all cmdlets.
- The Copy button will copy the cmdlet to be run to the clipboard.
- Hovering over a parameter will display a tooltip with additional information about the parameter:
Lucio Silveira [MSFT]