Cmdlet Input Processing Methods

Cmdlets must override one or more of the input processing methods described in this topic to perform their work. These methods allow the cmdlet to perform pre-processing operations, input processing operations, and post-processing operations. These methods also allow you to stop cmdlet processing.

Pre-Processing Tasks

Cmdlets should override the System.Management.Automation.Cmdlet.Beginprocessing%2A?Displayproperty=Fullname method to add any preprocessing operations that are valid for all the records that will be processed later by the cmdlet. When Windows PowerShell processes a command pipeline, Windows PowerShell calls this method once for each instance of the cmdlet in the pipeline. For more information about how Windows PowerShell invokes the command pipeline, see Cmdlet Processing Lifecycle.

The following code shows an implementation of the System.Management.Automation.Cmdlet.Beginprocessing%2A?Displayproperty=Fullname method.

protected override void BeginProcessing()
{
  // Replace the WriteObject method with the logic required
  // by your cmdlet. It is used here to generate the following
  // output:
  // "This is a test of the BeginProcessing template."
  WriteObject("This is a test of the BeginProcessing template.");
}

For a more detailed example of how to use the System.Management.Automation.Cmdlet.Beginprocessing%2A?Displayproperty=Fullname method, see SelectStr Tutorial. In this tutorial, the Select-Str cmdlet uses the System.Management.Automation.Cmdlet.Beginprocessing%2A?Displayproperty=Fullname method to generate the regular expression that is used to search the input processing records.

Input Processing Tasks

Cmdlets can override the System.Management.Automation.Cmdlet.Processrecord%2A?Displayproperty=Fullname method to process the input that is sent to the cmdlet. When Windows PowerShell processes a command pipeline, Windows PowerShell calls this method for each input record that is processed by the cmdlet. For more information about how Windows PowerShell invokes the command pipeline, see Cmdlet Processing Lifecycle. Cmdlets can override the System.Management.Automation.Cmdlet.Processrecord%2A?Displayproperty=Fullname method to process the input that is sent to the cmdlet. When Windows PowerShell processes a command pipeline, Windows PowerShell calls this method for each input record that is processed by the cmdlet. For more information about how Windows PowerShell invokes the command pipeline, see Cmdlet Processing Lifecycle.

The following code shows an implementation of the System.Management.Automation.Cmdlet.Processrecord%2A?Displayproperty=Fullname method.

protected override void ProcessRecord()
{
  // Replace the WriteObject method with the logic required
  // by your cmdlet. It is used here to generate the following
  // output:
  // "This is a test of the ProcessRecord template."
  WriteObject("This is a test of the ProcessRecord template.");
}

For a more detailed example of how to use the System.Management.Automation.Cmdlet.Processrecord%2A?Displayproperty=Fullname method, see SelectStr Tutorial.

Post-Processing Tasks

Cmdlets should override the System.Management.Automation.Cmdlet.Endprocessing%2A?Displayproperty=Fullname method to add any post-processing operations that are valid for all the records that were processed by the cmdlet. For example, your cmdlet might have to clean up object variables after it is finished processing.

When Windows PowerShell processes a command pipeline, Windows PowerShell calls this method once for each instance of the cmdlet in the pipeline. However, it is important to remember that the Windows PowerShell runtime will not call the System.Management.Automation.Cmdlet.Endprocessing%2A?Displayproperty=Fullname method if the cmdlet is canceled midway through its input processing or if a terminating error occurs in any part of the cmdlet. For this reason, a cmdlet that requires object cleanup should implement the complete System.Idisposable pattern, including a finalizer, so that the runtime can call both the System.Management.Automation.Cmdlet.Endprocessing%2A?Displayproperty=Fullname and System.Idisposable.Dispose* methods at the end of processing. For more information about how Windows PowerShell invokes the command pipeline, see Cmdlet Processing Lifecycle. When Windows PowerShell processes a command pipeline, Windows PowerShell calls this method once for each instance of the cmdlet in the pipeline. However, it is important to remember that the Windows PowerShell runtime will not call the System.Management.Automation.Cmdlet.Endprocessing%2A?Displayproperty=Fullname method if the cmdlet is canceled midway through its input processing or if a terminating error occurs in any part of the cmdlet. For this reason, a cmdlet that requires object cleanup should implement the complete System.Idisposable pattern, including a finalizer, so that the runtime can call both the System.Management.Automation.Cmdlet.Endprocessing%2A?Displayproperty=Fullname and System.Idisposable.Dispose* methods at the end of processing. For more information about how Windows PowerShell invokes the command pipeline, see Cmdlet Processing Lifecycle.

The following code shows an implementation of the System.Management.Automation.Cmdlet.Processrecord%2A?Displayproperty=Fullname method.

protected override void EndProcessing()
{
  // Replace the WriteObject method with the logic required
  // by your cmdlet. It is used here to generate the following
  // output:
  // "This is a test of the EndProcessing template."
  WriteObject("This is a test of the EndProcessing template.");
}

For a more detailed example of how to use the System.Management.Automation.Cmdlet.Processrecord%2A?Displayproperty=Fullname method, see SelectStr Tutorial.

See Also

System.Management.Automation.Cmdlet.Beginprocessing%2A?Displayproperty=Fullname

System.Management.Automation.Cmdlet.Processrecord%2A?Displayproperty=Fullname

System.Management.Automation.Cmdlet.Endprocessing%2A?Displayproperty=Fullname

System.Idisposable

Windows PowerShell Shell SDK