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_Advanced_Methods

Functions_Advanced_Methods

 

SHORT DESCRIPTION

    Describes how functions that specify the CmdletBinding attribute can use 
    the methods and properties that are available to compiled cmdlets. 
 

LONG DESCRIPTION

    Functions that specify the CmdletBinding attribute can access a number of  
    methods and properties through the $pscmdlet variable. These methods  
    include the following methods: 
 
 
        - Input-processing methods that compiled cmdlets use to do their work. 
 
        - The ShouldProcess and ShouldContinue methods that are used to get  
          user feedback before an action is performed. 
 
        - The ThrowTerminatingError method for generating error records. 
 
        - Several Write methods that return different types of output. 
 
 
    All the methods and properties of the PSCmdlet class are available to  
    advanced functions. For more information about these methods and  
    properties, see System.Management.Automation.PSCmdlet in the MSDN  
    (Microsoft Developer Network) library at  
    http://go.microsoft.com/fwlink/?LinkId=142139. 
 
 
  Input Processing Methods 
 
      The methods described in this section are referred to as the input  
      processing methods. For functions, these three methods are represented 
      by the Begin, Process, and End blocks of the function. Each function  
      must include one or more of these blocks. The Windows PowerShell runtime 
      uses the code within these blocks when it is running a function. (These 
      blocks are also available to functions that do not use the CmdletBinding 
      attribute.) 
 
       
    Begin 
      This block is used to provide optional one-time preprocessing for the  
      function. The Windows PowerShell runtime uses the code in this block one 
      time for each instance of the function in the pipeline. 
 
 
    Process 
      This block is used to provide record-by-record processing for the  
      function. This block might be used any number of times, or not at all, 
      depending on the input to the function. For example, if the function is 
      the first command in the pipeline, the Process block will be used one  
      time. If the function is not the first command in the pipeline, the  
      Process block is used one time for every input that the function  
      receives from the pipeline. If there is no pipeline input, the Process  
      block is not used. 
 
      This block must be defined if a function parameter is set to accept  
      pipeline input. If this block is not defined and the parameter accepts 
      input from the pipeline, the function will miss the values that are  
      passed to the function through the pipeline.  
 
      Also, when the function supports confirmation requests (when the  
      SupportsShouldProcess parameter of the Parameter attribute is set to  
      $True), the call to the ShouldProcess method must be made from within 
      the Process block. 
 
    End 
      This block is used to provide optional one-time post-processing for  
      the function. 
 
      The following example shows the outline of a function that contains a 
      Begin block for one-time preprocessing, a Process block for multiple  
      record processing, and an End block for one-time post-processing. 
 
          Function Test-ScriptCmdlet 
          { 
            [CmdletBinding(SupportsShouldProcess=$True)]  
            Param ($Parameter1) 
            Begin{} 
            Process{} 
            End{} 
          } 
 
 
  Confirmation Methods 
 
    ShouldProcess 
      This method is called to request confirmation from the user before the  
      function performs an action that would change the system. The function  
      can continue based on the Boolean value returned by the method. This  
      method can be called only from within the Process{} block of the  
      function. And, the CmdletBinding attribute must declare that the  
      function supports ShouldProcess (as shown in the previous example). 
 
      For more information about this method, see  
      System.Management.Automation.Cmdlet.ShouldProcess in the MSDN library at  
      http://go.microsoft.com/fwlink/?LinkId=142142. 
 
      For more information about how to request confirmation, see  
      "Requesting Confirmation" in the MSDN library at  
      http://go.microsoft.com/fwlink/?LinkID=136658. 
 
 
    ShouldContinue 
      This method is called to request a second confirmation message. It  
      should be called when the ShouldProcess method returns $true. For more 
      information about this method, see  
      System.Management.Automation.Cmdlet.ShouldContinue in the MSDN library 
      at http://go.microsoft.com/fwlink/?LinkId=142143. 
 
 
  Error Methods 
 
    Functions can call two different methods when errors occur. When a  
    nonterminating error occurs, the function should call the WriteError  
    method, which is described in the "Write Methods" section. When a  
    terminating error occurs and the function cannot continue, it should call 
    the ThrowTerminatingError method. You can also use the Throw statement for 
    terminating errors and the Write-Error cmdlet for nonterminating errors. 
 
    For more information, see System.Management.Automation.Cmdlet. 
    ThrowTerminatingError in the MSDN libray at  
    http://go.microsoft.com/fwlink/?LinkId=142144. 
 
 
  Write Methods 
 
      A function can call the following methods to return different types of  
      output. Notice that not all the output goes to the next command in the  
      pipeline. You can also use the various Write cmdlets, such as  
      Write-Error. 
 
 
    WriteCommandDetail 
      For information about the WriteCommandDetails method, see  
      System.Management.Automation.Cmdlet.WriteCommandDetail in the MSDN  
      library at http://go.microsoft.com/fwlink/?LinkId=142155. 
 
 
    WriteDebug 
      To provide information that can be used to troubleshoot a function,  
      make the function call the WriteDebug method. This displays debug  
      messages to the user. For more information, see  
      System.Management.Automation.Cmdlet.WriteDebug in the MSDN library 
      at http://go.microsoft.com/fwlink/?LinkId=142156. 
 
 
    WriteError 
      Functions should call this method when nonterminating errors occur and 
      the function is designed to continue processing records. For more  
      information, see System.Management.Automation.Cmdlet.WriteError in the  
      MSDN library at http://go.microsoft.com/fwlink/?LinkId=142157. 
 
      Note: If a terminating error occurs, the function should call the  
            ThrowTerminatingError method.  
 
 
    WriteObject 
      This method allows the function to send an object to the next command in  
      the pipeline. In most cases, this is the method to use when the function 
      returns data. For more information, see  
      System.Management.Automation.PSCmdlet.WriteObject in the MSDN library at 
      http://go.microsoft.com/fwlink/?LinkId=142158. 
 
 
    WriteProgress 
      For functions whose actions take a long time to complete, this method  
      allows the function to call the WriteProgress method so that progress 
      information is displayed. For example, you can display the percent  
      completed. For more information, see  
      System.Management.Automation.PSCmdlet.WriteProgress in the MSDN library 
      at http://go.microsoft.com/fwlink/?LinkId=142160. 
 
 
    WriteVerbose 
      To provide detailed information about what the function is doing, make  
      the function call the WriteVerbose method to display verbose messages to 
      the user. By default, verbose messages are not displayed. For more  
      information, see System.Management.Automation.PSCmdlet.WriteVerbose 
      in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142162. 
 
    WriteWarning 
      To provide information about conditions that may cause unexpected  
      results, make the function call the WriteWarning method to display  
      warning messages to the user. By default, warning messages are displayed. 
      For more information, see  
      System.Management.Automation.PSCmdlet.WriteWarning in the MSDN library  
      at http://go.microsoft.com/fwlink/?LinkId=142164. 
 
      Note: You can also display warning messages by configuring the  
            WarningPreference variable or by using the Verbose and Debug  
            command-line options. 
 
 
  Other Methods and Properties 
 
      For information about the other methods and properties that can be  
      accessed through the $PSCmdlet variable, see  
      System.Management.Automation.PSCmdlet in the MSDN library at 
      http://go.microsoft.com/fwlink/?LinkId=142139.  
 
      For example, the ParameterSetName property allows you to see the parameter  
      set that is being used. Parameter sets allow you to create a function that  
      performs different tasks based on the parameters that are specified when  
      the function is run. 
 
 

SEE ALSO

about_Functions
about_Functions_Advanced
about_Functions_Advanced_Parameters
about_Functions_CmdletBindingAttribute
about_Functions_OutputTypeAttribute