How-to: Function Input Processing Methods (Begin..Process..End)

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

In PowerShell 3.0 and greater, $PSItem is also available and represents the current input object - exactly the same as $_

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
Confirm the operation with the user. Cmdlets which make changes (e.g. delete files, stop services etc.) should call ShouldProcess to give the user the opportunity to confirm that the operation should actually be performed.
This method allows -confirm, -prompt, -whatif and -verbose switches. see overloads
This method can be called only within advanced functions from within the Process{} block of the function.
The CmdletBinding attribute must declare that the function supports ShouldProcess:
[CmdletBinding(SupportsShouldProcess, ConfirmImpact='Medium')]
Full example here

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 WriteError method, 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. Alternatively you can also use the various Write- cmdlets, such as Write-Error.

WriteCommandDetail Write important information about cmdlet execution to the pipeline 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 PowerShell Cmdlets

Functions and Filters - Write a named block of code.
Advanced functions - include cmdlet features, common parameters -verbose, -whatif, -confirm etc.
$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.
Scriptblock - A collection of statements.
Ref vars - Passing a reference variable to a function.


 
Copyright © 1999-2024 SS64.com
Some rights reserved