Specifying function attributes

In case of advanced functions, we use Cmdlet bindings to control the feature or function of the function itself. With this, we define how the function works or behaves.

Addition of the [CmdletBinding()]line allows you to define these controls in an advanced function. Note that with the use of CmdletBinding(), we get the $PSCmdlet automatic variable, but the $Args variable is not available in these functions.

In advanced functions, with the CmdletBinding attribute, unknown parameters and positional arguments that do not have any matching positional parameters results in parameter binding to fail.

Let's examine the available options with the CmdletBinding() attribute and their meaning:

<#
     Comment Based Help
#>
function <function_name> {

[CmdletBinding(ConfirmImpact=<String>,
                     DefaultParameterSetName=<String>,
                     HelpURI=<URI>,
                     SupportsPaging=<Boolean>,
                     SupportsShouldProcess=<Boolean>,
                     PositionalBinding=<Boolean>)]

[OutputType()]
Param(
<Parameters>
)
BEGIN{<# some script> }
PROCESS{<#some script>}
END{<#some script>}
}

So, the options available with CmdletBinding() are as follows:

  • ConfirmImpact=<String>: By specifying this argument, we can control when the action of the function can be confirmed by calling the ShouldProcess method. We need to specify this argument along with the SupportsShouldProcess argument.
  • DefaultParameterSetName=<String>:As the name suggests, this argument specifies which parameter is set to be used as the default value if PowerShell cannot find other parameters.
  • HelpURI=<URI>: This argument specifies the Internet address of the external online location of the function's help. It should start with http or https, thus specifying the address.
  • SupportsPaging=<Boolean>: This argument adds the First, Skip, and IncludeTotalCount parameters to the functions. This argument is generally used when there is a large set of input parameters and you need to select these input parameters. The parameters allow you to define the following:
    • First: It returns the first n objects from all the input objects.
    • Skip: Using this parameter, you can skip the first n objects and get the remaining objects.
    • IncludeTotalCount: This parameter reports the number of total objects in the dataset. This is an integer.
  • SupportsShouldProcess=<Boolean>: Using this argument, you can use the Confirm and WhatIf parameters of the function. The Confirm parameter will Confirm before the command is run on the objects, and the WhatIf parameter will list the changes that the commands will make. By specifying the WhatIf parameter, we will know what will happen and we can ensure that no unnecessary changes will be made.
  • PositionalBinding=<Boolean>: Using this argument, you can check whether the parameters in the function are positional in nature. By default, this is taken as $true, making the parameters positional in nature; thus, if you want to make it otherwise, you need to specify $false as the value to this argument.

The parameters in the PowerShell function are of two types: static and dynamic. For now, we will talk about static parameters, and later in this chapter, we will cover the dynamic parameters.

Static parameters are the ones that are always available in the function scope. Most of the cmdlets and scripts in PowerShell belong to this category.

Parameter attributes are used in order to control and manage the behaviors of the parameters. They define the characteristics of the parameter. The general format to define parameter attributes is as follows:

Param(
    [parameter(attribute=value, attribute=value)]
    [<variable type>]
    $variable
)

If we use the param attribute to define an advanced function, then we need to write it in the following format:

Param (
  [parameter()]
  [<variable type>] $variable
)

Notice that, though we did not provide any attributes to the parameter, we still need to mention it in the opening and closing brackets. This is what will indicate that the function is an advanced function. The attributes that we specify for a parameter can be divided into the following two categories:

  • The parameter attribute
  • The parameter and variable validation attributes

Let's discuss these categories and the different attributes available under them in detail.

上一章目录下一章