Throws a better error than “throw”.
Stop-ThrowError.ps1 [-ExceptionType] <Type> [-ExceptionArguments] <Object[]> [-ErrorCategory] <ErrorCategory>
[-TargetObject] <Object> [[-ErrorId] <String>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
Stop-ThrowError.ps1 [[-ExceptionType] <Type>] [[-ExceptionArguments] <Object[]>]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
Stop-ThrowError.ps1 [-Message] <String> [-NotImplemented] [-ProgressAction <ActionPreference>]
[<CommonParameters>]
Stop-ThrowError.ps1 [-Message] <String> -SearchContext <Object> [-ProgressAction <ActionPreference>]
[<CommonParameters>]
Stop-ThrowError.ps1 [-Message] <String> [-ProgressAction <ActionPreference>] [<CommonParameters>]
Stop-ThrowError.ps1 [-Message] <String> -OperationContext <Object> [-ProgressAction <ActionPreference>]
[<CommonParameters>]
Stop-ThrowError.ps1 [-Message] <String> -Argument <String> [-ProgressAction <ActionPreference>]
[<CommonParameters>]
Stop-ThrowError.ps1 [-Message] <String> -Format <String> -InputString <String>
[-ProgressAction <ActionPreference>] [<CommonParameters>]
The PowerShell “throw” keyword doesn’t do a good job of providing actionable detail or context:
Unable to remove root node.
At C:\Scripts\Remove-Xml.ps1:34 char:37
+ ... if($node.ParentNode -eq $null) {throw 'Unable to remove root node.'}
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : OperationStopped: (Unable to remove root node.:String) \[\], RuntimeException
+ FullyQualifiedErrorId : Unable to remove root node.
It only shows where the “throw” was used in the called script!
Using $PSCmdlet.ThrowTerminatingError() does a much better job:
C:\Scripts\Remove-Xml.ps1 : Unable to remove root node
Parameter name: SelectXmlInfo
At C:\Scripts\Test-Error.ps1:2 char:23
+ '\<a/\>' |Select-Xml / |Remove-Xml.ps1
+ ~~~~~~~~~~~~~~
+ CategoryInfo : InvalidArgument: (\<a /\>:SelectXmlInfo) \[Remove-Xml.ps1\], ArgumentException
+ FullyQualifiedErrorId : RootRequired,Remove-Xml.ps1
Now you can see where the trouble is in the calling script!
However, contructing an exception, then using that to construct an error with the right ID & category & target object, then using that to call ThrowTerminatingError() is pretty inconvenient.
This script combines that process into a few simple parameters.
Stop-ThrowError.ps1 'Unable to remove root node' -Argument SelectXmlInfo
C:\Scripts\Remove-Xml.ps1 : Unable to remove root node Parameter name: SelectXmlInfo At C:\Scripts\Test-Error.ps1:2 char:23
| ’<a/>’ | Select-Xml / | Remove-Xml.ps1 |
if(Test-Uri.ps1 $u) {[uri]$u} else {Stop-ThrowError.ps1 'Bad URL' -Format URL -InputString $u}
(Fails for non-uri values of $u.)
The type of a Exception class to instantiate as part of the error.
Type: Type
Parameter Sets: Detailed
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Type: Type
Parameter Sets: CatchBlock
Aliases:
Required: False
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
The constructor parameters for the exception class specified by ExceptionTypeName.
Type: Object[]
Parameter Sets: Detailed
Aliases:
Required: True
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Type: Object[]
Parameter Sets: CatchBlock
Aliases:
Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
The error’s category, as an enumeration value.
Type: ErrorCategory
Parameter Sets: Detailed
Aliases:
Accepted values: NotSpecified, OpenError, CloseError, DeviceError, DeadlockDetected, InvalidArgument, InvalidData, InvalidOperation, InvalidResult, InvalidType, MetadataError, NotImplemented, NotInstalled, ObjectNotFound, OperationStopped, OperationTimeout, SyntaxError, ParserError, PermissionDenied, ResourceBusy, ResourceExists, ResourceUnavailable, ReadError, WriteError, FromStdErr, SecurityError, ProtocolError, ConnectionError, AuthenticationError, LimitsExceeded, QuotaExceeded, NotEnabled
Required: True
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
The object in context when the error happened.
Type: Object
Parameter Sets: Detailed
Aliases:
Required: True
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
An string unique to the script that identifies the error. By default this will use the line number it is called from.
Type: String
Parameter Sets: Detailed
Aliases:
Required: False
Position: 5
Default value: "L$(Get-PSCallStack |select -First 1 |% ScriptLineNumber)"
Accept pipeline input: False
Accept wildcard characters: False
Type: String
Parameter Sets: NotImplemented, ItemNotFound, ObjectNotFound, InvalidOperation, InvalidArgument, Format
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
The data format the string failed to parse as.
Type: String
Parameter Sets: Format
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
The string that failed to parse.
Type: String
Parameter Sets: Format
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
The parameter name that had a bad value.
Type: String
Parameter Sets: InvalidArgument
Aliases: InvalidArgument
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
An object containing the state that failed to process.
Type: Object
Parameter Sets: InvalidOperation
Aliases: InvalidOperation
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
An object containing the search detail that failed.
Type: Object
Parameter Sets: ItemNotFound
Aliases: ObjectNotFound
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Indicates that the exception represents incomplete functionality.
Type: SwitchParameter
Parameter Sets: NotImplemented
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
https://docs.microsoft.com/dotnet/api/system.management.automation.cmdlet.throwterminatingerror
https://docs.microsoft.com/dotnet/api/system.management.automation.errorrecord.-ctor