DSCResources/DSC_SqlProtocol/DSC_SqlProtocol.psm1

$script:sqlServerDscHelperModulePath = Join-Path -Path $PSScriptRoot -ChildPath '..\..\Modules\SqlServerDsc.Common'
$script:resourceHelperModulePath = Join-Path -Path $PSScriptRoot -ChildPath '..\..\Modules\DscResource.Common'

Import-Module -Name $script:sqlServerDscHelperModulePath
Import-Module -Name $script:resourceHelperModulePath

$script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'

<#
    .SYNOPSIS
        Returns the current state of the SQL Server protocol for the specified
        SQL Server instance.
 
    .PARAMETER InstanceName
        Specifies the name of the SQL Server instance to enable the protocol for.
 
    .PARAMETER ProtocolName
        Specifies the name of network protocol to be configured. Possible values
        are 'TcpIp', 'NamedPipes', or 'ShareMemory'.
 
    .PARAMETER ServerName
        Specifies the host name of the SQL Server to be configured. If the SQL
        Server belongs to a cluster or availability group specify the host name
        for the listener or cluster group. Default value is the current computer
        name.
 
    .PARAMETER SuppressRestart
        If set to $true then the any attempt by the resource to restart the service
        is suppressed. The default value is $false.
 
    .PARAMETER RestartTimeout
        Timeout value for restarting the SQL Server services. The default value
        is 120 seconds.
 
    .NOTES
        The parameters SuppressRestart and RestartTimeout are part of the function
        Get-TargetResource to be able to return the value that the configuration
        have set, or the default values if not. If they weren't passed to the
        function Get-TargetResource we would have to always return $null which
        would indicate that they are not set at all.
#>

function Get-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $InstanceName,

        [Parameter(Mandatory = $true)]
        [ValidateSet('TcpIp', 'NamedPipes', 'SharedMemory')]
        [System.String]
        $ProtocolName,

        [Parameter()]
        [System.String]
        $ServerName = (Get-ComputerName),

        [Parameter()]
        [System.Boolean]
        $SuppressRestart = $false,

        [Parameter()]
        [System.UInt16]
        $RestartTimeout = 120
    )

    $returnValue = @{
        InstanceName           = $InstanceName
        ProtocolName           = $ProtocolName
        ServerName             = $ServerName
        SuppressRestart        = $SuppressRestart
        RestartTimeout         = $RestartTimeout
        Enabled                = $false
        ListenOnAllIpAddresses = $false
        KeepAlive              = 0
        PipeName               = $null
        HasMultiIPAddresses    = $false
    }

    $protocolNameProperties = Get-ProtocolNameProperties -ProtocolName $ProtocolName

    # Getting the server protocol properties by using the computer name.
    $computerName = Get-ComputerName

    Write-Verbose -Message (
        $script:localizedData.GetCurrentState -f $protocolNameProperties.DisplayName, $InstanceName, $computerName
    )

    Import-SqlDscPreferredModule

    <#
        Must connect to the local machine name because $ServerName can point
        to a cluster instance or availability group listener.
    #>

    $getServerProtocolObjectParameters = @{
        ServerName   = $computerName
        Instance     = $InstanceName
        ProtocolName = $ProtocolName
    }

    $serverProtocolProperties = Get-ServerProtocolObject @getServerProtocolObjectParameters

    if ($serverProtocolProperties)
    {
        # Properties that exist on all protocols.
        $returnValue.Enabled = $serverProtocolProperties.IsEnabled
        $returnValue.HasMultiIPAddresses = $serverProtocolProperties.HasMultiIPAddresses

        # Get individual protocol properties.
        switch ($ProtocolName)
        {
            'TcpIp'
            {
                $returnValue.ListenOnAllIpAddresses = $serverProtocolProperties.ProtocolProperties['ListenOnAllIPs'].Value
                $returnValue.KeepAlive = $serverProtocolProperties.ProtocolProperties['KeepAlive'].Value
            }

            'NamedPipes'
            {
                $returnValue.PipeName = $serverProtocolProperties.ProtocolProperties['PipeName'].Value
            }

            'SharedMemory'
            {
                <#
                    Left blank intentionally. There are no individual protocol
                    properties for the protocol Shared Memory.
                #>

            }
        }
    }

    return $returnValue
}

<#
    .SYNOPSIS
        Sets the desired state of the SQL Server protocol for the specified
        SQL Server instance.
 
    .PARAMETER InstanceName
        Specifies the name of the SQL Server instance to enable the protocol for.
 
    .PARAMETER ProtocolName
        Specifies the name of network protocol to be configured. Possible values
        are 'TcpIp', 'NamedPipes', or 'ShareMemory'.
 
    .PARAMETER ServerName
        Specifies the host name of the SQL Server to be configured. If the SQL
        Server belongs to a cluster or availability group specify the host name
        for the listener or cluster group. Default value is the current computer
        name.
 
    .PARAMETER Enabled
        Specifies if the protocol should be enabled or disabled.
 
    .PARAMETER ListenOnAllIpAddresses
        Specifies to listen on all IP addresses. Only used for the TCP/IP protocol,
        ignored for all other protocols.
 
    .PARAMETER KeepAlive
        Specifies the keep alive duration. Only used for the TCP/IP protocol,
        ignored for all other protocols.
 
    .PARAMETER PipeName
        Specifies the name of the named pipe. Only used for the Named Pipes protocol,
        ignored for all other protocols.
 
    .PARAMETER SuppressRestart
        If set to $true then the any attempt by the resource to restart the service
        is suppressed. The default value is $false.
 
    .PARAMETER RestartTimeout
        Timeout value for restarting the SQL Server services. The default value
        is 120 seconds.
 
    .NOTES
        If a protocol is disabled that prevents Restart-SqlService to contact the
        instance to evaluate if it is a cluster then the parameter `SuppressRestart`
        must be used to override the restart. Same if a protocol is enabled that
        was previously disabled and no other protocol allows connecting to the
        instance then the parameter `SuppressRestart` must also be used.
#>

function Set-TargetResource
{
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('SqlServerDsc.AnalyzerRules\Measure-CommandsNeededToLoadSMO', '', Justification='The command Import-SqlDscPreferredModule is implicitly called when calling Compare-TargetResourceState')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $InstanceName,

        [Parameter(Mandatory = $true)]
        [ValidateSet('TcpIp', 'NamedPipes', 'SharedMemory')]
        [System.String]
        $ProtocolName,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $ServerName = (Get-ComputerName),

        [Parameter()]
        [System.Boolean]
        $Enabled,

        [Parameter()]
        [System.Boolean]
        $ListenOnAllIpAddresses,

        [Parameter()]
        [System.Int32]
        $KeepAlive,

        [Parameter()]
        [System.String]
        $PipeName,

        [Parameter()]
        [System.Boolean]
        $SuppressRestart = $false,

        [Parameter()]
        [System.UInt16]
        $RestartTimeout = 120
    )

    $protocolNameProperties = Get-ProtocolNameProperties -ProtocolName $ProtocolName

    <#
        Compare the current state against the desired state. Calling this will
        also import the necessary module to later call Get-ServerProtocolObject
        which uses the SMO class ManagedComputer.
    #>

    $propertyState = Compare-TargetResourceState @PSBoundParameters

    # Get all properties that are not in desired state.
    $propertiesNotInDesiredState = $propertyState.Where( { -not $_.InDesiredState })

    if ($propertiesNotInDesiredState.Count -gt 0)
    {
        # Getting the server protocol properties by using the computer name.
        $computerName = Get-ComputerName

        Write-Verbose -Message (
            $script:localizedData.SetDesiredState -f $protocolNameProperties.DisplayName, $InstanceName, $computerName
        )

        <#
            Must connect to the local machine name because $ServerName can point
            to a cluster instance or availability group listener.
        #>

        $getServerProtocolObjectParameters = @{
            ServerName   = $computerName
            Instance     = $InstanceName
            ProtocolName = $ProtocolName
        }

        $serverProtocolProperties = Get-ServerProtocolObject @getServerProtocolObjectParameters

        if ($serverProtocolProperties)
        {
            $isRestartNeeded = $false

            # Check if Enable property need updating.
            if ($propertiesNotInDesiredState.Where( { $_.ParameterName -eq 'Enabled' }))
            {
                $serverProtocolProperties.IsEnabled = $Enabled

                if ($Enabled)
                {
                    Write-Verbose -Message (
                        $script:localizedData.ProtocolHasBeenEnabled -f $protocolNameProperties.DisplayName, $InstanceName
                    )
                }
                else
                {
                    Write-Verbose -Message (
                        $script:localizedData.ProtocolHasBeenDisabled -f $protocolNameProperties.DisplayName, $InstanceName
                    )
                }

                $isRestartNeeded = $true
            }

            # Set individual protocol properties.
            switch ($ProtocolName)
            {
                'TcpIp'
                {
                    # Check if ListenOnAllIpAddresses property need updating.
                    if ($propertiesNotInDesiredState.Where( { $_.ParameterName -eq 'ListenOnAllIpAddresses' }))
                    {
                        Write-Verbose -Message (
                            $script:localizedData.ParameterHasBeenSetToNewValue -f 'ListenOnAllIpAddresses', $protocolNameProperties.DisplayName, $ListenOnAllIpAddresses
                        )

                        $serverProtocolProperties.ProtocolProperties['ListenOnAllIPs'].Value = $ListenOnAllIpAddresses
                    }

                    # Check if KeepAlive property need updating.
                    if ($propertiesNotInDesiredState.Where( { $_.ParameterName -eq 'KeepAlive' }))
                    {
                        Write-Verbose -Message (
                            $script:localizedData.ParameterHasBeenSetToNewValue -f 'KeepAlive', $protocolNameProperties.DisplayName, $KeepAlive
                        )

                        $serverProtocolProperties.ProtocolProperties['KeepAlive'].Value = $KeepAlive
                    }
                }

                'NamedPipes'
                {
                    # Check if PipeName property need updating.
                    if ($propertiesNotInDesiredState.Where( { $_.ParameterName -eq 'PipeName' }))
                    {
                        Write-Verbose -Message (
                            $script:localizedData.ParameterHasBeenSetToNewValue -f 'PipeName', $protocolNameProperties.DisplayName, $PipeName
                        )

                        $serverProtocolProperties.ProtocolProperties['PipeName'].Value = $PipeName
                    }
                }

                'SharedMemory'
                {
                    <#
                        Left blank intentionally. There are no individual protocol
                        properties for the protocol Shared Memory.
                    #>

                }
            }

            $serverProtocolProperties.Alter()
        }
        else
        {
            $errorMessage = $script:localizedData.FailedToGetSqlServerProtocol

            New-InvalidOperationException -Message $errorMessage
        }

        if (-not $SuppressRestart -and $isRestartNeeded)
        {
            <#
                This is using the $ServerName to be able to restart a cluster
                instance or availability group listener.
            #>

            $restartSqlServiceParameters = @{
                ServerName   = $ServerName
                InstanceName = $InstanceName
                Timeout      = $RestartTimeout
                OwnerNode    = Get-ComputerName
            }

            Restart-SqlService @restartSqlServiceParameters
        }
        elseif ($isRestartNeeded)
        {
            Write-Warning -Message $script:localizedData.RestartSuppressed
        }
    }
    else
    {
        Write-Verbose -Message (
            $script:localizedData.ProtocolIsInDesiredState -f $protocolNameProperties.DisplayName, $InstanceName
        )
    }
}

<#
    .SYNOPSIS
        Determines the current state of the SQL Server protocol for the specified
        SQL Server instance.
 
    .PARAMETER InstanceName
        Specifies the name of the SQL Server instance to enable the protocol for.
 
    .PARAMETER ProtocolName
        Specifies the name of network protocol to be configured. Possible values
        are 'TcpIp', 'NamedPipes', or 'ShareMemory'.
 
    .PARAMETER ServerName
        Specifies the host name of the SQL Server to be configured. If the SQL
        Server belongs to a cluster or availability group specify the host name
        for the listener or cluster group. Default value is the current computer
        name.
 
    .PARAMETER Enabled
        Specifies if the protocol should be enabled or disabled.
 
    .PARAMETER ListenOnAllIpAddresses
        Specifies to listen on all IP addresses. Only used for the TCP/IP protocol,
        ignored for all other protocols.
 
    .PARAMETER KeepAlive
        Specifies the keep alive duration. Only used for the TCP/IP protocol,
        ignored for all other protocols.
 
    .PARAMETER PipeName
        Specifies the name of the named pipe. Only used for the Named Pipes protocol,
        ignored for all other protocols.
 
    .PARAMETER SuppressRestart
        If set to $true then the any attempt by the resource to restart the service
        is suppressed. The default value is $false.
 
    .PARAMETER RestartTimeout
        Timeout value for restarting the SQL Server services. The default value
        is 120 seconds.
#>

function Test-TargetResource
{
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('SqlServerDsc.AnalyzerRules\Measure-CommandsNeededToLoadSMO', '', Justification='The command Import-SqlDscPreferredModule is implicitly called when calling Compare-TargetResourceState')]
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $InstanceName,

        [Parameter(Mandatory = $true)]
        [ValidateSet('TcpIp', 'NamedPipes', 'SharedMemory')]
        [System.String]
        $ProtocolName,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $ServerName = (Get-ComputerName),

        [Parameter()]
        [System.Boolean]
        $Enabled,

        [Parameter()]
        [System.Boolean]
        $ListenOnAllIpAddresses,

        [Parameter()]
        [System.Int32]
        $KeepAlive,

        [Parameter()]
        [System.String]
        $PipeName,

        [Parameter()]
        [System.Boolean]
        $SuppressRestart = $false,

        [Parameter()]
        [System.UInt16]
        $RestartTimeout = 120
    )

    $protocolNameProperties = Get-ProtocolNameProperties -ProtocolName $ProtocolName

    Write-Verbose -Message (
        $script:localizedData.TestDesiredState -f $protocolNameProperties.DisplayName, $InstanceName, $ServerName
    )

    $propertyState = Compare-TargetResourceState @PSBoundParameters


    if ($false -in $propertyState.InDesiredState)
    {
        $testTargetResourceReturnValue = $false

        Write-Verbose -Message (
            $script:localizedData.NotInDesiredState -f $protocolNameProperties.DisplayName, $InstanceName
        )
    }
    else
    {
        $testTargetResourceReturnValue = $true

        Write-Verbose -Message (
            $script:localizedData.InDesiredState -f $protocolNameProperties.DisplayName, $InstanceName
        )
    }

    return $testTargetResourceReturnValue
}

<#
    .SYNOPSIS
        Compares the properties in the current state with the properties of the
        desired state and returns a hashtable with the comparison result.
 
    .PARAMETER InstanceName
        Specifies the name of the SQL Server instance to enable the protocol for.
 
    .PARAMETER ProtocolName
        Specifies the name of network protocol to be configured. Possible values
        are 'TcpIp', 'NamedPipes', or 'ShareMemory'.
 
    .PARAMETER ServerName
        Specifies the host name of the SQL Server to be configured. Default value
        is the current computer name.
 
    .PARAMETER Enabled
        Specifies if the protocol should be enabled or disabled.
 
    .PARAMETER ListenOnAllIpAddresses
        Specifies to listen on all IP addresses. Only used for the TCP/IP protocol,
        ignored for all other protocols.
 
    .PARAMETER KeepAlive
        Specifies the keep alive duration. Only used for the TCP/IP protocol,
        ignored for all other protocols.
 
    .PARAMETER PipeName
        Specifies the name of the named pipe. Only used for the Named Pipes protocol,
        ignored for all other protocols.
 
    .PARAMETER SuppressRestart
        If set to $true then the any attempt by the resource to restart the service
        is suppressed. The default value is $false.
 
    .PARAMETER RestartTimeout
        Timeout value for restarting the SQL Server services. The default value
        is 120 seconds.
#>

function Compare-TargetResourceState
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $InstanceName,

        [Parameter(Mandatory = $true)]
        [ValidateSet('TcpIp', 'NamedPipes', 'SharedMemory')]
        [System.String]
        $ProtocolName,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $ServerName = (Get-ComputerName),

        [Parameter()]
        [System.Boolean]
        $Enabled,

        [Parameter()]
        [System.Boolean]
        $ListenOnAllIpAddresses,

        [Parameter()]
        [System.Int32]
        $KeepAlive,

        [Parameter()]
        [System.String]
        $PipeName,

        [Parameter()]
        [System.Boolean]
        $SuppressRestart,

        [Parameter()]
        [System.UInt16]
        $RestartTimeout
    )

    if ($ProtocolName -eq 'SharedMemory')
    {
        <#
            If the protocol is Shared Memory, assert that no other individual
            protocol properties are passed.
        #>

        $assertBoundParameterParameters = @{
            BoundParameterList     = $PSBoundParameters
            <#
                Since SharedMemory does not have any individual properties this
                mandatory property is being used to compare against.
            #>

            MutuallyExclusiveList1 = @(
                'ProtocolName'
            )
            # These must not be passed for Shared Memory.
            MutuallyExclusiveList2 = @(
                'KeepAlive'
                'ListenOnAllIpAddresses'
                'PipeName'
            )
        }
    }
    else
    {
        <#
            If the protocol is set to TCP/IP or Named Pipes, assert that one or
            more of their individual protocol properties are not passed together.
        #>

        $assertBoundParameterParameters = @{
            BoundParameterList     = $PSBoundParameters
            # Individual properties for TCP/IP.
            MutuallyExclusiveList1 = @(
                'KeepAlive'
                'ListenOnAllIpAddresses'
            )
            # Individual properties for Named Pipes.
            MutuallyExclusiveList2 = @(
                'PipeName'
            )
        }
    }

    Assert-BoundParameter @assertBoundParameterParameters

    $getTargetResourceParameters = @{
        InstanceName    = $InstanceName
        ProtocolName    = $ProtocolName
        ServerName      = $ServerName
        SuppressRestart = $SuppressRestart
        RestartTimeout  = $RestartTimeout
    }

    <#
        We remove any parameters not passed by $PSBoundParameters so that
        Get-TargetResource can also evaluate $PSBoundParameters correctly.
 
        Need the @() around the Keys property to get a new array to enumerate.
    #>

    @($getTargetResourceParameters.Keys) | ForEach-Object -Process {
        if (-not $PSBoundParameters.ContainsKey($_))
        {
            $getTargetResourceParameters.Remove($_)
        }
    }

    $getTargetResourceResult = Get-TargetResource @getTargetResourceParameters

    $propertiesToEvaluate = @(
        'Enabled'
    )

    # Get individual protocol properties to evaluate.
    switch ($ProtocolName)
    {
        'TcpIp'
        {
            $propertiesToEvaluate += 'ListenOnAllIpAddresses'
            $propertiesToEvaluate += 'KeepAlive'
        }

        'NamedPipes'
        {
            $propertiesToEvaluate += 'PipeName'
        }

        'SharedMemory'
        {
            <#
                Left blank intentionally. There are no individual protocol
                properties for the protocol Shared Memory.
            #>

        }
    }

    $compareTargetResourceStateParameters = @{
        CurrentValues = $getTargetResourceResult
        DesiredValues = $PSBoundParameters
        Properties    = $propertiesToEvaluate
    }

    return Compare-ResourcePropertyState @compareTargetResourceStateParameters
}