functions/message/Register-PSFMessageTransform.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
function Register-PSFMessageTransform
{
    <#
  .SYNOPSIS
   Registers a scriptblock that can transform message content.
   
  .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.
   
  .PARAMETER TargetType
   The full typename of the target object to apply the scriptblock to.
   All objects of that typename will be processed through that scriptblock.
   
  .PARAMETER ExceptionType
   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.
   
  .PARAMETER ScriptBlock
   The scriptblock that performs the transformation.
   
  .PARAMETER TargetTypeFilter
   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!
   
  .PARAMETER ExceptionTypeFilter
   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!
   
  .PARAMETER FunctionNameFilter
   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!
   
  .PARAMETER ModuleNameFilter
   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!
   
  .EXAMPLE
   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
   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
   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.
 #>

    [CmdletBinding(PositionalBinding = $false)]
    Param (
        [Parameter(Mandatory = $true, ParameterSetName = "Target")]
        [string]
        $TargetType,
        
        [Parameter(Mandatory = $true, ParameterSetName = "Exception")]
        [string]
        $ExceptionType,
        
        [Parameter(Mandatory = $true)]
        [ScriptBlock]
        $ScriptBlock,
        
        [Parameter(Mandatory = $true, ParameterSetName = "TargetFilter")]
        [string]
        $TargetTypeFilter,
        
        [Parameter(Mandatory = $true, ParameterSetName = "ExceptionFilter")]
        [string]
        $ExceptionTypeFilter,
        
        [Parameter(ParameterSetName = "TargetFilter")]
        [Parameter(ParameterSetName = "ExceptionFilter")]
        $FunctionNameFilter = "*",
        
        [Parameter(ParameterSetName = "TargetFilter")]
        [Parameter(ParameterSetName = "ExceptionFilter")]
        $ModuleNameFilter = "*"
    )
    
    process
    {
        if ($TargetType) { [PSFramework.Message.MessageHost]::TargetTransforms[$TargetType.ToLower()] = $ScriptBlock }
        if ($ExceptionType) { [PSFramework.Message.MessageHost]::ExceptionTransforms[$ExceptionType.ToLower()] = $ScriptBlock }
        
        if ($TargetTypeFilter)
        {
            $condition = New-Object PSFramework.Message.TransformCondition($TargetTypeFilter, $ModuleNameFilter, $FunctionNameFilter, $ScriptBlock, "Target")
            [PSFramework.Message.MessageHost]::TargetTransformList.Add($condition)
        }
        
        if ($ExceptionTypeFilter)
        {
            $condition = New-Object PSFramework.Message.TransformCondition($ExceptionTypeFilter, $ModuleNameFilter, $FunctionNameFilter, $ScriptBlock, "Exception")
            [PSFramework.Message.MessageHost]::ExceptionTransformList.Add($condition)
        }
    }
}