Functions are used in most programming and scripting languages. A function
is a named block of code that can be referred to from within Windows
PowerShell. When a function’s name is called, the list of statements
contained in the function is executed.
A function may accept input in the form of
arguments, the values of which can then be used by the code inside the
function. The output from a function can be stored in a variable,
passed to another function, passed to a cmdlet, or written to one of
the output streams.
A function is declared with the keyword function, and the associated code is placed within a script block. Here is an example of a basic function:
PS > function Hello {
>> "Hello $env:username"
>> }
>>
PS > Hello
Hello nigo
When we call the function Hello, the block of code contained in the function is executed, and the output is returned to the session.
A function also accepts arguments, as this example shows:
PS > function foo { $args }
PS > foo 1 2 3
1
2
3
This function uses the automatic variable $args
to return the arguments passed to the function. When we call the
function and pass the arguments 1, 2, and 3, they are returned to the
session.
Like cmdlets, functions can have parameters. One way
to define a parameter is to place a variable within parentheses after
the function’s name. Here is an example of a function with two named
parameters:
PS > function username ($firstname, $lastname) {
>> "FirstName: $firstname"
>> "LastName: $lastname"
>> }
>>
The two named parameters to the function are $firstname and $lastname.
When we call the function, each argument passed to the function will be
bound to the corresponding parameter. If we simply type two arguments
after we call the function, the arguments will bind to the
corresponding parameter based on the argument’s position.
PS > username Niklas Goude
FirstName: Niklas
LastName: Goude
You can also bind the arguments to a named parameter by typing the parameter’s name before the argument:
PS > username -firstname Niklas -lastname Goude
FirstName: Niklas
LastName: Goude
This way, you do not need to enter the arguments in positional order. For example, you can input the last parameter first:
PS > username -lastname Goude -firstname Niklas
FirstName: Niklas
LastName: Goude
By adding a type to a named parameter, you can control the type of argument that the function accepts. Here is an example:
PS > function addition ([int]$val1, [int]$val2) { $val1 + $val2 }
PS > addition 2 3
5
If we try to input a string value to this function, it returns an error.
PS > addition 2 "three"
addition : Cannot process argument transformation on parameter 'val2'.
Cannot convert value "three" to type "System.Int
32". Error: "Input string was not in a correct format."
At line:1 char:9
+ addition <<<< 2 "three"
+ CategoryInfo : InvalidData: (:) [addition], ParameterBindin...
mationException
+ FullyQualifiedErrorId : ParameterArgumentTransformationError,addition
You can also create switch parameters that can
either evaluate to True or False. Switch parameters do not require any
input; you can simply type the function’s name followed by the name of
the switch parameter. Here is an example:
PS > function TV([switch]$on) {
>> if($on) { "The television is on" }
>> else { "The television is off" }
>> }
PS > TV
The television is off
PS > TV -on
The television is on
When we call the function TV without entering the switch parameter’s name, the variable $on is set to False, and The television is off is returned. If we do type the switch parameter’s name, the variable $on is set to True, and The television is on is returned.
You can add other types of named parameters to a function as well. In the next example, we create a named parameter of the type System.uri to check if a URL is valid.
PS > function Check-Url([uri]$url) {
>> if($url.AbsoluteUri -ne $Null -and $url.Scheme -match 'http|https') {
>> $true
>> } else {
>> $false
>> }
>> }
The Check-Url function has one parameter: $url.
When we call the function, the argument passed to the function needs to
be bound to the corresponding parameter, which can happen either by the
parameter’s name or position. If we simply type the argument value
after the function’s name, the argument will be bound to the parameter
based on the argument’s position. Since we have only one parameter in
this example, the argument will be bound to the $url parameter.
It is also possible to specify the type of parameter
the function will accept (if there are multiple parameters, type
information will also be used in the binding process, after the name
and position). Notice how we use the type System.Uri—an
object representation of a uniform resource identifier (URI), which,
according to Microsoft Developer Network (MSDN), is “a compact
representation of a resource available to your application on the
intranet or Internet.” We then check if the value of its AbsoluteURI property is not null and that the Scheme property value (which represents the protocol) contains either http or https. If the condition evaluates to true, True is returned; if not, False
is returned. This is a quick way of testing if a URL supplied is in the
correct format. We can call the function by typing its name followed by
the URL that we want to check.
PS > Check-Url -url http://SPServer01
True
