Named Arguments for PowerShell Functions: Best Practices

Summary: Microsoft Scripting Guy, Ed Wilson, talks about using named arguments in Windows PowerShell functions.

Microsoft Scripting Guy, Ed Wilson, is here. If I go to the trouble of writing a Windows PowerShell script, I generally do not use unnamed arguments (such as $args as I illustrated yesterday in Accepting Arguments for PowerShell Functions: Best Practices). Instead I create named arguments for my functions. It is just so much more powerful, and so much more flexible. Besides, I can still pass values appositionally in an unnamed fashion if I wish to do so.

Create a named argument in five easy steps

In yesterday's blog, I said that there are only three requirements to create a function in Windows PowerShell:

1. The Function keyword
2. The name of the function
3. A script block

To create a named argument in a Windows PowerShell function, I need only two  additional things:

1. The Param keyword
2. A variable to hold the argument inside a pair of parentheses

The following script illustrates this technique:

Function myfunction

{

 Param($myargument)

 "This value of `$myargument is $myargument"

}

To use MyFunction, I first have to run the script. This loads the function into memory and makes it available via the function PSDrive. Because I have not saved the script containing the function, when I run the script, it appears in the Console pane below the Script pane. When the script runs, the Windows PowerShell prompt returns, and I can call the function by typing the name of the function. I then supply a value for the argument by typing it. This is shown in the image that follows.

Keep in mind that tab expansion works here. So I do not have to type the entire name of MyFunction, nor do I need to type the complete name of MyArgument. In fact, I only had to type my and press the Tab key to get the MyFunctioncommand onto the command line. When I type the hyphen (–) for the named argument (parameter) a pop-up list appears, as shown in the following image.

The advantage of using named arguments (parameters) is that I do not need to name the parameter if I do not want to. I can use it as a positional parameter. In this manner, it behaves like an unnamed argument ($args). This is shown here.

PS C:\> myfunction "this is a  string"

This value of $myargument is this is a  string

Because creating named parameters in Windows PowerShell is so easy, and because using the Paramkeyword is the entry into the world of advanced functions, I never use $args in a Windows PowerShell script. Because it is an automatic variable that becomes available in certain circumstances, using $args is more difficult to understand because nothing has been created in the script. It is just there.

On the other hand, because the Paramblock is declared and available for inspection, it makes sense, and is easier to understand. If I begin with a script that uses $args and I later decide that I need to add functionality, I will have to add a Paramblock to get access to advanced features.

Join me tomorrow when I will welcome guest bloggers Yuri Diogenes and Tom Shinder back with the second installment in their security series. If you want to refresh your memory, check out their first installment in the series:

Security Series: Using PowerShell to Protect Your Private Cloud Infrastructure

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