about_Error.help.txt
|
TOPIC
about_Error SHORT DESCRIPTION Error provides two important pieces of error/exception handling functionality that is missing or incomplete from PowerShell; identifying complex exceptions based on hash tables, and writing out detailed stack trace information in text form. LONG DESCRIPTION PowerShell provides a simple try { } catch (type) { } exception handling mechanic, but due to the way exceptions are often wrapped in other exceptions and error records, it is often the case that these will be missed. Furthermore when catching SQL Server exceptions these have an object nested at an arbitrary depth with important properties to indicate what kind of exception it is (such as severity, error number, message, state). Together these two things lead to extremely long and complex catch blocks. To address this a Test-Error function is provided. * Test-Error -Type to identify an exception based on a type; matching not just the top object type but other common objects nested within it. * Test-Error -Property to identify an exception based on a hash table of matching properties on any single nested object within the error. Another function, Resolve-Error, either returns an expanded view of nested objects in an exception, and optionally, converts this into a verbose (but almost readable) string output suitable for use in stack traces. REQUIREMENTS None. EXAMPLE #1 try { $ErrorActionPreference = "Stop" Invoke-Sqlcmd -ServerInstance C1N1 -Query "Select 1/0" -IncludeSqlUserErrors } catch [System.Data.SqlClient.SqlException] { "Caught" } No output. This is because that exception type, despite being thrown, was buried. EXAMPLE #2 try { $ErrorActionPreference = "Stop" Invoke-Sqlcmd -ServerInstance C1N1 -Query "Select 1/0" -IncludeSqlUserErrors } catch { if (Test-Error System.Data.SqlClient.SqlException) { "Caught" } else { "Not caught" } } Results in a Caught output because we successfully matched a nested exception. EXAMPLE #3 try { $ErrorActionPreference = "Stop" Invoke-Sqlcmd -ServerInstance C1N1 -Query "Select 1/0" -IncludeSqlUserErrors } catch { if (Test-Error @{ Class = 16; Number = 8134; }) { "Caught" } else { "Not caught" } } Results in a Caught output because we successfully matched a set of properties. EXAMPLE #4 try { $ErrorActionPreference = "Stop" Invoke-Sqlcmd -ServerInstance C1N1 -Query "Select 1/0" -IncludeSqlUserErrors } catch { Resolve-Error $_ -AsString } A detailed string-style expansion of exceptions, error records, and the stack trace. LINKS https://github.com/codykonior/Error |