functions/message/Register-PSFMessageEvent.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
125
126
127
128
129
130
131
132
133
134
function Register-PSFMessageEvent
{
    <#
  .SYNOPSIS
   Registers an event to when a message is written.
   
  .DESCRIPTION
   Registers an event to when a message is written.
   These events will fire whenever the written message fulfills the specified filter criteria.
  
   This allows integrating direct alerts and reactions to messages as they occur.
  
   Warnings:
   - Adding many subscriptions can impact overall performance, even without triggering.
   - Events are executed synchronously. executing complex operations may introduce a significant delay to the command execution.
  
   It is recommended to push processing that involves outside resources to a separate runspace, then use the event to pass the object as trigger.
   The TaskEngine component may prove to be just what is needed to accomplish this.
   
  .PARAMETER Name
   The name of the subscription.
   Each subscription must have a name, subscriptions of equal name will overwrite each other.
   This is in order to avoid having runspace uses explode the number of subscriptions on each invocation.
   
  .PARAMETER ScriptBlock
   The scriptblock to execute.
   It will receive the message entry (as returned by Get-PSFMessage) as its sole argument.
   
  .PARAMETER MessageFilter
   Filter by message content. Understands wildcards, but not regex.
   
  .PARAMETER ModuleNameFilter
   Filter by Name of the module, from which the message comes. Understands wildcards, but not regex.
   
  .PARAMETER FunctionNameFilter
   Filter by Name of the function, from which the message comes. Understands wildcards, but not regex.
   
  .PARAMETER TargetFilter
   Filter by target object. Performs equality comparison on an object level.
   
  .PARAMETER LevelFilter
   Include only messages of the specified levels.
   
  .PARAMETER TagFilter
   Only include messages with any of the specified tags.
   
  .PARAMETER RunspaceFilter
   Only include messages which were written by the specified runspace.
   You can find out the current runspace ID by running this:
     [System.Management.Automation.Runspaces.Runspace]::DefaultRunspace.InstanceId
   You can retrieve the primary runspace - the Guid used by the runspace the user sees - by running this:
     [PSFramework.Utility.UtilityHost]::PrimaryRunspace
   
  .EXAMPLE
   PS C:\> Register-PSFMessageEvent -Name 'Mymodule.OffloadTrigger' -ScriptBlock $ScriptBlock -Tag 'engine' -Module 'MyModule' -Level Warning
  
   Registers an event subscription ...
   - Under the name 'Mymodule.OffloadTrigger' ...
   - To execute $ScriptBlock ...
   - Whenever a message is written with the tag 'engine' by the module 'MyModule' at the level 'Warning'
 #>

    [CmdletBinding(PositionalBinding = $false)]
    Param (
        [Parameter(Mandatory = $true)]
        [string]
        $Name,
        
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.ScriptBlock]
        $ScriptBlock,
        
        [string]
        $MessageFilter,
        
        [string]
        $ModuleNameFilter,
        
        [string]
        $FunctionNameFilter,
        
        $TargetFilter,
        
        [PSFramework.Message.MessageLevel[]]
        $LevelFilter,
        
        [string[]]
        $TagFilter,
        
        [System.Guid]
        $RunspaceFilter
    )
    
    $newName = $Name.ToLower()
    $eventSubscription = New-Object PSFramework.Message.MessageEventSubscription
    $eventSubscription.Name = $newName
    $eventSubscription.ScriptBlock = $ScriptBlock
    
    if (Test-PSFParameterBinding -ParameterName MessageFilter)
    {
        $eventSubscription.MessageFilter = $MessageFilter
    }
    
    if (Test-PSFParameterBinding -ParameterName ModuleNameFilter)
    {
        $eventSubscription.ModuleNameFilter = $ModuleNameFilter
    }
    
    if (Test-PSFParameterBinding -ParameterName FunctionNameFilter)
    {
        $eventSubscription.FunctionNameFilter = $FunctionNameFilter
    }
    
    if (Test-PSFParameterBinding -ParameterName TargetFilter)
    {
        $eventSubscription.TargetFilter = $TargetFilter
    }
    
    if (Test-PSFParameterBinding -ParameterName LevelFilter)
    {
        $eventSubscription.LevelFilter = $LevelFilter
    }
    
    if (Test-PSFParameterBinding -ParameterName TagFilter)
    {
        $eventSubscription.TagFilter = $TagFilter
    }
    
    if (Test-PSFParameterBinding -ParameterName RunspaceFilter)
    {
        $eventSubscription.RunspaceFilter = $RunspaceFilter
    }
    
    [PSFramework.Message.MessageHost]::Events[$newName] = $eventSubscription
}