TOPIC about_Functions SHORT DESCRIPTION Describes how to create and use functions in Windows PowerShell. LONG DESCRIPTION A function is a list of statements that has a name that you assign. When you run a function, you type the function name. The statements in the list run as if you had typed them at the command prompt. Like cmdlets, functions can have parameters. The parameters can be named, positional, switch, or dynamic parameters. Function parameters can be read from the command line or from the pipeline. Functions can return values that can be displayed, assigned to variables, or passed to other functions or cmdlets. The function's statement list can contain different types of statement lists with the keywords Begin, Process, and End. These statement lists handle input from the pipeline differently. A filter is a special kind of function that uses the Filter keyword. Functions can also act like cmdlets. You can create a function that works just like a cmdlet without using C# programming. For more information, see about_Functions_Advanced. Syntax The following is the syntax for a function: function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])] { param([type]$parameter1 [,[type]$parameter2]) dynamicparam {<statement list>} begin {<statement list>} process {<statement list>} end {<statement list>} } A function includes the following items: - A Function keyword - A scope (optional) - A name that you select - Any number of named parameters (optional) - One or more Windows PowerShell commands enclosed in braces ({}) For more information about the Dynamicparam keyword and dynamic parameters in functions, see about_Functions_Advanced_Parameters. Simple Functions Functions do not have to be complicated to be useful. The following function gets the environment variables that do not belong to the System account of the current system: function other_env { get-wmiObject win32_environment | where {$_.username -ne "<System>"} } To run the function, type "other_env". You can create a toolbox of useful small functions. Add these functions to your Windows PowerShell profile, as described in about_Profiles and later in this topic. Functions with Parameters You can use parameters with functions, including named parameters, positional parameters, switch parameters, and dynamic parameters. For more information about dynamic parameters in functions, see about_Functions_Advanced_Parameters. Named Parameters You can define any number of named parameters. You can include a default value for named parameters, as described later in this topic. You can define parameters inside the braces using the Param keyword, as shown in the following sample syntax: function <name> { param ([type]$parameter1[,[type]$parameter2]) <statement list> } You can also define parameters outside the braces without the Param keyword, as shown in the following sample syntax: function <name> [([type]$parameter1[,[type]$parameter2])] { <statement list> } There is no difference between these two methods. Use the method that you prefer. When you run the function, the value you supply for a parameter is assigned to a variable that contains the parameter name. The value of that variable can be used in the function. The following example is a function called Small_files. This function has a $size parameter. The function displays all the files that are smaller than the value of the $size parameter, and it excludes directories: function small_files { param ($size) Get-ChildItem c:\ | where { $_.length -lt $size -and !$_.PSIsContainer} } In the function, you can use the $size variable, which is the name defined for the parameter. To use this function, type the following command: C:\PS> function small_files –size 50 You can also enter a value for a named parameter without the parameter name. For example, the following command gives the same result as a command that names the Size parameter: C:\PS> function small_files 50 To define a default value for a parameter, type an equal sign and the value after the parameter name, as shown in the following variation of the Small_files example: function small_files ($size = 100) { Get-ChildItem c:\ | where { $_.length -lt $size -and !$_.PSIsContainer} } If you type "small_files" without a value, the function assigns 100 to $size. If you provide a value, the function uses that value. Positional Parameters A positional parameter is a parameter without a parameter name. Windows PowerShell uses the parameter value order to associate each parameter value with a parameter in the function. When you use positional parameters, type one or more values after the function name. Positional parameter values are assigned to the $args array variable. The value that follows the function name is assigned to the first position in the $args array, $args[0]. The following Extension function adds the .txt file name extension to a file name that you supply: function extension { $name = $args[0] + ".txt" $name } C:\PS> extension myTextFile myTextFile.txt Functions can take more than one positional parameter. The following example displays any values entered with the function name. function repeat { foreach ($arg in $args) { "The input is $arg" } } C:\PS>repeat one The input is one C:\PS> repeat one two three The input is one The input is two The input is three This function can be used with any number of values. The function assigns each value to a position in the $args array. Switch Parameters A switch is a parameter that does not require a value. Instead, you type the function name followed by the name of the switch parameter. To define a switch parameter, specify the type [switch] before the parameter name, as shown in the following example: function switchExample { param ([switch]$on) if ($on) { "Switch on" } else { "Switch off" } } When you type the On switch parameter after the function name, the function displays "Switch on". Without the switch parameter, it displays "Switch off". C:\PS> SwitchExample -on Switch on C:\PS> SwitchExample Switch off You can also assign a Boolean value to a switch when you run the function, as shown in the following example: C:\PS> SwitchExample -on:$true Switch on C:\PS> SwitchExample -on:$false Switch off Piping Objects to Functions Any function can take input from the pipeline. You can control how a function processes input from the pipeline using Begin, Process, and End keywords. The following sample syntax shows the three keywords: function <name> { begin {<statement list>} process {<statement list>} end {<statement list>} } The Begin statement list runs one time only, at the beginning of the function. The Process statement list runs one time for each object in the pipeline. While the Process block is running, each pipeline object is assigned to the $_ automatic variable, one pipeline object at a time. After the function receives all the objects in the pipeline, the End statement list runs one time. If no Begin, Process, or End keywords are used, all the statements are treated like an End statement list. The following function uses the Process keyword. The function displays examples from the pipeline: function pipelineFunction { process {"The value is: $_"} } To demonstrate this function, enter an array of numbers created with commas, as shown in the following example: C:\PS> 1,2,4 | pipelineFunction The value is: 1 The value is: 2 The value is: 4 When you use a function in a pipeline, the objects piped to the function are assigned to the $input automatic variable. The function runs statements with the Begin keyword before any objects come from the pipeline. The function runs statements with the End keyword after all the objects have been received from the pipeline. The following example shows the $input automatic variable with Begin and End keywords. ...
magdula294