New ErrorRecord

New-ErrorRecord

SYNOPSIS

Creates a new ErrorRecord.

SYNTAX

Exception (Default)

New-ErrorRecord -Exception <Exception> -ErrorCategory <ErrorCategory> [-TargetObject <Object>]
 [-ErrorId <String>] [<CommonParameters>]

ErrorRecord

New-ErrorRecord -ErrorRecord <ErrorRecord> -Exception <Exception> 
 [<CommonParameters>]

DESCRIPTION

The New-ErrorRecord function creates a new ErrorRecord with the specified parameters.

EXAMPLES

EXAMPLE 1

$ex = New-Exception -Message 'An error occurred.'
$errorRecord = New-ErrorRecord -Exception $ex -ErrorCategory 'InvalidOperation'

This example creates a new ErrorRecord with the specified parameters. Passing 'InvalidOperation' which is one available value of the enum [System.Management.Automation.ErrorCategory].

EXAMPLE 2

$ex = New-Exception -Message 'An error occurred.'
$errorRecord = New-ErrorRecord -Exception $ex -ErrorCategory 'InvalidOperation' -TargetObject $myObject

This example creates a new ErrorRecord with the specified parameters. TargetObject is set to the object that was being manipulated when the error occurred.

EXAMPLE 3

$ex = New-Exception -Message 'An error occurred.'
$errorRecord = New-ErrorRecord -Exception $ex -ErrorCategory 'InvalidOperation' -ErrorId 'MyErrorId'

This example creates a new ErrorRecord with the specified parameters. Passing ErrorId that will be set as the FullyQualifiedErrorId in the error record.

EXAMPLE 4

$existingErrorRecord = [System.Management.Automation.ErrorRecord]::new(
    [System.Management.Automation.ParentContainsErrorRecordException]::new('Existing error'),
    'ExistingErrorId',
    [System.Management.Automation.ErrorCategory]::InvalidOperation,
    $null
)
$newException = [System.Exception]::new('New error')
$newErrorRecord = New-ErrorRecord -ErrorRecord $existingErrorRecord -Exception $newException
$newErrorRecord.Exception.Message

This example first creates an emulated ErrorRecord that contain a ParentContainsErrorRecordException which will be replaced by the new exception passed to New-ErrorRecord. The result of $newErrorRecord.Exception.Message will be 'New error'.

PARAMETERS

-ErrorCategory

Specifies the category of the error.

Type: ErrorCategory
Parameter Sets: Exception
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: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ErrorId

Specifies a string that uniquely identifies the error.

Type: String
Parameter Sets: Exception
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ErrorRecord

Specifies an existing ErrorRecord.

Type: ErrorRecord
Parameter Sets: ErrorRecord
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Exception

Specifies the exception that caused the error.

If an error record is passed to parameter ErrorRecord and if the wrapped exception in the error record contains a [System.Management.Automation.ParentContainsErrorRecordException], the new ErrorRecord should have this exception as its Exception instead.

Type: Exception
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TargetObject

Specifies the object that was being manipulated when the error occurred.

Type: Object
Parameter Sets: Exception
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.Management.Automation.ErrorRecord, System.Exception, System.Management.Automation.ErrorCategory, System.Object, System.String

OUTPUTS

System.Management.Automation.ErrorRecord

NOTES

The function supports two parameter sets: 'ErrorRecord' and 'Exception'. If the 'ErrorRecord' parameter set is used, the function creates a new ErrorRecord based on an existing one and an exception. If the 'Exception' parameter set is used, the function creates a new ErrorRecord based on an exception, an error category, a target object, and an error ID.

RELATED LINKS