Windows PowerShell provides two mechanisms for reporting errors. Your cmdlet should call the ThrowTerminatingError method when an error occurs and when the cmdlet cannot or should not continue to process records. In contrast, your cmdlet should call the WriteError method to report nonterminating errors when the cmdlet can continue processing the next record in the pipeline, or when it can continue processing the current record in the pipeline.
The following guidelines can be used to determine if an error is a terminating or nonterminating error.
-
An error that prevents your cmdlet from continuing to process the current object or successfully process any further input objects, regardless of their content. This is a terminating error.
-
An error in which you do not want your cmdlet to continue processing the current object or successfully process any further input objects, regardless of their content. This is a terminating error.
-
An error that is related to a specific input object or subset of input objects. This is a nonterminating error.
-
Your cmdlet accepts multiple input objects and although an error occurred, the operation might succeed on a subsequent input object. This is a nonterminating error.
-
When cmdlets that accept multiple input objects receive only one object, they must decide on whether to treat this case in the same way as they would treat the first object of multiple objects. This could be a terminating or nonterminating error.
-
Cmdlets that accept only 0-1 input objects and write only 0-1 output objects should usually report terminating errors.
Terminating Errors
When a terminating error occurs, the cmdlet should report the error by calling the ThrowTerminatingError method. This method allows the cmdlet to report information that describes the condition that caused the terminating error. For more information about error records, see Windows PowerShell Error Records.
When the ThrowTerminatingError method is called, the Windows PowerShell runtime permanently stops the execution of the pipeline and throws a PipelineStoppedException exception. Any subsequent attempts to call WriteObject, WriteError, or several other APIs will result in those calls throwing a PipelineStoppedException exception.
The PipelineStoppedException exception can also occur if some other cmdlet in the pipeline has reported a terminating error, if the user has asked that the pipeline be stopped, or if for any reason the pipeline has been halted before completion. The cmdlet does not need to catch the PipelineStoppedException exception unless it must clean up open resources or its internal state.
Cmdlets can write any number of output objects or nonterminating errors before reporting a terminating error. The terminating error permanently stops the pipeline, and no further output or terminating or nonterminating errors can be reported. However, cmdlets may call ThrowTerminatingError only from the thread that called the input processing methods BeginProcessing, ProcessRecord, or EndProcessing. Do not attempt to call ThrowTerminatingError or WriteError from another thread. Instead, errors must be communicated back to the main thread.
It is possible for a cmdlet to throw an exception in its implementation of BeginProcessing, ProcessRecord, or EndProcessing. Any exception thrown from these methods (except for a few severe error conditions which will stop the Windows PowerShell host) will be interpreted as a terminating error, which stops the pipeline, but not Windows PowerShell as a whole. (This only applies to the main cmdlet thread; uncaught exceptions in threads spawned by the cmdlet will, in general, halt the Windows PowerShell host.) It is preferable to use ThrowTerminatingError rather than throwing an exception, because the error record provides additional information about the error condition which is useful to the end-user. Cmdlets should honor the overall Managed Code guideline against catching and handling all exceptions ("catch (Exception e)"), and only convert exceptions of known and expected types into error records.
Nonterminating Errors
When a nonterminating error occurs, for example, the failure to stop a particular process, the cmdlet should report this error by calling the WriteError method. When the cmdlet writes a nonterminating error, the cmdlet can continue to operate on this input object and on further incoming pipeline objects. Calling the WriteError method allows the cmdlet to write an error record that describes the condition that caused the nonterminating error. For more information about error records, see Windows PowerShell Error Records.
Cmdlets can call WriteError as necessary from within their input processing methods. However, cmdlets may only call WriteError from the thread that called the input processing methods BeginProcessing, ProcessRecord, or EndProcessing. Do not call WriteError from another thread. Instead, errors must be communicated back to the main thread.
Displaying Error Information by Category
When your cmdlet encounters an error, the presentation of the error information will, by default, look similar to the following error output.
$ stop-service lanmanworkstation
You do not have sufficient permissions to stop the service Workstation.
However, users can choose to view errors by category, by setting the $ErrorView variable to "CategoryView". Category view displays specific information from the error record, rather than a free-text description of the error. This view can be useful if you have a long list of errors to visually scan.
$ $ErrorView = "CategoryView"
$ stop-service lanmanworkstation
CloseError: (System.ServiceProcess.ServiceController:ServiceController) [stop-service], ServiceCommandException
For more information about error categories, see Windows PowerShell Error Records.
See Also
