Tag Archives: PSScriptAnalyzer

Cmdlet and Function Alias Best Practice

Aliases are a beautiful thing, really. Even though this may be true, we need to make sure we’re following best practice, when we opt to use them. I’m not sure what it is about me, but I get a little antsy whenever I see someone not conforming to a best practice in PowerShell. I really don’t care how you lace and tie your shoes, or make your peanut butter and jelly sandwiches, but when you use your PowerShell aliases is important to me, and it should be to you, too.

The main idea here is that cmdlet and function aliases shouldn’t exist in something that lasts longer than a one time use. That means we shouldn’t see them in help documentation (although, I believe I’ve seen some), in online articles, and in PowerShell-related forum posts. The only time you’ll see me use a cmdlet or function alias, is if you’re looking over my shoulder and watching me type commands into my console, or the ISE’s console pane. Realistically, aliases do two things: One, they help speed up getting results in a one time use scenario, as I’ve mentioned, and two, they confuse PowerShell newcomers that come across a blog where they’ve been used without consideration to best practice. Perhaps it’s my desire to help people learn PowerShell, that’s driving some of this alias indignation. I should mention, that I think it’s acceptable to include them in cases where you also explain that you’re using an alias, and indicate the full cmdlet or function name.

If you showed up here after seeing one of those blogs, or scripts, where someone littered their work with aliases, keep in mind that we have a Get-Alias cmdlet that can help you determine to which cmdlet an alias resolves — we’ll get back to that momentarily. Let’s say you found this command online:

PS> ls c:\windows | ? {$_ -like 'Win*'} | % {echo "$($_.Name)||$($_.LastWriteTime)"}

I understand this command has the potential to be written better. One such way, would be to not pipe to ? in order to filter on the file or directory name, but instead to use the ls -Filter parameter. Weird… in that last sentence, I used a couple aliases instead of their cmdlet names, and even that was confusing. Imagine having read that as a newcomer. This command, since it’s going to live on this webpage “forever,” should have been written like this (for the most part):

PS> Get-ChildItem -Path c:\windows | Where-Object {$_ -like 'Win*'} | ForEach-Object {Write-Output -InputObject "$($_.Name)||$($_.LastWriteTime)"}

It’s longer, there’s no doubt about it, but it’s much more complete and easier to comprehend, especially had you found it in a lengthy script or function.

Back to Get-Alias: If you find yourself confused by a command you found online, where someone “didn’t think of the next person,” then run though the command, or commands, and check the aliases against the Get-Alias cmdlet. Let’s do that below, for the first example command I wrote. Notice that Get-Alias will accept a comma-separated list of (alias) values.

PS> Get-Alias -Name ls,?,%,echo

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Alias           ls -> Get-ChildItem
Alias           % -> ForEach-Object
Alias           ? -> Where-Object
Alias           h -> Get-History
Alias           r -> Invoke-History
Alias           % -> ForEach-Object
Alias           echo -> Write-Output

Now, notice the results. We’ve returned aliases that we didn’t request, such as h for Get-History and r for Invoke-History. Why? A little off topic, but this is because the question mark (?), in regular expressions, or regex, stands in for a single character. The results are not only returning the alias for the question mark, but for any aliases that only have a single character. In order to only return what we want, we’ll need to escape the question mark character and put it in quotes, so that the parser is certain we have supplied the string value, of an actual question mark.

PS> Get-Alias -Name ls,'`?',%,echo

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Alias           ls -> Get-ChildItem
Alias           ? -> Where-Object
Alias           % -> ForEach-Object
Alias           echo -> Write-Output

There, we go.

As a community, we should do things so they better help the current, and future members. Use all the aliases you want, but do so where they won’t exist for someone else to stumble upon, unless, you’ve taken the time to explain that you’ve used an alias, and to which cmdlet it refers.

In closing, I want to mention the PSScriptAnalyzer module. I pulled it down and installed it in PowerShell 5.0, using the Find-Module and Install-Module cmdlets: Find-Module -Name PSScriptAnalyzer | Install-Module. I then copied my alias heavily command above, pasted it into notepad, and saved it as C:\file.ps1. Following that, I ran an Invoke-ScriptAnalyzer command. You can see the command and its results below

PS> Invoke-ScriptAnalyzer -Path C:\file.ps1 -IncludeRule PSAvoidUsingCmdletAliases

RuleName                            Severity     FileName   Line  Message
--------                            --------     --------   ----  -------
PSAvoidUsingCmdletAliases           Warning      file.ps1   1     'echo' is an alias of 'Write-Output'. Alias can
                                                                  introduce possible problems and make scripts hard to
                                                                  maintain. Please consider changing alias to its full
                                                                  content.
PSAvoidUsingCmdletAliases           Warning      file.ps1   1     '%' is an alias of 'ForEach-Object'. Alias can
                                                                  introduce possible problems and make scripts hard to
                                                                  maintain. Please consider changing alias to its full
                                                                  content.
PSAvoidUsingCmdletAliases           Warning      file.ps1   1     '?' is an alias of 'Where-Object'. Alias can
                                                                  introduce possible problems and make scripts hard to
                                                                  maintain. Please consider changing alias to its full
                                                                  content.
PSAvoidUsingCmdletAliases           Warning      file.ps1   1     'ls' is an alias of 'Get-ChildItem'. Alias can
                                                                  introduce possible problems and make scripts hard to
                                                                  maintain. Please consider changing alias to its full
                                                                  content.

The cmdlet was instructed to only return the problems it found with aliases (see the parameter used and the included value). It’s a very powerful cmdlet; not only can you find any alias-related best practice failures, but it’ll help you locate any other areas, where you can improve your code.

Thanks for your time, and… your new dedication to not use cmdlet and function aliases, that last longer than a one time use.

Update: I just saw a post from The Scripting! Guy (http://blogs.technet.com/b/heyscriptingguy/archive/2015/10/25/powertip-group-powershell-cmdlet-count-by-version.aspx) where he used a few aliases and told us what they mean. If you’re going to use them, explain them.