About Help

Choose a topic from the list on the left or search for a specific topic. Choose a topic from the list or search for a specific topic.
Cmdlets  Providers
 

about_Functions_CmdletBindingAttribute

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