April 12th, 2012

Running show-command for a cmdlet

PowerShell Team
PowerShell Team

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

Image 0042 clip image002 thumb 7241799A

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:

Image 4744 clip image004 thumb 0DE60591 Image 1033 clip image006 thumb 38BE69A3

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:

  1. Initially, the parameters for only one parameter set are displayed (the default parameter set), reducing the information to be understood compared to the syntax.
  2. The braces indicating optional parameters are replaced by the friendlier GUI language of * and enabled/disabled buttons.
  3. 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:

Image 0451 clip image008 thumb 1184206E

 

Lucio Silveira [MSFT]

Author

PowerShell Team
PowerShell Team

PowerShell is a task-based command-line shell and scripting language built on .NET. PowerShell helps system administrators and power-users rapidly automate tasks that manage operating systems (Linux, macOS, and Windows) and processes.

1 comment

Discussion is closed. Login to edit/delete existing comments.

  • Basavaraj, Krishna (US - Bengaluru)

    “In each parameter set tab, parameter names are displayed alphabetically, but mandatory parameters are listed first.”
    But is there a way to use Position  to display based on the Position?