Running show-command for a cmdlet

Running show-command for a cmdlet

Rate This
  • Comments 11

 

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

clip_image002

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:

clip_image004

clip_image006

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:

clip_image008

 

Lucio Silveira [MSFT]

Leave a Comment
  • Please add 8 and 8 and type the answer here:
  • Post
  • Really cool feature for users, who do not know what is PowerShell.

    This UI is written with WPF?

  • Very cool.

    I have an open request on Connect to a add a feature for formatting paramters as a hash table for splatting:

    connect.microsoft.com/.../ise-option-to-collapse-a-cmdlets-parameters-and-arguments-to-hash-for-splatting

    This uses the same initial logic as the POC I wrote for that - select a paramter set, and then select the parameters you want from that set.  I think it would be really cool if that kind of functionality was added to Show-Command by having a Copy Hash option.

    (Apologies if a dupe of this comment shows up.  I had a network glitch on the first one).

  • Does it work for 'function cmdlets' or just the compiled ones?

  • @stukselbax - I think it's useful for more than just people who don't know PowerShell. Even if you're an expert, there are going to be commands that you've never used before, and this will be a great way to explore the available command line options for those commands. Thanks to the PowerShell team for adding this feature!

    One recommendation if it's not too late - I would make the command that is executed via show-command be always displayed on the command line before executing. I see that you can view the command by pressing the up arrow key to access the history, but most people aren't going to do that. In my opinion, it's valuable to always display the command as a way of educating people in the use of PowerShell. If all users know is the show-command method, they'll never be as productive as they could be, and their opinion of PowerShell may be diminished because of it.

  • Does anyone know if there is documentation somewhere explaining how to load a Cmdlet using the module auto-loading that is described at technet.microsoft.com/.../hh857339.aspx I'm trying to develop a simple Cmdlet using Visual Studio 2010 and C#. I'm hoping that the new functionality simply lets you put a Cmdlet derived class in a library and add it to your path and have that picked up automatically. Developing Cmdlets really does seem to be far more complicated that it should be. Why isn't there a template in Visual Studio for developing Cmdlets? Why does the documentation for this seem to suck so bad?

    I found the following article that looks like it would be useful community.bartdesmet.net/.../easy-windows-powershell-cmdlet-development-and-debugging.aspx, but, the links to the images are broken.

    I don't understand why creating and running a Cmdlet is so complicated. Microsoft really needs to include support for this in Visual Studio. All this registering of modules, etc., etc. seems way more complicated than it should be.

  • I was able to get it to work using module auto-loading. I think the problem was that I was putting the .dll directly in the ~/Documents/WindowsPowerShell/Modules directory and it seems to want it to be in a subdirectory in that directory. I also figured out how to debug the Cmdlet in Visual Studio by setting the properties for the library project to start powershell.exe as an external program and then set the command line arguments to "-NoExit -Command "& { Import-Module .\MyLibrary.dll }"" Maybe I just haven't found it yet, but, it seems like tips like this should be included in the PowerShell documentation. I think part of my confusion was because I was looking at documentation from older versions of PowerShell. E.g. PowerShell 1.0 where you had to register "snap-ins" etc. It would be good if the class library documentation indicated the version at the top of the pages like it does for the .NET Framework class library documentation proper. Also, confusingly, the documentatoin appears in two places. There is documentation that looks more like it does with the standard .NET MSDN documentation, and then there is separate documentation that is styled differently for Windows Client. It's unclear which set of documentation is more up to date. I think PowerShell class library documentation should look exactly as it does for the .NET Framework and it should indicate the version.

    One other problem that I ran into though is that if the assembly containing the Cmdlet references other assemblies and if those assemblies are in the same directory, it won't find them. I'm assuming that maybe I'll need to set a path variable or something.

    It would also be nice if Remove-Module actually unloaded the assembly so that you could update the assembly without having to completely restart PowerShell.

  • Jon, thanks for your feedback. Two pointers that will help:

    Installing Modules: msdn.microsoft.com/.../dd878350(v=vs.85).aspx

    Module Manifests: msdn.microsoft.com/.../dd878337(v=vs.85).aspx

    Also, there isn't a way to unload an assembly once it's been loaded. This is a .NET Framework limitation.

  • Is there any guidance or best practice around the number of parameter sets that a cmdlet should have before it gets over complicated and should be a separate cmdlet ?

  • Answering to stukselbax, yes the UI is written in WPF.

    Lucio [MSFT]

  • Answering to:

       Does it work for 'function cmdlets' or just the compiled ones?

    yes, it does work on function cmdlets.

               Lucio [MSFT]

  • Great. But Name can be a list - how is this visually addressed. Here you need to enter comma (,) but would it be great to be able to enter each value on a line of multi-line edit? At least it should be shown which parameters accept a list and which accept only a single value.

Page 1 of 1 (11 items)