How To Make Use Of Functions in PowerShell
Over the last few weeks I’ve had a number of comments on posts essentially asking the same question: “How do I use the functions that you publish on your blog?”. So I thought it worth making a post to refer people to, rather than trying to respond in kind to each comment. There are a number of ways it can be done depending on your requirements and they are listed below.
First of all, let’s create a simple function to use for testing:
function Get-TimesResult {
Param (\[int\]$a,\[int\]$b)
$c = $a \* $b
Write-Output $c }
1) Paste Into Existing PowerShell Session
If you are working interactively in the console then the function can be copy / pasted into that session and is then available for the duration of that session. I find this easier to do via the PowerShell ISE than the standard console.
Copy the function into the script pane:
Click the Green Run Script button or hit F5 and the code will appear in the console pane:
The function is now available for use and if using the ISE will appear interactively when you start typing the name:
2) PowerShell Profile
If the function is something that you wish to use regularly in your interactive PowerShell sessions then you can place the function in your PowerShell Profile and it will be available every time you open your PowerShell console.
If you are unsure what a PowerShell profile is or how to use one, there is some good info here. A quick way to create one is:
New-Item -Path $profile -ItemType File -Force
Once you have created a PowerShell profile, place the function in the profile and save and close. Now every time you open your PowerShell console the function will be available.
3) Directly In A Script
If you wish to use the function in a script, place the function in the script above the sections where you need to use it. Typically this will be towards the top. The plus side of doing it this way is everything is contained in one file, a negative is that if you have a number of functions then readability of the script is reduced since there may be a long way to scroll down before anything of significance starts to happen.
4) Called From Another Script
One method I have seen quite often in the wild (and I’m not a particular fan of, point 5 is a much better approach) is to store all regularly used functions in a script file and dot source the functions script file in the script where you need to use one or more of the functions.
Functions script file Tools.ps1:
Get-Results script file calling Tools.ps1:
Note the dot and a space before the reference to the Tools.ps1 file
. C:\\Users\\jmedd\\Documents\\WindowsPowerShell\\Scratch\\Tools.ps1
Get-TimesResult -a 6 -b 8
5) Stored in a Module
Using a PowerShell module is a more advanced and significantly more structured and powerful method of achieving what was done in 4). If you haven’t used PowerShell modules before I wrote an introduction to PowerShell modules a while back which you can find here.
Essentially they are a method to package up your reusable functions and make them available in a manner similar to how other teams in Microsoft and third-parties produce suites of PowerShell cmdlets for consumption.
For this example I have created a Tools module to use, which essentially is the same content as the Tools.ps1 file, but stored in a *.psm1 file (Tools.psm1) in the Modules\Tools folder on my workstation.
Note: the name of the *.psm1 file should match that of the folder. Its possible to create a more enhanced module than taking this approach using a Module Manifest, but we don’t need that for the purposes of this post. It’s described further in the previously mentioned article.
Now we can use the *-Module PowerShell cmdlets to work with our content.
To observe the module we can use Get-Module:
Get-Module Tools -ListAvailable
To use the functions contained in the module we can use Import-Module
Import-Module Tools
Get-TimesResult -a 6 -b 8
Note: Since PowerShell v3 automatic cmdlet discovery and module loading has been supported. (You can find out more about it here) Consequently, you don’t actually need to use Import-Module to get access to the functions as long as you place the Module in the correct location. However, it would be a good practice to add the Import-Module line to your script, so that another user is aware of where you are getting the functionality from.