< Back
Register-PSFMessageTransform
Post
NAME Register-PSFMessageTransform
SYNOPSIS
Registers a scriptblock that can transform message content.
SYNTAX
Register-PSFMessageTransform -TargetType <String> -ScriptBlock <ScriptBlock> [<CommonParameters>]
Register-PSFMessageTransform -ExceptionType <String> -ScriptBlock <ScriptBlock> [<CommonParameters>]
Register-PSFMessageTransform -ScriptBlock <ScriptBlock> -TargetTypeFilter <String> [-FunctionNameFilter <Object>]
[-ModuleNameFilter <Object>] [<CommonParameters>]
Register-PSFMessageTransform -ScriptBlock <ScriptBlock> -ExceptionTypeFilter <String> [-FunctionNameFilter
<Object>] [-ModuleNameFilter <Object>] [<CommonParameters>]
DESCRIPTION
Registers a scriptblock that can transform message content.
This can be used to convert some kinds of input. Specifically:
Target:
When specifying a target, this target may require some conversion.
For example, an object containing a live connection may need to have a static copy stored instead,
as otherwise its export on a different runspace may cause access violations.
Exceptions:
Some exceptions may need transforming.
For example some APIs might wrap the actual exception into a common wrapper.
In this scenario you may want the actual exception in order to provide more specific information.
In all instances, the scriptblock will be called, receiving only the relevant object as its sole input.
Note: This transformation is performed synchronously on the active runspace. Complex scriptblocks may delay
execution times when a matching object is passed.
PARAMETERS
-TargetType <String>
The full typename of the target object to apply the scriptblock to.
All objects of that typename will be processed through that scriptblock.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ExceptionType <String>
The full typename of the exception object to apply the scriptblock to.
All objects of that typename will be processed through that scriptblock.
Note: In case of error records, the type of the Exception Property is inspected. The error record as a whole
will not be touched, except for having its exception exchanged.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ScriptBlock <ScriptBlock>
The scriptblock that performs the transformation.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TargetTypeFilter <String>
A filter for the typename of the target object to transform.
Supports wildcards, but not regex.
WARNING: Adding too many filter-type transforms may impact overall performance, try to avoid using them!
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ExceptionTypeFilter <String>
A filter for the typename of the exception object to transform.
Supports wildcards, but not regex.
WARNING: Adding too many filter-type transforms may impact overall performance, try to avoid using them!
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FunctionNameFilter <Object>
Default: "*"
Allows filtering by function name, in order to consider whether the function is affected.
Supports wildcards, but not regex.
WARNING: Adding too many filter-type transforms may impact overall performance, try to avoid using them!
Required? false
Position? named
Default value *
Accept pipeline input? false
Accept wildcard characters? false
-ModuleNameFilter <Object>
Default: "*"
Allows filtering by module name, in order to consider whether the function is affected.
Supports wildcards, but not regex.
WARNING: Adding too many filter-type transforms may impact overall performance, try to avoid using them!
Required? false
Position? named
Default value *
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Register-PSFMessageTransform -TargetType 'mymodule.category.classname' -ScriptBlock $ScriptBlock
Whenever a target object of type 'mymodule.category.classname' is specified, invoke $ScriptBlock (with the object
as sole argument) and store the result as target instead.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Register-PSFMessageTransform -ExceptionType 'mymodule.category.exceptionname' -ScriptBlock $ScriptBlock
Whenever an exception or error record of type 'mymodule.category.classname' is specified, invoke $ScriptBlock
(with the object as sole argument) and store the result as exception instead.
If the full error record is specified, only the updated exception will be inserted
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Register-PSFMessageTransform -TargetTypeFilter 'mymodule.category.*' -ScriptBlock $ScriptBlock
Adds a transform for all target objects that are of a type whose full name starts with 'mymodule.category.'
All target objects matching that typename will be run through the specified scriptblock, which in return generates
the new target object.
RELATED LINKS
SYNOPSIS
Registers a scriptblock that can transform message content.
SYNTAX
Register-PSFMessageTransform -TargetType <String> -ScriptBlock <ScriptBlock> [<CommonParameters>]
Register-PSFMessageTransform -ExceptionType <String> -ScriptBlock <ScriptBlock> [<CommonParameters>]
Register-PSFMessageTransform -ScriptBlock <ScriptBlock> -TargetTypeFilter <String> [-FunctionNameFilter <Object>]
[-ModuleNameFilter <Object>] [<CommonParameters>]
Register-PSFMessageTransform -ScriptBlock <ScriptBlock> -ExceptionTypeFilter <String> [-FunctionNameFilter
<Object>] [-ModuleNameFilter <Object>] [<CommonParameters>]
DESCRIPTION
Registers a scriptblock that can transform message content.
This can be used to convert some kinds of input. Specifically:
Target:
When specifying a target, this target may require some conversion.
For example, an object containing a live connection may need to have a static copy stored instead,
as otherwise its export on a different runspace may cause access violations.
Exceptions:
Some exceptions may need transforming.
For example some APIs might wrap the actual exception into a common wrapper.
In this scenario you may want the actual exception in order to provide more specific information.
In all instances, the scriptblock will be called, receiving only the relevant object as its sole input.
Note: This transformation is performed synchronously on the active runspace. Complex scriptblocks may delay
execution times when a matching object is passed.
PARAMETERS
-TargetType <String>
The full typename of the target object to apply the scriptblock to.
All objects of that typename will be processed through that scriptblock.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ExceptionType <String>
The full typename of the exception object to apply the scriptblock to.
All objects of that typename will be processed through that scriptblock.
Note: In case of error records, the type of the Exception Property is inspected. The error record as a whole
will not be touched, except for having its exception exchanged.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ScriptBlock <ScriptBlock>
The scriptblock that performs the transformation.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TargetTypeFilter <String>
A filter for the typename of the target object to transform.
Supports wildcards, but not regex.
WARNING: Adding too many filter-type transforms may impact overall performance, try to avoid using them!
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ExceptionTypeFilter <String>
A filter for the typename of the exception object to transform.
Supports wildcards, but not regex.
WARNING: Adding too many filter-type transforms may impact overall performance, try to avoid using them!
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FunctionNameFilter <Object>
Default: "*"
Allows filtering by function name, in order to consider whether the function is affected.
Supports wildcards, but not regex.
WARNING: Adding too many filter-type transforms may impact overall performance, try to avoid using them!
Required? false
Position? named
Default value *
Accept pipeline input? false
Accept wildcard characters? false
-ModuleNameFilter <Object>
Default: "*"
Allows filtering by module name, in order to consider whether the function is affected.
Supports wildcards, but not regex.
WARNING: Adding too many filter-type transforms may impact overall performance, try to avoid using them!
Required? false
Position? named
Default value *
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Register-PSFMessageTransform -TargetType 'mymodule.category.classname' -ScriptBlock $ScriptBlock
Whenever a target object of type 'mymodule.category.classname' is specified, invoke $ScriptBlock (with the object
as sole argument) and store the result as target instead.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Register-PSFMessageTransform -ExceptionType 'mymodule.category.exceptionname' -ScriptBlock $ScriptBlock
Whenever an exception or error record of type 'mymodule.category.classname' is specified, invoke $ScriptBlock
(with the object as sole argument) and store the result as exception instead.
If the full error record is specified, only the updated exception will be inserted
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Register-PSFMessageTransform -TargetTypeFilter 'mymodule.category.*' -ScriptBlock $ScriptBlock
Adds a transform for all target objects that are of a type whose full name starts with 'mymodule.category.'
All target objects matching that typename will be run through the specified scriptblock, which in return generates
the new target object.
RELATED LINKS