PowerShell Function Parameters

Creating Windows PowerShell Functions

Regular PowerShell command(s) + named parameters = Function.PowerShell Function Parameters

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

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)Review of Orion NPM v11.5 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.

See more on Get-IPConfig »

Guy Recommends: SolarWinds Free Wake-On-LAN UtilitySolarwinds Wake-On-LAN

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.