Function Input Processing Methods (Begin..Process..End)

For functions, (and V2 scriptCmdlets) three methods are available for processing pipeline input: Begin, Process, and End blocks. In these blocks, the $_ variable represents the current input object.

Scripts, functions, and script blocks also have access to the $input variable, which provides an enumerator over the elements in the incoming pipeline.

Begin

This block is used to provide optional one-time pre-processing for the function.
The 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.

A Filter is a shorthand representation of a function whose body is composed entirely of a process block.

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, if the function/cmdlet supports confirmation requests (the -SupportsShouldProcess parameter 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-Demo
 {
  Param ($Param1)
  Begin{ write-host "Starting"}
  Process{ write-host "processing" $_ for $Param1}
  End{write-host "Ending"}
 }

PS C:\> Echo Testing1, Testing2 | Test-Demo Sample

Confirmation Methods

ShouldProcess
This method allows -confirm, -prompt, -whatif and -verbose switches, the method may be called to request confirmation from the user before the function performs an action that would change the system.
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. Example

ShouldContinue
This method is called to request a second confirmation message. It should be called when the ShouldProcess method returns $true.

Error Methods

Functions can call two different methods when errors occur.
When a nonterminating error occurs, the function should call the WriteErrormethod, which is described below.
When a terminating error occurs and the function cannot continue, it should call the ThrowTerminatingError method. When this method is called, the PowerShell runtime catches the error record and then starts shutting down the pipeline.

You can also use the Throw statement for terminating errors and the Write-Error cmdlet for nonterminating errors.

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 Text to be written to the execution log.

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.

WriteError Functions should call this method when nonterminating errors occur and the function is designed to continue processing records. When this method is called, an error record is sent to the error pipeline and control is returned to the cmdlet for more processing. 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.

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 to the host. For example, you can display the percent completed.

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 while the function is performing a task. By default, verbose messages are not displayed.

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.

Note: You can also display warning messages by configuring the WarningPreference variable or by using the -Verbose and -Debug command-line options.

“The function of the imagination is not to make strange things settled, so much as to make settled things strange” ~ G. K. Chesterton

Related:

$PSCmdlet variable
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.
Ref vars - Passing a reference variable to a function.


© Copyright SS64.com 1999-2014
Some rights reserved