| Server IP : 134.29.175.74 / Your IP : 216.73.216.160 Web Server : nginx/1.10.2 System : Windows NT CST-WEBSERVER 10.0 build 19045 (Windows 10) i586 User : Administrator ( 0) PHP Version : 7.1.0 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : /Windows/System32/WindowsPowerShell/v1.0/en-US/ |
Upload File : |
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.
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.
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 = $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. 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
about_Functions
about_Functions_Advanced
about_Functions_Advanced_Methods
about_Functions_Advanced_Parameters
about_Functions_OutputTypeAttribute