Tag Archives: Get-Alias

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.

Create a Function to Open Internet Explorer (Like in Run)

Even before Windows PowerShell, I strove to do things quickly. One such thing was to open Internet Explorer (IE) from the Run dialog. In the image below, you can see how you can enter iexplore followed by a space and then a URL. When you press OK, it will launch IE and direct itself to the URL that was passed along. If no URL is provided, it will open the home page.

Create Function to Open Internet Explorer (Like in Run)01

When I transferred this knowledge to PowerShell, I was sad to see that entering the same thing in the console host resulted in an error: “The term ‘iexplore’ is not recognized as the name of a cmdlet, function, script file, or operable program.”  I wasn’t overly concerned about it, moved on, and mostly forgot about it.

After spending last week at the PowerShell Summit North America 2015, I saw several demos from speakers that included ‘start iexplore <URL>,’ where start is an alias for Start-Process. Use Get-Alias to see this yourself: Get-Alias -Name start. I decided I would write up a simple function, to add to my profile, that would allow me to just use iexplore again.

With the function below, in place, I can enter iexplore in PowerShell to open Internet Explorer to the home page, or iexplore bing.com to open Internet Explorer to bing.com, for example — pretty straightforward. Here it is: the little function that saves me six keystrokes every time I use it. Don’t worry, it won’t be long before I make up for the lost keystrokes from writing the function itself.

Function iexplore {
	Param ([string]$Url)

	If ($Url) {
		start iexplore $Url
	} Else {
		start iexplore
	}
}

And, here’s the results.

Create Function to Open Internet Explorer (Like in Run)02

Before we close for the day, we should probably makes a couple changes to our function. We should change the function name so it uses an approved verb, along with the verb-noun naming convention, and then create an alias (iexplore), to call the function.

Set-Alias -Name iexplore -Value Open-InternetExplorer

Function Open-InternetExplorer {
	Param ([string]$Url)

	If ($Url) {
		start iexplore $Url
	} Else {
		start iexplore
	}
}

Add CMD’s ver to PowerShell

One of the great things about Windows PowerShell is that it can run Windows native command line tools, such as ping, ipconfig, and others. There are times, however, when there are exceptions. While recently working in the console, I brainlessly entered ‘ver’ (without the quotes), and it didn’t return what I expected. Instead of printing ‘Microsoft Windows [Version 6.3.9600]’ to the console, it reported that ver wasn’t recognized.

PS C:\> ver
ver : The term 'ver' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the
spelling of the name, or if a path was included, verify that the path is correct and try again.
At line:1 char:1
+ ver
+ ~~~
    + CategoryInfo          : ObjectNotFound: (ver:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

While I wouldn’t recommend opening CMD to run the command, because seriously get out of that habit already, you can switch to CMD from inside the PowerShell console, as demonstrated below.

PS C:\> cmd
Microsoft Windows [Version 6.3.9600]
(c) 2013 Microsoft Corporation. All rights reserved.

C:\>ver

Microsoft Windows [Version 6.3.9600]

C:\>exit
PS C:\>

Still, this wasn’t quite as native as I wanted. For whatever reason, I wanted to type ver, and get the identical output I was used to seeing,… regardless of the fact that the ver output doesn’t really tell me much.

The first thing I did was launch the ISE and create an alias for ver. Keep in mind, that you may need to add -ErrorAction SilentlyContinue to the New-Alias cmdlet, if you run the script more than once inside the ISE. The problem here is that you’ll receive an error if you try and create an alias that is already being used. Either that, or you can add the -Force parameter and make New-Alias act like Set-Alias (and overwrite the alias even though it’s not really changing it).

New-Alias -Name ver -Value Get-TMVersion

Next, I constructed a function called Get-TMVersion that the alias ver would use. Inside the function, I created a single variable, $OS, and assigned it the results of a Get-CimInstance command. If for some reason you’re still using PowerShell 2.0, this can be replaced by the Get-WmiObject equivalent: Get-WmiObject -Class Win32_OperatingSystem.

Function Get-TMVersion {
    $OS = Get-CimInstance -ClassName Win32_OperatingSystem
}

Once I have this data stored in a variable, I can begin checking for a value in the variable, and then, building out my results to match the native Windows command. The If statement checks to see if the Name property of $OS begins with the string Microsoft Windows. Providing it does, it sets a second variable, $Version, as seen in the example below. Once that’s complete, it then echos a blank line, the $Version variable, and then echos a second blank line. At this point, $Version should be identical to the ver command’s standard output.

Function Get-TMVersion {
    $OS = Get-CimInstance -ClassName Win32_OperatingSystem
    If ($OS.Name -like 'Microsoft Windows*') {
        $Version = "Microsoft Windows [Version $($OS.Version)]"
    }
    Write-Output -Verbose `r`n$Version`r`n
}

Here’s the function in action.

PS C:\> ver

Microsoft Windows [Version 6.3.9600]

PS C:\>

Boring, but it works. I should note that this function would probably be best served to include some error checking, in case setting the $OS variable errors out. In addition, I suspect there are probably other ways to produce the same resul–… (pause, keyboard keys clicking) …ugh, here’s a couple variations of yet another, simpler way.

PS C:\> cmd /c ver

Microsoft Windows [Version 6.3.9600]
PS C:\> cmd /c ver;echo ''

Microsoft Windows [Version 6.3.9600]

PS C:\>

It seems I could have just dropped a tiny bit of text into my function and called it a day. If you’ve ever read anything else I’ve written and posted, then you may have noticed a pattern. I seem to do things the hard way, long before I figure out a simpler way. I like it that way, though. If anything, it keeps me thinking, and therefore, improving my PowerShell skills overall.

Function Get-TMVersion {
    cmd /c ver
    Write-Output -Verbose ''
}

about_Aliases

This post is the help rewrite for about_Aliases. While the help files for Windows PowerShell are invaluable, the idea behind a rewrite is so true beginners might even better understand the help file concepts. At times, some things discussed in the Windows PowerShell help file will not be included in a help rewrite. Therefore, it is always best to read the actual help file after reading this post. (PS3.0)

An Alias in Windows PowerShell is a simplified, or quicker, way to type a cmdlet using an alternate name. Get-Alias (or the alias for Get-Alias, gal) will display a list of all of the aliases that the Windows PowerShell session knows about. This includes both built-in aliases and any additional aliases created or imported. The first two examples below, indicate two ways to accomplish the same thing – listing all the aliases. These examples only show the first four results.

PS C:\> Get-Alias

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Alias           % -> ForEach-Object
Alias           ? -> Where-Object
Alias           ac -> Add-Content
Alias           asnp -> Add-PSSnapin

This example uses the alias for the Get-Alias cmdlet, gal.

PS C:\> gal

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Alias           % -> ForEach-Object
Alias           ? -> Where-Object
Alias           ac -> Add-Content
Alias           asnp -> Add-PSSnapin

In order to find the cmdlet associated with a single alias, the alias needs to be provided, as the value for the -Name parameter, to the Get-Alias cmdlet.

PS C:\> gal -Name gc

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Alias           gc -> Get-Content

The name parameter (-Name) is not required to use it. This means that if there is something after the Get-Alias cmdlet, such as gc in this example, then it will default to using the -Name parameter.

PS C:\> gal gc

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Alias           gc -> Get-Content

Windows PowerShell will error if the -Name parameter is supplied with a cmdlet name, or another value that is not an alias.

PS C:\> gal Get-Content

gal : This command cannot find a matching alias because an alias with the name ‘Get-Content’ does not exist.
At line:1 char:1
+ gal Get-Content
+ ~~~~~~~~~~~~~~~
+ CategoryInfo          : ObjectNotFound: (Get-Content:String) [Get-Alias], ItemNotFoundException
+ FullyQualifiedErrorId : ItemNotFoundException,Microsoft.PowerShell.Commands.GetAliasCommand

In order to get an alias (or aliases, if there is more than one) for a cmdlet, the -Definition parameter must be used.

PS C:\> gal -Definition Get-Content

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Alias           cat -> Get-Content
Alias           gc -> Get-Content
Alias           type -> Get-Content

The Get-Service cmdlet returns the computer’s services, the Get-Process cmdlet return the processes running on the computer, and the Get-ChildItem cmdlet returns the directories and/or files from the root of a drive or from a folder. Here is how a user can get the aliases for multiple cmdlets at the same time.

PS C:\> gal -Definition Get-Service,Get-Process,Get-ChildItem

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Alias           gsv -> Get-Service
Alias           gps -> Get-Process
Alias           ps -> Get-Process
Alias           dir -> Get-ChildItem
Alias           gci -> Get-ChildItem
Alias           ls -> Get-ChildItem

There are a few other cmdlets that allow a user to work with aliases. By using the Get-Command cmdlet (or its alias – if it has one), additional cmdlets can be returned that all end with -Alias.

PS C:\> Get-Command *-Alias

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Cmdlet          Export-Alias                                       Microsoft.PowerShell.Utility
Cmdlet          Get-Alias                                          Microsoft.PowerShell.Utility
Cmdlet          Import-Alias                                       Microsoft.PowerShell.Utility
Cmdlet          New-Alias                                          Microsoft.PowerShell.Utility
Cmdlet          Set-Alias                                          Microsoft.PowerShell.Utility

Export-Alias: Exports information about currently defined aliases to a file.

PS C:\> Export-Alias -Path 'C:\aliases.txt'

Import-Alias: Imports an alias, or aliases, from a file.

PS C:\> Import-Alias -Path 'C:\ImportedAliases.txt'

Trying to import aliases that already exists will cause an error for every alias Windows PowerShell tries to import (that already exists).

PS C:\> Export-Alias -Path 'C:\aliases.txt'
PS C:\> Import-Alias -Path 'C:\aliases.txt'
Import-Alias : The alias is not allowed, because an alias with the name ‘ac’ already exists.
At line:1 char:1
+ Import-Alias -Path ‘C:\aliases.txt’
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ResourceExists: (ac:String) [Import-Alias], SessionStateException
    + FullyQualifiedErrorId : AliasAlreadyExists,Microsoft.PowerShell.Commands.ImportAliasCommand

New-Alias: Creates a new alias.
Set-Alias: Changes an existing alias, or creates an alias if it does not already exist.

PS C:\> New-Alias -Name MyAlias -Value Get-Process
PS C:\> MyAlias | select -First 4

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName
-------  ------    -----      ----- -----   ------     -- -----------
    224      19     3440        772   110    16.50   4612 ALMon
    164      14     2476       2108    44     5.36   2744 ALsvc
     77       9     1336       5288    75   137.55   4076 ApMsgFwd
     90       8     1372       5788    76   162.11   4324 ApntEx

PS C:\> Set-Alias -Name MyAlias -Value Get-Service
PS C:\> MyAlias | select -First 4

Status   Name               DisplayName
------   ----               -----------
Running  AdobeARMservice    Adobe Acrobat Update Service
Stopped  AdobeFlashPlaye... Adobe Flash Player Update Service
Stopped  AeLookupSvc        Application Experience
Stopped  ALG                Application Layer Gateway Service

Bonus Information

Use the Measure-Object cmdlet, or the count property, to find out how many aliases Windows PowerShell knows about.

PS C:\> Get-Alias | Measure-Object

Count    : 182
Average  :
Sum      :
Maximum  :
Minimum  :
Property :

PS C:\> gal | measure

Count    : 182
Average  :
Sum      :
Maximum  :
Minimum  :
Property :

PS C:\> (gal | measure).count
182
PS C:\> (gal).count
182

Real World

While aliases are helpful in the console, the belief is that they should not be used in a script file (.ps1 file). Using full cmdlet names in a script is preferred for script readability. There are plenty of people writing Windows PowerShell who adhere to this best practice even while using aliases for the object cmdlets (select for Select-Object, where for Where-Object, etc.).

Learn More

This information, and more, is stored in the help file about_Aliases that comes with Windows PowerShell. This information can be read by typing any of the commands below. The first example will display the help file in the Windows PowerShell console, the second example will open the full help in it’s own window, the third example will send the contents of the help file to the clipboard (so it can be pasted into Word, Notepad, etc.), and the fourth example will open the help file in Notepad.

PS C:\> Get-Help about_aliases
PS C:\> Get-Help about_aliases -ShowWindow
PS C:\> Get-Help about_aliases | clip
PS C:\> Notepad C:\Windows\System32\WindowsPowerShell\v1.0\en-US\about_Aliases.help.txt

There is a built-in, automatic variable, $PSHOME, that stores the installation path of Windows PowerShell. This means that the third example above could have been partially written using that variable.

PS C:\> Notepad $PSHOME\en-us\about_Aliases.help.txt