Creating Windows PowerShell Functions
Regular PowerShell command(s) + named parameters = Function.
I see a Parameter in PowerShell as similar to a -in a DOS command. In both cases the user gets extra options for the basic command.
Topics for PowerShell Parameters
- Benefits of Microsoft PowerShell Parameters
- Key Concepts for PowerShell Functions
- Example of a PowerShell Functions
- More Information on PowerShell Parameters
♣
Benefits of Microsoft PowerShell Parameters
The main benefit of creating a function is that you can reuse the code, and this is what drives us to create functions rather than keeping on re-inventing the wheel.
PowerShell functions work like cmdlets, but without having to program in C#. To use the FUNCTION you just type its name [and press enter] just as you would execute a normal verb-noun cmdlet.
At the heart of a PowerShell function is a list of ordinary statements. In most cases you can also type a -switch parameter to filter the output.
Technically speaking, functions return values that can be displayed, assigned to variables, or passed to cmdlets.
Key Concepts for PowerShell Functions
To see the place of parameters, let us review all the elements of a PowerShell function.
Keywords in PowerShell Functions:
- Function (Itself!)
- Global (Optional scope)
- Param ($Parameters define the -switches)
- Begin (Optional one-off commands, e.g. Clear-Host)
- Process (The business, PowerShell commands)
- End (I often place the date here)
The Function Name:
There is a rhythm to creating a PowerShell function; let us start with name, for example Get-JobDone
Function Global:Get-JobDone {script coding instructions}
It's easy to overlook that 'Function' itself is a keyword, you could not call it FunctionS or Function1.
Brackets in Functions:
It's always worth studying PowerShell's use of brackets (param parenthesis) [Type square] {commands braces}
Observe in the 'Process' section the instructions are enclosed in curly brackets {called braces}.
Param Section
The Param sections hold definitions of the -Switches, for example [String], [Switch], [PSObject]. There is quite a long list of optional keywords that can refine your parameters. From a learning point-of-view these modifiers such as 'Position', 'ValueFromPipeline' and 'Alias' are optional, and you can learn them as and when you need them.
A second parenthesis style bracket brings the parameter definition section to an end.)
Process {Script Engine}
It surprised me that 'Process' is another keyword; at first I naively thought that someone had left off the Get from 'Get-Process'. I was completely wrong! Plain 'Process' introduces the work-horse section of the function. Here are all the commands that you would employ if you had a scripting job and couldn't be bothered to make a function.
Begin and End
These are two optional sections designed for one-off commands, the Begin and End sections need not cause worry to the novice scripter.
<#.SYNOPSIS
Although this section is often placed at the top of the script, it's the last part of the function that I tackle. To see the results of adding comments I type: Get-Help Get-JobDone (or other function name), then I can see the synopsis, the description and any examples that I wrote in my script.
PowerShell realises it's the end of the help and comments section by the closing syntax:
#>
Guy Recommends: A Free Trial of the Network Performance Monitor (NPM)
v11.5
SolarWinds’ Network Performance Monitor will help you discover what’s happening on your network. This utility will also guide you through troubleshooting; the dashboard will indicate whether the root cause is a broken link, faulty equipment or resource overload.
What I like best is the way NPM suggests solutions to network problems. Its also has the ability to monitor the health of individual VMware virtual machines. If you are interested in troubleshooting, and creating network maps, then I recommend that you try NPM now.
Download a free trial of Solarwinds’ Network Performance Monitor
More Examples of PowerShell Functions
Detailed Example: Get-IPConfig
The purpose of this function is to illustrate how PowerShell can run native commands such as IPConfig.
Furthermore you can enhance the original IPConfig command with filters such as -MAC (Physical address: 20-CF-30-3A-B4-72), or IPv, which display just the dotty dot numbers, for example: 192.168.1.40.
PowerShell Function Example: Get-IPConfig
Function Global:Get-IPConfig {
<#
.SYNOPSIS
PowerShell function to encase Microsoft's IPConfig
.DESCRIPTION
Includes parameters to filter MAC and IPv4 and IPv6 addresses
.EXAMPLE
Get-IPConfig -MAC
#>
[cmdletbinding()]
Param (
[Switch]$IP,
[Switch]$Mac,
[Switch]$All
)
Begin {
Clear-Host
}
Process {
If($Mac) {
IPConfig -all | Select-String "Physical"
} # End of 'If'
ElseIf($IP) {
IPConfig -all | Select-String "IPv"
}
ElseIf($All) {
IPConfig -all
}
Else {
IPConfig
} # End of 'Else'
} # End of Process
End {
"`n " + (Get-Date).DateTime
}
}
PowerShell Learning Points
[Switch] Parameter. Think of this as creating a switch which you can append to the command, for example:
IPConfig -MAC
From a scripting point of view, [Switch]$MAC enables you to oscillate from running the basic command, with modifying the code as laid out in the IF($MAC) {Swap this code} construction. Incidentally, this is why people sometimes refer to parameters as switches.
In addition to the 'Function' structure, PowerShell brings Select-String to this project and thus enhances the underlying IPConfig command.
Guy Recommends: SolarWinds Free Wake-On-LAN Utility
Encouraging computers to sleep when they’re not in use is a great idea – until you are away from your desk and need a file on that remote sleeping machine!
WOL also has business uses for example, rousing machines so that they can have update patches applied. My real reason for recommending you download this free tool is because it’s so much fun sending those ‘Magic Packets’. Give WOL a try – it’s free.
Download your free copy of SolarWinds Wake-On-LAN
Types of PowerShell Function Parameters
The problem is there are at least four types of parameters (Script, Switch PSObject and Int32), thus assigning an inappropriate definition could have an undesirable effect on your function.
The parameters also can be named, positional, switch, or dynamic parameters. A function's parameters can be read from the command line or from the pipeline. Some parameters accept wildcards; you can read their detailed descriptions with Get-Help Cmdlet (or Function) -full.
For More Information on Creating PowerShell Parameters See:
- about_Parameters
- about_Functions_Advanced_Parameters
- about_Parameters_Default_Values
- about_Automatic_Variables
- about_Comment_Based_Help
Summary of Function's Parameters
A function is a regular PowerShell command with added parameters. The capabilities of these parameters is defined in the function's Process section.
PowerShell's parameters remind me of a -switch in a DOS command.
If you like this page then please share it with your friends
See More PowerShell Function Parameters
• Scripting PowerShell Function • PowerShell Function Clear-Recyclebin • PowerShell Get-File
• Create PowerShell Function Get-ServiceStatus • PowerShell Function Get-Driver • PowerShell Outlook
• Show-BalloonTip • PowerShell Function Get-IPConfig • Free Permissions Analyzer
Please email me if you have a better example script. Also please report any factual mistakes, grammatical errors or broken links, I will be happy to correct the fault.
