TOPIC
about_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.
- 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
https://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
https://go.microsoft.com/fwlink/?LinkId=142142.
For more information about how to request confirmation, see
"Requesting Confirmation" in the MSDN library at
https://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 https://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
https://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 https://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 https://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 https://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
https://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 https://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 https://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 https://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
https://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_Advanced
about_Functions_CmdletBindingAttributes
about_Functions_Advanced_Parameters