Create Your Own PowerShell Functions

Like any scripting language, Windows PowerShell lets you create functions that you can reference within PowerShell statements. A function is basically a named block of code. When you call the function name, the script block within that function runs. You can include any PowerShell statements within the script block, and you can add input parameters so you can use the same function in different situations. Let's look at how to create functions, define input parameters, and work with functions in PowerShell scripts.

Creating a Function

At the most basic level, a function definition (i.e., the code that defines the function) requires the function keyword, the function's name, and a script block, as the following syntax shows:

function <name> { <script block> }

The script block, which needs to be enclosed in braces, contains the statements that run when you call the function. You can include any PowerShell statement that you can run directly in the console. For example, the following code defines a function named FileSize1:

function FileSize1
{
  dir C:\Windows |
  where {$_.length -gt 100000}
}

Note that when you enter multiple lines of code at the command prompt, you should input a line and press Enter. You'll then see a >> prompt, which indicates that additional input is expected. After you've entered the entire function, press Enter twice to return to the normal command prompt (>).

As you can see, this function definition begins with the function keyword, followed by the function's name. The script block includes two commands in a single pipeline. The first command uses the Get-ChildItem cmdlet (represented by the dir alias) to retrieve the contents of the C:\Windows directory. The results are piped to the second command, which uses the Where-Object cmdlet (represented by the where alias) to filter out files so that only files larger than 100,000 bytes are included in the results.

When you create a function, PowerShell stores it in memory for the duration of your session. During that session, you can call the function at any time by simply entering the function's name, as in

FileSize1

When you press Enter, PowerShell runs the code in the script block and returns the results, as shown in Figure 1. These are the same results you would receive if you had run the script block commands directly in the PowerShell console.

As this example shows, creating a basic function is a straightforward process. Although the script block here contains only a simple set of commands, you can make the script block as complex as necessary, letting you easily repeat complex logic without re-entering the same commands over and over. However, in most cases, a function without input parameters limits how much you can do with that function, so let's take a look at how to use input parameters.

Adding Input Parameters

One way you can use input parameters in a function is to take advantage of the $args built-in variable. When you call a function in PowerShell, you can include parameter values with the function's name. If those values aren't associated with a named parameter, they're automatically saved to the $args array. You can then retrieve values from that array within your function.

For example, the following function uses $args:

function FileSize2
{
  dir $args\[0] |
  where {$_.Length -gt 100000}
}

Notice that the first command in the script block references the first value in the $args array ($args\[0]) rather than specifying a pathname (e.g., C:\Windows). As a result, when you call the FileSize2 function, PowerShell uses the first argument that you provide to identify the folder. If you provide more than one argument, PowerShell disregards the extra arguments because the function doesn't reference them.

To call the FileSize2 function, you simply enter the function name and pathname, making sure there's a space between them, such as

FileSize2 C:\Windows

When PowerShell receives this command, it calls the function, replaces $args\[0] with C:\Windows, and returns the applicable contents from that folder, providing the same results as those shown in Figure 1. Note that if a pathname includes spaces, you should enclose it in quotes.

Figure 1: Creating and running a function