Error Handling for SharePoint Foundation Cmdlets

Applies to: SharePoint Foundation 2010

Your cmdlets for SharePoint Foundation must provide basic error management. This means that you must list all conditions in which a cmdlet can error out and, for each condition, describe the expected behavior. Your cmdlets must clean up partial changes when an error occurs, and they must return a meaningful error message, revealing how a system administrator can recover from any error condition. In particular, your cmdlets must be able to differentiate between fatal (terminating) and nonfatal (nonterminating) errors. A fatal error is an error that stops Windows PowerShell from processing a command. Fatal errors terminate the execution of a Windows PowerShell pipeline. A nonterminating error allows Windows PowerShell to continue to operate on the current input object or on further incoming pipeline objects. Furthermore, nonterminating errors present the system with an opportunity to recover.

Handling Errors in Cmdlets for SharePoint

Cmdlets should be resilient enough to withstand invalid property values. While in fatal cases a Get cmdlet must throw a terminating error (for example, if it cannot connect to a specified database), it must treat an object that has invalid properties as a non-terminating error and must write the object to the output pipeline.

Cmdlets must report all nonterminating errors by using the WriteError(Exception, ErrorCategory, Object) method. For terminating errors, cmdlets should throw a localized exception.

Both terminating and nonterminating errors must use localized error strings and must use the current thread locale when reporting errors when using the WriteError(Exception, ErrorCategory, Object) method.

Note

Do not use the Windows PowerShell error-reporting APIs directly; instead, use the SharePoint Foundation APIs for Windows PowerShell that are located in the Microsoft.SharePoint.PowerShell namespace. This ensures compatibility among cmdlets that operate in SharePoint deployments. The SharePoint APIs implement the functionality of the native Windows PowerShell APIs, but, importantly, do additional work such as writing failure data to log files.

See Also

Concepts

Development Guidelines for SharePoint Foundation Cmdlets

Key Concepts for Writing Cmdlets for the SharePoint Management Shell