PowerShell Logo Small

about_Functions_CmdletBindingAttribute



This is the built-in help made by Microsoft for the document 'about_Functions_CmdletBindingAttribute', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-24.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

Search powershellhelp.space

about_Functions_CmdletBindingAttribute
TOPIC
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 that are written in C#, and it
provides access to features of cmdlets.

Windows 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{}
}


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" in the MSDN (Microsoft Developer Network) library at
http://go.microsoft.com/fwlink/?LinkId=136658.


DefaultParameterSetName
The DefaultParameterSetName argument specifies the name of the parameter
set that Windows 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 (Uniform Resource
Identifier (URI)) 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 a 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".

Windows 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 = $true)]
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. Windows
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. Windows 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
(http://go.microsoft.com/fwlink/?LinkID=135173).

NOTES
The SupportsTransactions argument is not supported in advanced functions.

KEYWORDS
about_Functions_CmdletBinding_Attribute

SEE ALSO
about_Functions
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_Advanced_Parameters
about_Functions_OutputTypeAttribute