functions/New-DbaXESmartEmail.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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
function New-DbaXESmartEmail {
    <#
        .SYNOPSIS
            This Response type can be used to send an email each time an event is captured.
 
        .DESCRIPTION
            This Response type can be used to send an email each time an event is captured.
 
        .PARAMETER SmtpServer
            Address of the SMTP server for outgoing mail.
 
        .PARAMETER Sender
            Sender's email address.
 
        .PARAMETER To
            Address of the To recipient(s).
 
        .PARAMETER Cc
            Address of the Cc recipient(s).
 
        .PARAMETER Bcc
            Address of the Bcc recipient(s).
 
        .PARAMETER Credential
            Credential object containing username and password used to authenticate on the SMTP server. When blank, no authentication is performed.
 
        .PARAMETER Subject
            Subject of the mail message. Accepts placeholders in the text.
 
            Placeholders are in the form {PropertyName}, where PropertyName is one of the fields or actions available in the Event object.
 
            For instance, a valid Subject in a configuration file looks like this: "An event of name {Name} occurred at {collection_time}"
 
        .PARAMETER Body
            Body of the mail message. The body can be static text or any property taken from the underlying event. See Subject for a description of how placeholders work.
 
        .PARAMETER Attachment
            Data to attach to the email message. At this time, it can be any of the fields/actions of the underlying event. The data from the field/action is attached to the message as an ASCII stream. A single attachment is supported.
 
        .PARAMETER AttachmentFileName
            File name to assign to the attachment.
 
        .PARAMETER PlainText
            If this switch is enabled, the email will be sent in plain text. By default, HTML formatting is used.
 
        .PARAMETER Event
            Each Response can be limited to processing specific events, while ignoring all the other ones. When this attribute is omitted, all events are processed.
 
        .PARAMETER Filter
            You can specify a filter expression by using this attribute. The filter expression is in the same form that you would use in a SQL query. For example, a valid example looks like this: duration > 10000 AND cpu_time > 10000
 
        .PARAMETER EnableException
            By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
            This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
            Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.
 
        .NOTES
            Tags: ExtendedEvent, XE, Xevent
            Website: https://dbatools.io
            Copyright: (C) Chrissy LeMaire, clemaire@gmail.com
            License: MIT https://opensource.org/licenses/MIT
            SmartTarget: by Gianluca Sartori (@spaghettidba)
 
        .LINK
            https://dbatools.io/New-DbaXESmartEmail
            https://github.com/spaghettidba/XESmartTarget/wiki
 
        .EXAMPLE
            $params = @{
                SmtpServer = "smtp.ad.local"
                To = "admin@ad.local"
                Sender = "reports@ad.local"
                Subject = "Query executed"
                Body = "Query executed at {collection_time}"
                Attachment = "batch_text"
                AttachmentFileName = "query.sql"
            }
            $emailresponse = New-DbaXESmartEmail @params
            Start-DbaXESmartTarget -SqlInstance sql2017 -Session querytracker -Responder $emailresponse
 
            Sends an email each time a querytracker event is captured.
    #>

    [CmdletBinding()]
    param (
        [parameter(Mandatory)]
        [string]$SmtpServer,
        [parameter(Mandatory)]
        [string]$Sender,
        [parameter(Mandatory)]
        [string[]]$To,
        [string[]]$Cc,
        [string[]]$Bcc,
        [pscredential]$Credential,
        [parameter(Mandatory)]
        [string]$Subject,
        [parameter(Mandatory)]
        [string]$Body,
        [string]$Attachment,
        [string]$AttachmentFileName,
        [string]$PlainText,
        [string[]]$Event,
        [string]$Filter,
        [switch]$EnableException
    )
    begin {
        try {
            Add-Type -Path "$script:PSModuleRoot\bin\XESmartTarget\XESmartTarget.Core.dll" -ErrorAction Stop
        }
        catch {
            Stop-Function -Message "Could not load XESmartTarget.Core.dll." -ErrorRecord $_ -Target "XESmartTarget"
            return
        }
    }
    process {
        if (Test-FunctionInterrupt) { return }

        try {
            $email = New-Object -TypeName XESmartTarget.Core.Responses.EmailResponse
            $email.SmtpServer = $SmtpServer
            $email.Sender = $Sender
            $email.To = $To
            $email.Cc = $Cc
            $email.Bcc = $Bcc
            $email.Subject = $Subject
            $email.Body = $Body
            $email.Attachment = $Attachment
            $email.AttachmentFileName = $AttachmentFileName
            $email.HTMLFormat = ($PlainText -eq $false)
            if (Test-Bound -ParameterName "Event") {
                $email.Events = $Event
            }
            if (Test-Bound -ParameterName "Filter") {
                $email.Filter = $Filter
            }

            if ($Credential) {
                $email.UserName = $Credential.UserName
                $email.Password = $Credential.GetNetworkCredential().Password
            }

            $email
        }
        catch {
            Stop-Function -Message "Failure" -ErrorRecord $_ -Target "XESmartTarget" -Continue
        }
    }
}