Accepting Arguments for PowerShell Functions: Best Practices
Summary: Microsoft Scripting Guy, Ed Wilson, talks about the best practices surrounding accepting input for a Windows PowerShell function.
Microsoft Scripting Guy, Ed Wilson, is here. April in the Carolina’s is a special time. In fact, it is my favorite time of the year here. This is because the weather is invariably mild. This week, it has been sunny, moderate temperature, mild humidity, and clear skies. The Scripting Neighbors tell me it is perfect golf weather. It is also perfect “sit on the lanai and write Windows PowerShell scripts” weather. Although I have never had much luck with putting a small ball into an even smaller hole with equipment not designed for that purpose, I can compute the trajectory, and force necessary to accomplish the task with a one-line Windows PowerShell command.
Passing a value to a Windows PowerShell function
If I have a function that I need to pass a value to, I can use the automatic variable $args. This makes the function easy to write and easy to use. The following function uses three steps to create the function. It calls the function keyword, provides a name, and creates a script block that contains code.
“the computer name is $args”
In the Windows PowerShell ISE, I run the script (I do not have to save the code into a .ps1 file), and the function loads into memory. I can then call the function directly in the execution pane (the dark blue box that follows) and pass a value to the function when I call it. The command line is shown here:
The image that follows illustrates creating the function, using $args in the script block, and calling the function from the execution pane.
Anything I add following the name of the function populates the $args variable. In the command that follows, I pass the value mred to the function. Interestingly, I do not have to supply quotation marks when passing the value.
PS C:\> myfunction mred
the computer name is mred
PS C:\> myfunction “mred”
the computer name is mred
I can also use the output from the Get-WmiObject cmdlet for input. Therefore, the following code uses WMI to return the computer name and to pass it to the MyFunction function.
PS C:\> myfunction (gwmi win32_computersystem).name
the computer name is EDLT
One thing to keep in mind, is that when I use the $args automatic variable as illustrated in the MyFunction function, I cannot pipe input to the function. This can actually be a bit of a problem, because it could be really hard to troubleshoot due to the fact that no error arises. This is shown here.
PS C:\> $env:COMPUTERNAME | myfunction
the computer name is
If I want to pipel input to my function, I use the $input automatic variable. The only change that is required to my function is to change $args to $input, as shown here.
“the computer name is $input”
I then pipe the input to the function by using the command shown here.
PS C:\> $env:COMPUTERNAME | afunction
If I attempt to provide positional input to the function instead of piping the input, no error arises, but no value passes either.
The command and associated output are shown in the image here.
Best Practices Week will continue tomorrow when I will talk some more about Windows PowerShell functions.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at email@example.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy