Export (0) Print
Expand All
Expand Minimize

about_Functions_CmdletBindingAttribute

Updated: August 9, 2012

Applies To: Windows PowerShell 2.0, Windows PowerShell 3.0

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



Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft