MSFT_SqlAgentOperator: Added resource for SQL Server Agent Operators

CHANGELOG.md

@@ -50,6 +50,7 @@
     used for the creation of the endpoint
     ([issue #1251](https://github.com/PowerShell/SqlServerDsc/issues/1251)).
     [Maxime Daniou (@mdaniou)](https://github.com/mdaniou)
+- Added SqlAgentOperator Resource
 
 ## 12.2.0.0
 

DSCResources/MSFT_SqlAgentOperator/MSFT_SqlAgentOperator.psm1

@@ -0,0 +1,332 @@
+Import-Module -Name (Join-Path -Path (Split-Path (Split-Path $PSScriptRoot -Parent) -Parent) `
+        -ChildPath 'SqlServerDscHelper.psm1') `
+    -Force
+
+Import-Module -Name (Join-Path -Path (Split-Path -Path $PSScriptRoot -Parent) `
+    -ChildPath 'CommonResourceHelper.psm1')
+
+$script:localizedData = Get-LocalizedData -ResourceName 'MSFT_SqlAgentOperator'
+
+<#
+    .SYNOPSIS
+    This function gets the SQL Agent Operator.
+
+    .PARAMETER Name
+    The name of the SQL Agent Operator.
+
+    .PARAMETER ServerName
+    The host name of the SQL Server to be configured. Default is $env:COMPUTERNAME.
+
+    .PARAMETER InstanceName
+    The name of the SQL instance to be configured.
+
+#>
+function Get-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [System.String]
+        $ServerName = $env:COMPUTERNAME,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $InstanceName
+
+    )
+
+    $returnValue = @{
+        Name         = $null
+        Ensure       = 'Absent'
+        ServerName   = $ServerName
+        InstanceName = $InstanceName
+        EmailAddress = $null
+    }
+
+    $sqlServerObject = Connect-SQL -ServerName $ServerName -InstanceName $InstanceName
+
+    if ($sqlServerObject)
+    {
+        Write-Verbose -Message (
+            $script:localizedData.GetSqlAgents
+        )
+        # Check operator exists
+        $sqlOperatorObject = $sqlServerObject.JobServer.Operators | Where-Object {$_.Name -eq $Name}
+        if ($sqlOperatorObject)
+        {
+            Write-Verbose -Message (
+                $script:localizedData.SqlAgentPresent `
+                    -f $Name
+            )
+            $returnValue['Ensure'] = 'Present'
+            $returnValue['Name'] = $sqlOperatorObject.Name
+            $returnValue['EmailAddress'] = $sqlOperatorObject.EmailAddress
+        }
+        else
+        {
+            Write-Verbose -Message (
+                $script:localizedData.SqlAgentAbsent `
+                    -f $Name
+            )
+        }
+    }
+    else
+    {
+
+        $errorMessage = $script:localizedData.ConnectServerFailed -f $ServerName, $InstanceName
+        New-InvalidOperationException -Message $errorMessage -ErrorRecord $_
+    }
+
+    return $returnValue
+}
+
+<#
+    .SYNOPSIS
+    This function sets the SQL Agent Operator.
+
+    .PARAMETER Ensure
+    Specifies if the SQL Agent Operator should be present or absent. Default is Present
+
+    .PARAMETER Name
+    The name of the SQL Agent Operator.
+
+    .PARAMETER ServerName
+    The host name of the SQL Server to be configured. Default is $env:COMPUTERNAME.
+
+    .PARAMETER InstanceName
+    The name of the SQL instance to be configured.
+
+    .PARAMETER EmailAddress
+    The email address to be used for the SQL Agent Operator.
+#>
+function Set-TargetResource
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter()]
+        [ValidateSet('Present', 'Absent')]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $Ensure = 'Present',
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [System.String]
+        $ServerName = $env:COMPUTERNAME,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $InstanceName,
+
+        [Parameter()]
+        [System.String]
+        $EmailAddress
+    )
+
+    $sqlServerObject = Connect-SQL -ServerName $ServerName -InstanceName $InstanceName
+
+    if ($sqlServerObject)
+    {
+        switch ($Ensure)
+        {
+            'Present'
+            {
+                $sqlOperatorObject = $sqlServerObject.JobServer.Operators | Where-Object {$_.Name -eq $Name}
+
+                if ($sqlOperatorObject)
+                {
+                    if ($PSBoundParameters.ContainsKey('EmailAddress'))
+                    {
+                        try
+                        {
+                            Write-Verbose -Message (
+                                $script:localizedData.UpdateEmailAddress `
+                                    -f $EmailAddress, $Name
+                            )
+                            $sqlOperatorObject.EmailAddress = $EmailAddress
+                            $sqlOperatorObject.Alter()
+                        }
+                        catch
+                        {
+                            $errorMessage = $script:localizedData.UpdateOperatorSetError -f $ServerName, $InstanceName, $Name, $EmailAddress
+                            New-InvalidOperationException -Message $errorMessage -ErrorRecord $_
+                        }
+                    }
+                }
+                else
+                {
+                    try
+                    {
+                        $sqlOperatorObjectToCreate = New-Object -TypeName Microsoft.SqlServer.Management.Smo.Agent.Operator -ArgumentList $sqlServerObject.JobServer, $Name
+
+                        if ($sqlOperatorObjectToCreate)
+                        {
+                            Write-Verbose -Message (
+                                $script:localizedData.AddSqlAgentOperator `
+                                    -f $Name
+                            )
+                            if ($PSBoundParameters.ContainsKey('EmailAddress'))
+                            {
+                                Write-Verbose -Message (
+                                    $script:localizedData.UpdateEmailAddress `
+                                        -f $EmailAddress, $Name
+                                )
+                                $sqlOperatorObjectToCreate.EmailAddress = $EmailAddress
+                            }
+                            $sqlOperatorObjectToCreate.Create()
+                        }
+                    }
+                    catch
+                    {
+                        $errorMessage = $script:localizedData.CreateOperatorSetError -f $Name, $ServerName, $InstanceName
+                        New-InvalidOperationException -Message $errorMessage -ErrorRecord $_
+                    }
+                }
+            }
+
+            'Absent'
+            {
+                try
+                {
+                    $sqlOperatorObjectToDrop = $sqlServerObject.JobServer.Operators | Where-Object {$_.Name -eq $Name}
+                    if ($sqlOperatorObjectToDrop)
+                    {
+                        Write-Verbose -Message (
+                            $script:localizedData.DeleteSqlAgentOperator `
+                                -f $Name
+                        )
+                        $sqlOperatorObjectToDrop.Drop()
+                    }
+                }
+                catch
+                {
+                    $errorMessage = $script:localizedData.DropOperatorSetError -f $Name, $ServerName, $InstanceName
+                    New-InvalidOperationException -Message $errorMessage -ErrorRecord $_
+                }
+            }
+        }
+    }
+    else
+    {
+        $errorMessage = $script:localizedData.ConnectServerFailed -f $ServerName, $InstanceName
+        New-InvalidOperationException -Message $errorMessage -ErrorRecord $_
+    }
+}
+
+<#
+    .SYNOPSIS
+    This function tests the SQL Agent Operator.
+
+    .PARAMETER Ensure
+    Specifies if the SQL Agent Operator should be present or absent. Default is Present
+
+    .PARAMETER Name
+    The name of the SQL Agent Operator.
+
+    .PARAMETER ServerName
+    The host name of the SQL Server to be configured. Default is $env:COMPUTERNAME.
+
+    .PARAMETER InstanceName
+    The name of the SQL instance to be configured.
+
+    .PARAMETER EmailAddress
+    The email address to be used for the SQL Agent Operator.
+#>
+function Test-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter()]
+        [ValidateSet('Present', 'Absent')]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $Ensure = 'Present',
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [System.String]
+        $ServerName = $env:COMPUTERNAME,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $InstanceName,
+
+        [Parameter()]
+        [System.String]
+        $EmailAddress
+    )
+
+    Write-Verbose -Message (
+        $script:localizedData.TestSqlAgentOperator `
+            -f $Name
+    )
+
+    $getTargetResourceParameters = @{
+        Name           = $Name
+        ServerName     = $ServerName
+        InstanceName   = $InstanceName
+    }
+
+    $getTargetResourceResult = Get-TargetResource @getTargetResourceParameters
+    $isOperatorInDesiredState = $true
+
+    switch ($Ensure)
+    {
+        'Absent'
+        {
+            if ($getTargetResourceResult.Ensure -ne 'Absent')
+            {
+                Write-Verbose -Message (
+                    $script:localizedData.SqlAgentOperatorExistsButShouldNot `
+                        -f $Name
+                )
+                $isOperatorInDesiredState = $false
+            }
+        }
+
+        'Present'
+        {
+            if ($getTargetResourceResult.EmailAddress -ne $EmailAddress -and $PSBoundParameters.ContainsKey('EmailAddress'))
+            {
+                Write-Verbose -Message (
+                    $script:localizedData.SqlAgentOperatorExistsButEmailWrong `
+                        -f $Name, $getTargetResourceResult.EmailAddress, $EmailAddress
+                )
+                $isOperatorInDesiredState = $false
+            }
+            elseif ($getTargetResourceResult.Ensure -ne 'Present')
+            {
+                Write-Verbose -Message (
+                    $script:localizedData.SqlAgentOperatorDoesNotExistButShould `
+                        -f $Name
+                )
+                $isOperatorInDesiredState = $false
+            }
+        }
+    }
+    $isOperatorInDesiredState
+}
+
+Export-ModuleMember -Function *-TargetResource

DSCResources/MSFT_SqlAgentOperator/MSFT_SqlAgentOperator.schema.mof

@@ -0,0 +1,9 @@
+[ClassVersion("1.0.0.0"), FriendlyName("SqlAgentOperator")]
+class MSFT_SqlAgentOperator : OMI_BaseResource
+{
+    [Key, Description("The name of the SQL Agent Operator.")] String Name;
+    [Write, Description("Specifies if the SQL Agent Operator should be present or absent. Default is Present."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
+    [Write, Description("The host name of the SQL Server to be configured. Default is $env:COMPUTERNAME.")] String ServerName;
+    [Key, Description("The name of the SQL instance to be configured.")] String InstanceName;
+    [Write, Description("The email address to be used for the SQL Agent Operator.")] String EmailAddress;
+};

DSCResources/MSFT_SqlAgentOperator/en-US/MSFT_SqlAgentOperator.strings.psd1

@@ -0,0 +1,18 @@
+# Localized resources for MSFT_SqlServerAgentOperator
+
+ConvertFrom-StringData @'
+    GetSqlAgents = Getting SQL Agent Operators.
+    SqlAgentPresent = SQL Agent Operator '{0}' is present.
+    SqlAgentAbsent = SQL Agent Operator '{0}' is absent.
+    UpdateOperatorSetError = Unable to update the email address for '{2}' to '{3}' on {0}\\{1}.
+    AddSqlAgentOperator = Adding SQL Agent Operator '{0}'.
+    UpdateEmailAddress = Updating email address to '{0}' for SQL Agent Operator '{1}'.
+    CreateOperatorSetError = Unable to create the SQL Agent Operator '{0}' on {1}\\{2}.
+    DeleteSqlAgentOperator = Deleting SQL Agent Operator '{0}'.
+    DropOperatorSetError = Unable to drop the SQL Agent Operator '{0}' on {1}\\{2}.
+    TestSqlAgentOperator = Checking if SQL Agent Operator '{0}' is present or absent.
+    SqlAgentOperatorExistsButShouldNot = SQL Agent Operator exists but ensure is set to Absent. The SQL Agent Operator '{0}' should be deleted.
+    SqlAgentOperatorDoesNotExistButShould  = SQL Agent Operator does not exist but Ensure is set to Present. The SQL Agent Operator '{0}' should be created.
+    SqlAgentOperatorExistsButEmailWrong  = SQL Agent Operator '{0}' exists but has the wrong email address. Email address is currently '{1}' and should be updated to '{2}'.
+    ConnectServerFailed = Unable to connect to {0}\\{1}.
+'@

Examples/README.md

@@ -9,6 +9,7 @@ These are the links to the examples for each individual resource.
 
 - [SqlAG](Resources/SqlAG)
 - [SqlAGDatabase](Resources/SqlAGDatabase)
+- [SqlAgentOperator](Resources/SqlAgentOperator)
 - [SqlAGListener](Resources/SqlAGListener)
 - [SqlAGReplica](Resources/SqlAGReplica)
 - [SqlAlias](Resources/SqlAlias)

Examples/Resources/SqlAgentOperator/1-AddOperator.ps1

@@ -0,0 +1,21 @@
+<#
+    .EXAMPLE
+        This example shows how to ensure that the SQL Agent Operator
+        DbaTeam exists with the correct email address.
+#>
+
+Configuration Example
+{
+
+    Import-DscResource -ModuleName SqlServerDsc
+
+    node localhost {
+        SqlAgentOperator Add_DbaTeam {
+            Ensure               = 'Present'
+            Name                 = 'DbaTeam'
+            ServerName           = 'TestServer'
+            InstanceName         = 'MSSQLServer'
+            EmailAddress         = '[email protected]'
+        }
+    }
+}