tags:
Contents
What are PowerShell Functions
PowerShell functions are similar to scripts, but can be loaded into a PowerShell profile or manually when needed. Once loaded, the function can be run by merely typing the name. This differs from a ps1 script where you must specify the file path when executing.
More detailed information about PowerShell functions can be found on Microsoft’s site.
Loading Functions From Files
Let’s say we have a really useful function that we’d like to save and load again in the future. We can save that function into a ps1 file and load it into our current scope by dot sourcing the file.
Normally when you run a PowerShell script it get’s run in a new scope. This means that functions and variables inside the script will not be accessible outside the script.
When a script is Dot-Sourced in the current scope, any functions, aliases, and variables that the script creates become available in the current scope. - ss64.com
Since we want to save and reuse our function regularly we want to add it to the current scope by dot sourcing it.
PS C:\Users\larntz\Documents\Scripts\functions> ls
Directory: C:\Users\larntz\Documents\Scripts\functions
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 4/3/2019 10:46 AM 160 Test-VIServerConnection-Function.ps1
PS C:\Users\larntz\Documents\Scripts\functions> . .\Test-VIServerConnection-Function.ps1
In the example above I dot sourced the file Test-ViServerConnection-Function.ps1 by simply enter a period followed by a space and the file name containing my function.
Loading Functions Automatically
Now let’s get to the handy dandy part and load our functions every time we open PowerShell. Before we do this we need to identify which profile we want to load our functions from. There are six total PowerShell profiles, but only four that matter.
Listing Profile Locations
PowerShell profiles are available in the $profile automatic variable. You can list all locations using the code below. But, I recommend always using the CurrentUserCurrentHost profile unless you have a good reason to use a different one.
foreach ($profileLocation in ($PROFILE | Get-Member -MemberType NoteProperty).Name)
{
Write-Host "$($profileLocation): $($PROFILE.$profileLocation)"
}
| PowerShell Version | Path |
|---|---|
| PowerShell >= 6 | $Home\Documents\PowerShell\Profile.ps1 |
| PowerShell <= 5.1 | $Home\Documents\WindowsPowerShell\Profile.ps1 |
Organizing and Loading Functions
I put each of my functions in a single file and store those files within a single directory. I use a naming convention for each file that ends with -Function.ps1. Using this convention I can edit my PowerShell profile once to load all functions in that directory. The obvious downside to this, is that anyone with access to your PowerShell function directory could drop code in there to be run each time you open PowerShell.
Inside my $Home\Documents\PowerShell\Profile.ps1 I added this line to dot source all my function files.
Get-ChildItem C:\Users\larntz\Documents\Scripts\functions\*Function.ps1 | %{. $_ }
Conclusion
This is a nifty way to add PowerShell functions to your environment. When creating a new function you drop it into your functions directory and, voilà, it’s loaded each time you open PowerShell.
This is best used for functions that don’t fit tightly into a group. If you end up with a collection of functions that could be logically grouped together using PowerShell modules is a better idea.
Modules have two advantages over mere functions. First, they aren’t loaded until they are needed. Second, they are easier to distribute.