Powershell Function Introduction

Adam Bertram

Read more posts by this author.

In this blog post, learn how to get started building and using your own PowerShell function.

PowerShell, like any good development/scripting language, has functions. Functions are ubiquitous in the software development world. At their most basic, functions are groupings of code that when executed as a single entity behave like one.

A function is typically created when the code author has a specific activity that needs to get done and usually more than once. By writing a function instead of the lines of PowerShell code on their own, it keeps the script cleaner and allows easy reuse of the code.

Here’s an example of a very basic function and how to use it:

function HelloWorld {
    Write-Host 'Hello world!'

PS> HelloWorld

In this example, this script would simply output Hello World! to the console. This is because the function was created/declared by the function keyword and the code in brackets.

We then we executed/called the function by name using HelloWorld.

PowerShell, unlike other languages, makes you create your functions at the top of the script and call them below. I found this out the hard way. Keep that in mind.

In this example, PowerShell saw the function line but did nothing. It then saw the HelloWorld line and went back up and ran the code inside the function thus writing out Hello World!.

If you’re coming from other languages, notice no parentheses in function declaration and when calling the function. You’ll see it gets even more odd-looking when we touch on parameters.

Functions can have parameters that can be fed into them. A parameter is a variable that can modify the function’s behavior.

For example, if you’ve got a function that creates a file and write some text to it you’d probably want to tell the function where the file is located and what exactly to write to it. These two specifications would be called parameters in a WriteToFile function.

Let’s take a look at two ways to send parameters to your PowerShell functions.

Function WriteToFileMethodOne($FilePath,$LineToWrite = 'Write this to the text file') {
    if (Test-Path $FilePath) {
        Add-Content -Path $FilePath -Value $LineToWrite
    } else {
        return "The file $FilePath does not exist"

Function WriteToFileMethodTwo {
    if (Test-Path $args[0]) {
        Add-Content -Path $args[0] -Value $args[1]
    } else {
        return "The file $($args[0]) does not exist"

WriteToFileMethodOne 'C:\textfile.txt'
WriteToFileMethodTwo 'C:\textfile.txt' 'Write this to the text file'

In the code above, I’ve created two functions that first check to see if a file specified (parameter 1) exists. If it does, it appends a line of text we specified as the second parameter. They just work a little differently.

Our first example is a typical function with parameters but includes a default parameter. A default parameter just says “this is the value of the parameter if there’s none specified”.

In this instance, we’re going to use the text snippet Write this to the text file if nothing is specified and as you can see when calling WriteToFileMethodOne we don’t.

The second function example is very PowerShell-esque and truthfully not one I use regularly. I believe in code that looks like it acts. I understand this way and I see why PowerShell allows it (ala passing parameters to jobs) but it just looks odd.

Under the covers, PowerShell keeps an $args array variable. It captures all arguments passed to functions (and more).

By using this method, we’re saving some keystrokes by not explicitly stating what parameters we’re expecting. $args[0] would be the first parameter that’s passed to WriteToFileMethodTwo while $args[1] would be the second parameter that’s passed to the function which would be the text snippet Write this to the text file.

Finally, let’s discuss the return construct. The return you see in both functions simply says return this to wherever the function was called in the first place and stop the function.

When the function sees a return and something after it, it immediately stops processing any other code in the function and hands processing back to the line of code that called it in the first place.

In this instance, if the file path wasn’t found, it returned a string saying the file doesn’t exist.

Subscribe to Adam the Automator

Get the latest posts delivered right to your inbox

Looks like you're offline!