Archive

Archive for September, 2007

Essential PowerShell: Avoid shorthand in shared PowerShell scripts

September 6, 2007 2 comments

While this topic may be the subject of debate and it has certainly been discussed to some extent before, I am a firm believer that PowerShell script authors should completely avoid shorthand in their shared PowerShell scripts.  Shorthand should only be used when using PowerShell interactively from the console.  I consider this a best practice when working with PowerShell.  There are four reasons for this that all boil down to providing a better user experience: readability, integrated help support, portability and upgradability.  I’ll explain.

Readability

PowerShell scripts written without any shorthand are as close to self-documenting as you can get.  If the cmdlets and parameters (and variables!) being used are intelligently named, you should be able to read a script containing cmdlets and/or parameters (and variables!) that you haven’t used before and have a general idea what the script is going to do.  PowerShell’s verb-noun format for cmdlets goes a long way to facilitate that.  Having readable scripts is also necessary for maintenance reasons so that scripts maintained by multiple authors are understandable to all authors.

Integrated Help Support 

PowerShell is still new and will likely be new for a while yet.  Many people new to PowerShell will use sample scripts to learn the language, and it will be much easier for them to learn from sample scripts if they use full cmdlet and parameter names.  That way they can take full advantage of the rich help system that is integrated within PowerShell by using it to learn more about PowerShell scripts they find on the web or in products that expose integrated PowerShell scripts such as PowerGUI.  To illustrate this point, let’s look at a sample script where using shorthand can harm the user experience of other PowerShell users.

Here’s a sample script using shorthand that will retrieve the expanded parameter sets for the get-command cmdlet:

gcm -name get-command -type cmdlet | select -expand parametersets

And here’s that same sample script without any shorthand:

Get-Command -name Get-Command -commandType Cmdlet | Select-Object -expandProperty ParameterSets

If someone new to PowerShell is trying to figure out what the different parts of this script do, they can use the get-help cmdlet or help alias on the parts of the script.  This can be especially important if English isn’t their first language (the integrated help documentation in PowerShell has already been localized in many different languages to reduce the learning curve for people whose first language is not English).  For the sample script, they might try to look up help for the gcm command, the name parameter, the type parameter, the select command, or the expand parameter.  Here are the PowerShell commands to do just that:

  1. Get-Help gcm
  2. Get-Help gcm -parameter name
  3. Get-Help gcm -parameter type
  4. Get-Help select
  5. Get-Help select -parameter expand

Of these 5 commands, 2 will fail.

The third command fails because the Get-Command cmdlet does not have a Type parameter.  Type is the alias for the CommandType parameter, and PowerShell 1.0 does not resolve alias names when passed in as the value of the Parameter parameter.

The fifth command fails because the Select-Object cmdlet does not have an expand parameter.  But expand isn’t an alias for a parameter either.  In PowerShell 1.0, part of the parameter name resolution logic includes support for identifying parameters by the shortest substring that uniquely identifies the parameter or an alias to the parameter when compared with a list of parameters and aliases for the cmdlet.  In this case, expand is a substring of expandProperty and there are no other parameters beginning with “expand”, so PowerShell deduces that the script author is referring to expandProperty and lets the script run accordingly without warnings or errors.

Had the script been written without any shorthand, as in the second sample, then all attempts to look up the same help information would succeed.  Here are the same Get-Help commands but without any shorthand:

  1. Get-Help Get-Command
  2. Get-Help Get-Command -parameter name
  3. Get-Help Get-Command -parameter commandType
  4. Get-Help Select-Object
  5. Get-Help Select-Object -parameter expandProperty

 All 5 of these commands work as expected.

Portability

As Jeffrey Snover indicated in his blog post titled “Is it safe to use ALIASES in scripts?“, aliases are not constant and can be removed.  While this would likely only happen rarely in practice, PowerShell scripts using aliases are not guaranteed to be portable to other environments and should be avoided.

Upgradability

As I mentioned earlier in this post, part of the parameter name resolution logic in PowerShell 1.0 includes support for identifying parameters by the shortest substring that uniquely identifies the parameter or an alias to the parameter when compared with a list of parameters and aliases for the cmdlet.  This means we could have written the above sample script like this:

 gcm -na get-command -ty cmdlet | select -exp parametersets

In this case, “na” is the shortest substring that uniquely identifies the name parameter, “ty” is the shortest substring that uniquely identifies the type alias for the commandType parameter, and “exp” is the shortest substring that uniquely identifies the expandProperty parameter.  While this works fine just now, you cannot depend on this sample continuing to work in future releases of PowerShell.  Why?  Because there is no guarantee that another parameter or alias will not be added in a future release that would make one of these substrings ambiguous.  In fact, you cannot depend on this sample working in the current release of PowerShell for users who have added parameter aliases that would make one of these substrings ambiguous either.

For these four reasons, PowerShell authors should be diligent about avoiding use of shorthand in shared PowerShell scripts.  While using aliases for cmdlets, parameters and functions and shorthand to identify parameters is very useful when using PowerShell interactively, it can negatively impact the user experience of others when used in PowerShell scripts and therefore should be avoided (with few exceptions, if any).

Kirk out.

Technorati Tags: , , ,

Follow

Get every new post delivered to your Inbox.

Join 47 other followers