internal/functions/Register-DbaMessageEvent.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
function Register-DbaMessageEvent {
    <#
    .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-DbatoolsLog) 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:
        [Sqlcollaborative.Dbatools.Utility.UtilityHost]::PrimaryRunspace
 
    .EXAMPLE
        PS C:\> Register-DbaMessageEvent -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)]
        [string]
        $Name,

        [Parameter(Mandatory)]
        [System.Management.Automation.ScriptBlock]
        $ScriptBlock,

        [string]
        $MessageFilter,

        [string]
        $ModuleNameFilter,

        [string]
        $FunctionNameFilter,

        $TargetFilter,

        [Sqlcollaborative.Dbatools.Message.MessageLevel[]]
        $LevelFilter,

        [string[]]
        $TagFilter,

        [System.Guid]
        $RunspaceFilter
    )

    $newName = $Name.ToLower()
    $eventSubscription = New-Object Sqlcollaborative.Dbatools.Message.MessageEventSubscription
    $eventSubscription.Name = $newName
    $eventSubscription.ScriptBlock = $ScriptBlock

    if (Test-Bound -ParameterName MessageFilter) {
        $eventSubscription.MessageFilter = $MessageFilter
    }

    if (Test-Bound -ParameterName ModuleNameFilter) {
        $eventSubscription.ModuleNameFilter = $ModuleNameFilter
    }

    if (Test-Bound -ParameterName FunctionNameFilter) {
        $eventSubscription.FunctionNameFilter = $FunctionNameFilter
    }

    if (Test-Bound -ParameterName TargetFilter) {
        $eventSubscription.TargetFilter = $TargetFilter
    }

    if (Test-Bound -ParameterName LevelFilter) {
        $eventSubscription.LevelFilter = $LevelFilter
    }

    if (Test-Bound -ParameterName TagFilter) {
        $eventSubscription.TagFilter = $TagFilter
    }

    if (Test-Bound -ParameterName RunspaceFilter) {
        $eventSubscription.RunspaceFilter = $RunspaceFilter
    }

    [Sqlcollaborative.Dbatools.Message.MessageHost]::Events[$newName] = $eventSubscription
}