Best Practice for Using Aliases in PowerShell Scripts

Best Practice for Using Aliases in PowerShell Scripts

  • Comments 5
  • Likes

Summary: Microsoft Scripting Guy, Ed Wilson, discusses the use of aliases in Windows PowerShell scripts. He covers the pros and cons in this blog.

Weekend Scripter

Microsoft Scripting Guy, Ed Wilson, is here. “You can have my aliases when you pry my cold dead fingers from my keyboard,” was not one of the emails I received during the 2011 Scripting Games, but it easily could have been. It seems that in the world of Windows PowerShell, two things really seem to cause a lot of heated discussions—one is the use of aliases and the other is what goes in a profile. These two topics can overlap, but for now, I will focus on aliases.

In general, I believe it is a best practice not to use aliases in a script. I also believe it is OK—in fact, I encourage the use of aliases at the Windows PowerShell prompt when one is working in an interactive fashion. Of course, part of the decision point around this depends on the definition of “best.” What do I mean by best?

Here is a scenario to describe one view of best. A couple of weeks ago, the southeastern portion of the United States was hit by massive thunderstorms. Charlotte, North Carolina, unfortunately, was hit with this storm. In the image below, Dr. Scripto assists with cleanup in the aftermath of “The storm that tried to eat the 2011 Scripting Games.”

Image of Dr. Scripto

As luck would have it, this was during the middle of the 2011 Scripting Games. If you follow ScriptingGuys on Twitter, you know that the Scripting Wife and I were without electricity for more than 25 hours (as were over 100,000 other people, so it was not some kind of conspiracy to keep the Scripting Wife from getting her scripts entered on time).

It is 2:00 in the morning and the Scripting Wife wakes me up.

“Can you make that UPS shut up,” she asks.

“Mmmmmrrrrr umph,” I reply in somewhat incoherent speech.

“Come on, wake up. That beeping is driving me crazy,” she complains.

“Huh? Oh, all right,” I say.

The house is completely dark. I grab a flashlight (a “torch” for my friends in the UK), and I tell the Scripting Wife to come with me into the office. I shake the mouse on my desktop to cause it wake up. I open the Windows PowerShell ISE, and I begin to write a script to shut down all 12 computers that are on my home network.

“Hmmm, I say to myself. I think I will query AD with the AdsiSearcher and do a nice LDAP query to retrieve computer objects.”

NOT!

I open the Windows PowerShell console as an Administrator and type the command that is shown here.

Stop-Computer $mycomputers -force

That is it. One reason is that I have a variable in my Windows PowerShell profile that performs the following command.

$mycomputers = Get-Content –path c:\fso\mycomputers.txt

Although it is true that I have two pretty big UPSs in my office to support my twelve computers, networking equipment, and monitor, I am not certain of exactly how long they will keep everything up. In my mind, two o’clock in the morning, during a massive thunderstorm is not the time to be conducting load tests on my power supplies. It is true that I might very well need to run that command again—in fact, with our electric power supplier, it is a virtual certainty I will need the command again, but code reuse was not my top priority at that time. I did not use any aliases in my command; but then, there is no default alias for the Stop-Computer cmdlet. There is nothing to keep one from creating an alias for it. However, I am considering really simplifying things and adding a new function to my profile. It is shown here.

Stop-MyComputers Function

Function Stop-MyComputers

{

 Stop-Computer -ComputerName $mycomputers -Force

} #end function Stop-MyComputers

 

Set-Alias -Name sac -Value Stop-MyComputers -Description "Shutdown all computers"

When do I use aliases?

The previous function and alias combine to form one of my favorite things to do…I love to create a function with a descriptive name, and then create an alias for that function to facilitate using it from the Windows PowerShell console. Now, if a huge storm brews up in the sky, I can shut down my entire network with three key strokes—that is pretty quick. Of course, the function assumes that I will have a $mycomputers variable, but that is defined inside my profile in the same location that the Stop-MyComputers function will reside, so using the variable is a safe bet.

The only trick is to remember to update the mycomputers.txt file when I add a new computer to the network. Another approach is to query AD in your profile and use the results of your query to populate the $mycomputers variable. I might make that change one of these days. If I do, I will probably create three variables: $mycomputers, $myServers, and $myvirtualmachines. I might also create $allcomputers, which would be created by adding the three previous variables.

OK, so I got off on a bit of a tangent. Blame it on Boz Scaggs—I am listening to Boz Scaggs on my (soon to be extinct) Zune HD (I am heartbroken), and I guess I let my train of thought shuffle off to Toledo. Oh well.

I was talking about the use of aliases. Largely I believe that it is a best practice to use aliases when working interactively at the Windows PowerShell console. I feel that when working interactively at the Windows PowerShell console, the goal is to accomplish something specific. This might not always be the case, and at times, I am simply experimenting, playing, or otherwise trying out various commands. In these scenarios, I do not feel too invested in the particular command, and I wish to try out many commands in a short amount of time. Aliases help and support these goals.

When to not use aliases

When might I not want to type a series of aliases at the Windows PowerShell console? I can think of at least three scenarios. The first scenario involves typing a critical command or two. If I am getting ready to type a critical command, I want to be sure I am getting the syntax correct. Therefore, I will use the full cmdlet name, and I will use all of the named parameters. I will not rely on positional parameters.

Another scenario in which I do not use aliases at the Windows PowerShell console involves what I call command prototyping. In this scenario, I am trying to figure out the syntax of a series of commands that I will use in a Windows PowerShell script. I have the Windows PowerShell ISE opened as well as the Windows PowerShell console. I will run my Windows PowerShell commands in the console until they are performing exactly the way I intend, and then I copy the command into my script in the Windows PowerShell ISE. Because I am copying directly from the Windows PowerShell console into my script, I use tab expansion to expand the complete cmdlet name and to avoid using aliases. For me this is less work than replacing the aliases in my script code after the fact.

The third scenario is when I am teaching or making a presentation to customers. One of my pet peeves is Windows PowerShell presentations that are heavy with aliases…especially when the target audience is beginners. I believe it is extremely unfair to expect a novice user to come up to speed immediately with the intricacies of Windows PowerShell code and to learn 138 aliases for 236 cmdlets all at the same time. (I used the following commands to retrieve this information. The alias for Get-Alias is gal, and the alias for Get-Command is gcm.)

PS C:\> gal | measure

 

Count    : 138

Average  :

Sum      :

Maximum  :

Minimum  :

Property :

 

PS C:\> gcm -command cmdlet | measure

 

Count    : 236

Average  :

Sum      :

Maximum  :

Minimum  :

Property :

Why worry about aliases in the first place?

What is the big deal about using aliases anyway? If they make the code easier to type, what is the harm in using them in scripts? There are two things at work when it comes to a script. The first is that no alias is guaranteed to exist—even aliases that are created by Windows PowerShell. There are two classes (or types) of aliases in Windows PowerShell. The first alias type is those that are marked Read-only. The following command displays the Read-only aliases. (The alias for Get-Alias is gal, the ? is an alias for the Where-Object, and ft is an alias for the Format-Table cmdlet. The –a uses partial parameter completion for the autosize switch.)

PS C:\> gal | ? { $_.options -match 'readonly' } | ft name, options -a

 

Name               Options

----               -------

%       ReadOnly, AllScope

?       ReadOnly, AllScope

ac      ReadOnly, AllScope

asnp    ReadOnly, AllScope

clc     ReadOnly, AllScope

clhy    ReadOnly, AllScope

cli     ReadOnly, AllScope

clp     ReadOnly, AllScope

clv     ReadOnly, AllScope

compare ReadOnly, AllScope

cpi     ReadOnly, AllScope

cpp     ReadOnly, AllScope

cvpa    ReadOnly, AllScope

dbp     ReadOnly, AllScope

diff    ReadOnly, AllScope

ebp     ReadOnly, AllScope

epal    ReadOnly, AllScope

epcsv   ReadOnly, AllScope

fc      ReadOnly, AllScope

fl      ReadOnly, AllScope

foreach ReadOnly, AllScope

ft      ReadOnly, AllScope

fw      ReadOnly, AllScope

gal     ReadOnly, AllScope

gbp     ReadOnly, AllScope

gc      ReadOnly, AllScope

gci     ReadOnly, AllScope

gcm     ReadOnly, AllScope

gcs     ReadOnly, AllScope

gdr     ReadOnly, AllScope

ghy     ReadOnly, AllScope

gi      ReadOnly, AllScope

gl      ReadOnly, AllScope

gm      ReadOnly, AllScope

gmo     ReadOnly, AllScope

gp      ReadOnly, AllScope

gps     ReadOnly, AllScope

group   ReadOnly, AllScope

gsnp    ReadOnly, AllScope

gsv     ReadOnly, AllScope

gu      ReadOnly, AllScope

gv      ReadOnly, AllScope

gwmi    ReadOnly, AllScope

iex     ReadOnly, AllScope

ihy     ReadOnly, AllScope

ii      ReadOnly, AllScope

ipal    ReadOnly, AllScope

ipcsv   ReadOnly, AllScope

ipmo    ReadOnly, AllScope

ise     ReadOnly, AllScope

iwmi    ReadOnly, AllScope

measure ReadOnly, AllScope

mi      ReadOnly, AllScope

mp      ReadOnly, AllScope

nal     ReadOnly, AllScope

ndr     ReadOnly, AllScope

ni      ReadOnly, AllScope

nmo     ReadOnly, AllScope

nv      ReadOnly, AllScope

ogv     ReadOnly, AllScope

oh      ReadOnly, AllScope

rbp     ReadOnly, AllScope

rdr     ReadOnly, AllScope

ri      ReadOnly, AllScope

rmo     ReadOnly, AllScope

rni     ReadOnly, AllScope

rnp     ReadOnly, AllScope

rp      ReadOnly, AllScope

rsnp    ReadOnly, AllScope

rv      ReadOnly, AllScope

rvpa    ReadOnly, AllScope

rwmi    ReadOnly, AllScope

sal     ReadOnly, AllScope

saps    ReadOnly, AllScope

sasv    ReadOnly, AllScope

sbp     ReadOnly, AllScope

sc      ReadOnly, AllScope

select  ReadOnly, AllScope

si      ReadOnly, AllScope

sl      ReadOnly, AllScope

sleep   ReadOnly, AllScope

sort    ReadOnly, AllScope

sp      ReadOnly, AllScope

spps    ReadOnly, AllScope

spsv    ReadOnly, AllScope

start   ReadOnly, AllScope

sv      ReadOnly, AllScope

swmi    ReadOnly, AllScope

tee     ReadOnly, AllScope

where   ReadOnly, AllScope

write   ReadOnly, AllScope

Now, compare the results of this list with the output for the following listing of aliases that are not marked Read-only.

PS C:\> gal | ? { $_.options -notmatch 'readonly' } | ft name, options -a

 

Name     Options

----     -------

cat     AllScope

cd      AllScope

chdir   AllScope

clear   AllScope

cls     AllScope

copy    AllScope

cp      AllScope

del     AllScope

dir     AllScope

echo    AllScope

epsn    AllScope

erase   AllScope

etsn    AllScope

exsn    AllScope

gjb     AllScope

gsn     AllScope

h       AllScope

history AllScope

i           None

icm     AllScope

ipsn    AllScope

kill    AllScope

lp      AllScope

ls      AllScope

man     AllScope

md      AllScope

mount   AllScope

move    AllScope

mv      AllScope

nsn     AllScope

popd    AllScope

ps      AllScope

pushd   AllScope

pwd     AllScope

r       AllScope

rcjb    AllScope

rd      AllScope

ren     AllScope

rjb     AllScope

rm      AllScope

rmdir   AllScope

rsn     AllScope

sajb    AllScope

set     AllScope

spjb    AllScope

type    AllScope

wjb     AllScope

The r alias is mine; it is short for Invoke-History. But that is beyond the point. If you look at the results of the previous list, you see things like md, rd, rmdir, and ls, cat, and man. I call these aliases compatibility aliases because they make Windows PowerShell compatible with UNIX or Windows shell environments. Therefore, a Windows administrator probably knows how to use dir to produce a list of files from the file system. It is easier to use the dir command, especially early on, to tell that Windows admin you must learn the gci or Get-ChildItem.

The first set of aliases (the ones marked Read-only) are not compatible with either Windows or UNIX. The commands only have meaning within Windows PowerShell itself. Many times, they are the first initials of stressed syllables. This is seen in gci for Get-ChildItem or ebp for Enable-BreakPoint, gps for Get-ProceSs, or even gsv for Get-SerVice. Nevertheless, this is not always the case. For example, gmo for Get-Module does not seem to follow the pattern.

Therefore, if you do not like gmo for Get-Module, you can remove it. But how does one remove an alias? The logical first step is to use the Get-Command cmdlet to see if there is a cmdlet named Remove-Alias. As shown in the following output, such a command does not exist.

PS C:\> Get-Command -Noun alias

 

CommandType     Name                                      Definition

-----------     ----                                      ----------

Cmdlet          Export-Alias                              Export-Alias [-Path] <String> [[-Name]...

Cmdlet          Get-Alias                                 Get-Alias [[-Name] <String[]>] [-Exclu...

Cmdlet          Import-Alias                              Import-Alias [-Path] <String> [-Scope ...

Cmdlet          New-Alias                                 New-Alias [-Name] <String> [-Value] <S...

Cmdlet          Set-Alias                                 Set-Alias [-Name] <String> [-Value] <S...

Remember the *-item cmdlets? The reason they are all named something about an item is that an item can be anything. It all depends on the provider. In Windows PowerShell, there are many different providers, each of which makes use of the *-item cmdlets. As shown here, on my laptop, there are eight different providers. A quick review of the list will show to even the most casual observer that there is a provider named Alias, and that the Alias provider exposes a drive named Alias.

PS C:\> Get-PSProvider

 

Name                 Capabilities                            Drives

----                 ------------                            ------

WSMan                Credentials                             {WSMan}

Alias                ShouldProcess                           {Alias}

Environment          ShouldProcess                           {Env}

FileSystem           Filter, ShouldProcess                   {C, Bin, D, E}

Function             ShouldProcess                           {Function}

Registry             ShouldProcess, Transactions             {HKLM, HKCU, HKCR}

Variable             ShouldProcess                           {Variable}

Certificate          ShouldProcess                           {cert}

A review of the *-item cmdlets shows that there is a Remove-Item cmdlet. This is shown here.

PS C:\> Get-Command -Noun item

 

CommandType     Name                                      Definition

-----------     ----                                      ----------

Cmdlet          Clear-Item                                Clear-Item [-Path] <String[]> [-Force]...

Cmdlet          Copy-Item                                 Copy-Item [-Path] <String[]> [[-Destin...

Cmdlet          Get-Item                                  Get-Item [-Path] <String[]> [-Filter <...

Cmdlet          Invoke-Item                               Invoke-Item [-Path] <String[]> [-Filte...

Cmdlet          Move-Item                                 Move-Item [-Path] <String[]> [[-Destin...

Cmdlet          New-Item                                  New-Item [-Path] <String[]> [-ItemType...

Cmdlet          Remove-Item                               Remove-Item [-Path] <String[]> [-Filte...

Cmdlet          Rename-Item                               Rename-Item [-Path] <String> [-NewName...

Cmdlet          Set-Item                                  Set-Item [-Path] <String[]> [[-Value] ...

OK, so it should be a simple matter to use the alias drive and remove an alias. Let’s try it.

PS C:\> Get-Alias gmo

 

CommandType     Name                                      Definition

-----------     ----                                      ----------

Alias           gmo                                       Get-Module

 

PS C:\> Remove-Item alias:gmo

Remove-Item : Alias was not removed because alias gmo is constant or read-only.

At line:1 char:12

+ Remove-Item <<<<  alias:gmo

    + CategoryInfo          : WriteError: (gmo:String) [Remove-Item], SessionStateUnauthorizedAcce

   ssException

    + FullyQualifiedErrorId : AliasNotRemovable,Microsoft.PowerShell.Commands.RemoveItemCommand

Well, that did not work. It says the alias might be constant or Read-only. It does not specify a remedy (interestingly enough). But I know from working with the variable drive that I can remove a Read-only variable by using the –Force switch. Let’s try it here.

PS C:\> Remove-Item alias:gmo –Force

The command did not generate an error; however, I am not convinced that it actually worked because nothing was returned. The way to check it is to use the Get-Alias cmdlet to retrieve it. I do this, and an error is generated that states the alias gmo does not exist. This is shown here.

PS C:\> Get-Alias gmo

Get-Alias : This command cannot find a matching alias because alias with name 'gmo' do not exist.

At line:1 char:10

+ Get-Alias <<<<  gmo

    + CategoryInfo          : ObjectNotFound: (gmo:String) [Get-Alias], ItemNotFoundException

    + FullyQualifiedErrorId : ItemNotFoundException,Microsoft.PowerShell.Commands.GetAliasCommand

What if I later suffer from “deletion regret?” Am I stuck? Do I have to reinstall Windows 7 just to get that silly alias back?

The answer, of course, is, “No, I do not have to reinstall Windows 7 to get the gmo alias back.” All I have to do is to close Windows PowerShell, and then open it. When I do that, I use the Get-Alias cmdlet again to see if it is there. As shown here, it is.

PS C:\> Get-Alias gmo

 

CommandType     Name                                      Definition

-----------     ----                                      ----------

Alias           gmo                                       Get-Module

Now, if the alias returns every time I start Windows PowerShell, then what is the harm? Maybe I really hate the gmo alias, and I never want to look at it again. All I need to do is to add my previous command to my Windows PowerShell profile, and the alias will never again appear, unless I choose to use it for something.

The real danger of using an alias in a script

This then, is the danger of using aliases in a script. I will give a quick story, and end this. I was teaching a Windows PowerShell class in Copenhagen, Denmark a few years ago, and one of my students spent all of his free time (and long into the night) working on his profile. He spent hours and hours making his Windows PowerShell environment look like a command environment he had on a different system. He created various variables, customized his prompt, changed the background color, modified the Windows PowerShell window title and everything else he could think of to do. One of the things he did was remove the alias ls (a compatibility alias for Get-ChildItem). After he did that, he redefined the alias to Set-Location.

The interesting thing is that both commands accept a string as the default argument…and that string is a path. This means that a script that uses ls to get a directory listing would instead change the working location of the script to that directory. Depending on what the following commands were, the results could be disastrous, and no error would be generated because the signatures are the same.

For my student, this decision made sense—after all, aliases are a convenience factor, and because he never intended to use ls for Get-ChildItem, there is no harm. The big problem, of course, would be if he ran a script from someone else who used that alias for Get-ChildItem.

You might not always control where and how a script will be run. You cannot be guaranteed that an alias will exist in an environment. And if that alias does exist, you cannot be guaranteed that it means the same thing everywhere. Of, course, you can always check to see if an alias exists, and if it means what you expect it to mean. An example of this is shown here.

if ((Get-Alias ls).definition -match 'Get-Childitem') { ls }

But using code such as this really defeats the purpose of using an alias. In the end, it is a best practice to avoid using aliases in enterprise production-level scripts. The same is true when it comes to using positional arguments or partial parameter names.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Hello Ed,

    This is a wonderful alias article!

    A word of wisdom to all of us! :-)

    I used aliases since the doskey command has been introduced in MS DOS (Vx.y?)and I really liked the

    short an precise UNIX like commands. They come in handy if you are used to them!

    But spreading the batch files to be used by others complicated everything.

    You have to import the alias definitions from files that have to be accessible by each user.

    And .. you know what ... nobody understood the beautines of my aliases! If errors popped up

    and co-workers had to have a look at my batches they always had to make sure to understand what my

    wonderful aliases were supposed to do! That lead to some discussions and in the end I cleared the code

    and eliminated all aliases for the sake of transparancy and to have a common knowledge basis.

    The same problem will likely appear in unix and powershell systems.

    Undefined or even redfined aliases in local profiles will definitely be a problem.

    The readablity of aliases is another point to mention. But I think that most people who are

    comfortable with PS will be fine with the commom aliases like %, ?, dir, where, select etc.

    These won't put additional burdons on other PS users, at least not regarding the readability.

    In general we should follow your advice: We may use aliases on the command line but we should avoid them im scripts!

    kind regards, Klaus

  • Thanks a lot for this article !

    Excellent demonstration :)

    "CQFD !" as we could say in french, which is not an Alias of "Comme Quoi il Fallait Dormir" (Something like "You should have slept", in english) but "Ce Qu'il Fallait Démontrer" : Quod Erat Demonstrandum (QED).

    A thought for the victims of storms that hit south of the United States, these last days...

  • Bon soir Mr. Betton,

    cest vrai! you are absolutely right!

    We all should bow our heads to the victims of the storm!

    I'm desperately sorry that the US were hit again by a natural disaster!!!

    Klaus

  • A number of people in the Hey, Scripting Guy! forum could do by reading this article. There is nothing worse than needing help with a script and the people just reply with a bunch of aliases that make no sense. Then the beginner spends more time decoding the aliases then getting an answer to the inital question.

  • hi first of all sorry for commenting here. I thought Scripting Guy would read it faster. the thing is you had a blog post earlier at here: http://blogs.technet.com/b/heyscriptingguy/archive/2011/03/11/use-powershell-to-find-writable-wmi-properties.aspx and I need the program shown in the first two screenshots. the program would be a life saver to me and it's really urgent so please contact me as soon as you can. Email: mohsentux@live.com