about_Functions_CmdletBindingAttribute

Short description

Describes the attribute that makes a function work like a compiled cmdlet.

Long description

The CmdletBinding attribute is an attribute of functions that makes them operate like compiled cmdlets written in C#. It provides access to the features of cmdlets.

When you use the CmdletBinding attribute, PowerShell automatically adds the Common Parameters. You can't create any parameters that use the same names as the Common Parameters. For more information, see about_CommonParameters.

PowerShell binds the parameters of functions that have the CmdletBinding attribute in the same way that it binds the parameters of compiled cmdlets. The $PSCmdlet automatic variable is available to functions with the CmdletBinding attribute, but the $Args variable is not available.

In functions that have the CmdletBinding attribute, unknown parameters and positional arguments that have no matching positional parameters cause parameter binding to fail.

Note

Compiled cmdlets use the required Cmdlet attribute, which is similar to the CmdletBinding attribute that is described in this topic.

Syntax

The following example shows the format of a function that specifies all the optional arguments of the CmdletBinding attribute. A brief description of each argument follows this example.

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

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

The boolean argument types of the CmdletBinding attribute default to False when omitted from the CmdletBinding attribute. Set the argument value to $true or just list the argument by name. For example, the following CmdletBinding attributes are equivalent.

{
    [CmdletBinding(SupportsPaging=$true)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

# Boolean arguments can be defined using this shorthand syntax

{
    [CmdletBinding(SupportsPaging)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

ConfirmImpact

The ConfirmImpact argument specifies when the action of the function should be confirmed by a call to the ShouldProcess method. The call to the ShouldProcess method displays a confirmation prompt only when the ConfirmImpact argument is equal to or greater than the value of the $ConfirmPreference preference variable. (The default value of the argument is Medium.) Specify this argument only when the SupportsShouldProcess argument is also specified.

For more information about confirmation requests, see Requesting Confirmation.

DefaultParameterSetName

The DefaultParameterSetName argument specifies the name of the parameter set that PowerShell will attempt to use when it cannot determine which parameter set to use. You can avoid this issue by making the unique parameter of each parameter set a mandatory parameter.

HelpURI

The HelpURI argument specifies the internet address of the online version of the help topic that describes the function. The value of the HelpURI argument must begin with "http" or "https".

The HelpURI argument value is used for the value of the HelpURI property of the CommandInfo object that Get-Command returns for the function.

However, when help files are installed on the computer and the value of the first link in the RelatedLinks section of the help file is a URI, or the value of the first .Link directive in comment-based help is a URI, the URI in the help file is used as the value of the HelpUri property of the function.

The Get-Help cmdlet uses the value of the HelpURI property to locate the online version of the function help topic when the Online parameter of Get-Help is specified in a command.

SupportsPaging

The SupportsPaging argument adds the First, Skip, and IncludeTotalCount parameters to the function. These parameters allow users to select output from a very large result set. This argument is designed for cmdlets and functions that return data from large data stores that support data selection, such as an SQL database.

This argument was introduced in Windows PowerShell 3.0.

  • First: Gets only the first 'n' objects.
  • Skip: Ignores the first 'n' objects and then gets the remaining objects.
  • IncludeTotalCount: Reports the number of objects in the data set (an integer) followed by the objects. If the cmdlet cannot determine the total count, it returns "Unknown total count".

PowerShell includes NewTotalCount, a helper method that gets the total count value to return and includes an estimate of the accuracy of the total count value.

The following sample function shows how to add support for the paging parameters to an advanced function.

function Get-Numbers {
    [CmdletBinding(SupportsPaging)]
    param()

    $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
    $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First +
      $FirstNumber - 1, 100)

    if ($PSCmdlet.PagingParameters.IncludeTotalCount) {
        $TotalCountAccuracy = 1.0
        $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100,
          $TotalCountAccuracy)
        Write-Output $TotalCount
    }
    $FirstNumber .. $LastNumber | Write-Output
}

SupportsShouldProcess

The SupportsShouldProcess argument adds Confirm and WhatIf parameters to the function. The Confirm parameter prompts the user before it runs the command on each object in the pipeline. The WhatIf parameter lists the changes that the command would make, instead of running the command.

PositionalBinding

The PositionalBinding argument determines whether parameters in the function are positional by default. The default value is $True. You can use the PositionalBinding argument with a value of $False to disable positional binding.

The PositionalBinding argument is introduced in Windows PowerShell 3.0.

When parameters are positional, the parameter name is optional. PowerShell associates unnamed parameter values with the function parameters according to the order or position of the unnamed parameter values in the function command.

When parameters are not positional (they are "named"), the parameter name (or an abbreviation or alias of the name) is required in the command.

When PositionalBinding is $True, function parameters are positional by default. PowerShell assigns position number to the parameters in the order in which they are declared in the function.

When PositionalBinding is $False, function parameters are not positional by default. Unless the Position argument of the Parameter attribute is declared on the parameter, the parameter name (or an alias or abbreviation) must be included when the parameter is used in a function.

The Position argument of the Parameter attribute takes precedence over the PositionalBinding default value. You can use the Position argument to specify a position value for a parameter. For more information about the Position argument, see about_Functions_Advanced_Parameters.

Notes

The SupportsTransactions argument is not supported in advanced functions.

Keywords

about_Functions_CmdletBinding_Attribute

See also