April 10th, 2013

Accepting Arguments for PowerShell Functions: Best Practices

Doctor Scripto
Scripter

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.

function myfunction

{

 “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:

myfunction $env:COMPUTERNAME

The image that follows illustrates creating the function, using $args in the script block, and calling the function from the execution pane.

Image of command

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.

function afunction

{

 “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.

Image of command output

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 scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy 

Author

The "Scripting Guys" is a historical title passed from scripter to scripter. The current revision has morphed into our good friend Doctor Scripto who has been with us since the very beginning.

0 comments

Discussion are closed.