about_Functions_CmdletBindingAttribute

Applies To: Windows PowerShell 2.0

TOPIC
    about_Functions_CmdletBindingAttribute

SHORT DESCRIPTION
    Describes an attribute that declares a function that acts similar to a 
    compiled cmdlet.

LONG DESCRIPTION
    When you write functions, you can add the CmdletBinding attribute so that 
    Windows PowerShell will bind the parameters of the function in the same 
    way that it binds the parameters of compiled cmdlets. When this attribute
    is declared, Windows PowerShell also sets the $PSCmdlet automatic variable.


    When you use cmdlet binding, unknown parameters and positional arguments 
    that have no matching positional parameters cause parameter binding to
    fail. Also, a function or script with cmdlet binding does not use the 
    $args variable.

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


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

        {
          [CmdletBinding(SupportsShouldProcess=<Boolean>,
                     ConfirmImpact=<String>,
                     DefaultParameterSetName=<String>)]

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


  SupportsShouldProcess

      When the SupportsShouldProcess argument is set to true, it indicates that
      the function supports calls to the ShouldProcess method, which is used to
      prompt the user for feedback before the function makes a change to the 
      system. When this argument is specified, the Confirm and WhatIf 
      parameters are enabled for the function.
 

      For more information about confirmation requests, see "Requesting 
      Confirmation" in the MSDN (Microsoft Developer Network) library at 
      https://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.


  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.

NOTES
  The SupportsTransactions cmdlet attribute is not supported in advanced functions.


SEE ALSO
    about_Functions
    about_Functions_Advanced
    about_Functions_Advanced_Methods
    about_Functions_Advanced_Parameters