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
149
150
151
152
153
154
155
156
157
158
#ValidationTags#Messaging,FlowControl,Pipeline,CodeStyle#
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 WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .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
        Author: Chrissy LeMaire (@cl) | SmartTarget by Gianluca Sartori (@spaghettidba)
 
        Website: https://dbatools.io
        Copyright: (c) 2018 by dbatools, licensed under MIT
        License: MIT https://opensource.org/licenses/MIT
 
    .LINK
        https://dbatools.io/New-DbaXESmartEmail
 
    .EXAMPLE
        PS C:\> $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"
        >> }
        >>
        PS C:\> $emailresponse = New-DbaXESmartEmail @params
        PS C:\> Start-DbaXESmartTarget -SqlInstance sql2017 -Session querytracker -Responder $emailresponse
 
        Sends an email each time a querytracker event is captured.
 
#>

    [CmdletBinding(SupportsShouldProcess)]
    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 }

        if ($Pscmdlet.ShouldProcess("Creating new XESmartEmail Object")) {
            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
            }
        }
    }
}