Improving Parameter Set Design

PowerShell Team

Designing useable cmdlets is part engineering and part art. It’s not an easy task to define the conceptual boundaries of a cmdlet (where does one cmdlet end and the next begin) or to provide great feature control without inundating the user with parameters.

However, you can improve the usability of your cmdlets by avoiding two common parameter set design flaws.

• A parameter set with no mandatory parameters in a cmdlet that requires parameters
• Mandatory parameters with position numbers that are higher than the position numbers of optional parameters

Parameter sets with no mandatory parameters

Some cmdlets, like Get-Process, can be run without any parameters, so you’d expect them to have at least one parameter set with no mandatory parameters.

But look at the syntax of Get-WmiObject. The first three parameter sets have no mandatory parameters, which implies that there is at least one valid command without parameters. But you cannot run Get-WmiObject without parameters. If you try, you get the default parameter set, which has the Class mandatory parameter.

But it’s worse. To use any of the first three parameter sets, you have to specify one of the parameters that is unique to those parameter sets. And good luck finding the unique parameter in the syntax block. It’s like playing Where’s Waldo when you’re on deadline.

Unless you can run the cmdlet without parameters, be sure that there is at least one mandatory parameter in each parameter set. This better reflects the use of the cmdlet and makes it easier for users to interpret the parameter sets in the syntax block.

Mandatory parameters with high position numbers

When Get-Command displays command syntax, it uses the following rule to determine the order of parameters in the syntax block:

1. Mandatory
2. Position
3. Alphabetical by name

So, all of the mandatory parameters appear before any of the optional ones. Which is what users expect.

But users also expect the parameters to be listed in position order. They expect to be able to construct a valid command by following the syntax diagram from left to right.

However, if a mandatory parameter has a higher position number than an optional parameter, the parameters are not in position order in the syntax block.

I was recently asked to review a cmdlet spec where the mandatory parameter in the parameter set had position 2 and an optional parameter had position 1. We quickly swapped them, resulting in a much improved user experience.

Cmdlet design is an art. But a little engineering guidance goes a long way, too.

June Blender [MSFT]
Windows PowerShell Documentation

PowerShell Team PowerShell Team, PowerShell

Follow