Beginner’s guide to PowerShell part 2 - Functions

November 18, 2016

Functions

If you find that you are running a certain script all the time then the best thing to do is to create it as a function. But there are also other benefits to using functions. When you create a function, the name you have for the function is now a command inside your PowerShell session.

Now I prefer using PowerShell ISE when creating script because of its ease of use.

When you open PowerShell ISE the top part is the script pane and this is where you can input multiple lines of PowerShell and save them as *.ps1 files. You can create just regular code here or you can create functions.

Here is an example of a function that opens up a text file using notepad and the location of the text file is located in C:\Test folder.

    function Notes {
        notepad "C:\Test\notes.txt"
    }

When you click the play button on the top your function executes inside the code window. Once its ran then it’s loaded in PowerShell for use again with just using the name of the function which is Notes. Enlarge image

Now type Notes into the command window and then Notepad opens up with your document. Enlarge image

Functions with parameters

The next thing to learn is functions with parameters and here is an example of one below.

    function Sum {
        param(
            [int]$firstNumber,
            [int]$secondNumber
        )

        $firstNumber + $secondNumber

    }

    Sum -firstNumber 1 -secondNumber 2
    3

    Sum 1 2
    3

The syntax of a function is important to learn to do correctly. When declaring parameters it is crucial that you put the $ dollar sign in front of every parameter. Also you can optionally declare the type of variable and in this case I have declared both the parameters as integers.

Here is the exact same function but without declaring the type for the parameters and it achieves the same result.

    function SumWO {
        param(
            $first,
            $second
        )

        $first + $second
    }

    SumWO -firstNumber 1 -secondNumber 2
    3

    SumWO 1 2
    3

The other part is you can use Tab Completion in PowerShell.

When I type sum(lowercase) I hit Tab right after and it finds my function and changes it to Sum. After that I hit spacebar then a dash. I hit Tab again and PowerShell shows me the first parameter. Then I hit spacebar again and type in the number 1. I type another dash then Tab and it gives me the second parameter, I hit spacebar again and then type 2. After all that I hit Enter and the function executes with the parameters and returns a 3 on the next line. I then type cls to clear the screen. The command cls is an alias for Clear-Host command in PowerShell.

Functions with default parameters

Functions also have a way to set parameters with default values. So say you want to create the same function we have been using but want to set both the firstNumber and secondNumber with a default value. So if you just run Sum in powershell it won’t require you to put in a variable.

Currently if you run the function with no parameters then the value automatically comes back as 0.

    function Sum {
        param(
            $first,
            $second
        )

        $first + $second
    }

    Sum
    0

But if we specify default values for each parameter, in this case 2 for each value. When you run the sum command now it will be equal to 4.

    function Sum {
        param(
            $first=2,
            $second=2
        )

        $first + $second
    }

    Sum
    4

Functions with Required parameters

Also to help you starting with Windows PowerShell 2.0 and above, there is a parameter attribute you can use to require a parameter.

[Parameter(Mandatory=$true)]

When you use this above your declared parameter then the function requires you to input a parameter.

In this example we have set both parameters to be mandatory.

function Sum {
param(
    [Parameter(Mandatory=$true)]
    [int]$firstNumber,
    [Parameter(Mandatory=$true)]
    [int]$secondNumber
)

$firstNumber + $secondNumber

}

When we use the function now PowerShell will not let us use the function without inputting a value for each parameter.

PS:> Sum
cmdlet Sum at command pipeline position 1
Supply values for the following parameters:
firstNumber: 

Then for the second number.

PS:> Sum
cmdlet Sum at command pipeline position 1
Supply values for the following parameters:
firstNumber: 1
secondNumber: 1

And finally.

PS:> Sum
cmdlet Sum at command pipeline position 1
Supply values for the following parameters:
firstNumber: 1
secondNumber: 2
3

PS:> 

This is just a high level view of functions and we will get into PowerShell profile next.

PowerShell links

PowerShell references