From 10233fe0caa2f5f4d8837176eebad7f2c0c4a653 Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Tue, 12 May 2020 09:51:18 +0200 Subject: [PATCH] SqlServerDsc: Deprecating SqlServerNetwork (#1544) --- CHANGELOG.md | 12 +- README.md | 8 + build.yaml | 6 + codecov.yml | 4 + .../MSFT_SqlServerNetwork.psm1 | 399 ++++++++++++++++++ .../MSFT_SqlServerNetwork.schema.mof | 12 + .../en-US/MSFT_SqlServerNetwork.strings.psd1 | 12 + 7 files changed, 449 insertions(+), 4 deletions(-) create mode 100644 source/DSCResources/MSFT_SqlServerNetwork/MSFT_SqlServerNetwork.psm1 create mode 100644 source/DSCResources/MSFT_SqlServerNetwork/MSFT_SqlServerNetwork.schema.mof create mode 100644 source/DSCResources/MSFT_SqlServerNetwork/en-US/MSFT_SqlServerNetwork.strings.psd1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 26ad040e9..7828704b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,11 +5,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -### Removed +### Deprecated -- SqlServerDsc - - BREAKING CHANGE: Removed resource _SqlServerNetwork_. The functionality - is now covered by the resources _SqlServerProtocol_ and _SqlServerProtocolTcpIp_. +The documentation, examples, unit test, and integration tests have been +removed for these deprecated resources. + +- SqlServerNetwork + - This resource is now deprecated. The functionality is now covered by + the resources _SqlServerProtocol_ and _SqlServerProtocolTcpIp_. ### Added @@ -38,6 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - SqlServerDsc - Changed all resource prefixes from `MSFT_` to `DSC_` ([issue #1496](https://github.com/dsccommunity/SqlServerDsc/issues/1496)). + _Deprecated resource has not changed prefix._ - All resources are now using the common module DscResource.Common. - When a PR is labelled with 'ready for merge' it is no longer being marked as stale if the PR is not merged for 30 days (for example it is diff --git a/README.md b/README.md index 1fcc85f98..0f5b8a49e 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,14 @@ for some general use scenarios for all of the resources that are in the module. A full list of changes in each version can be found in the [change log](CHANGELOG.md). +### Deprecated resources + +The documentation, examples, unit test, and integration tests have been removed +for these deprecated resources. + +* SqlServerNetwork _(replaced by [**SqlServerProtocol**](#sqlserverprotocol) and_ + _[**SqlServerProtocolTcpIp**](#sqlserverprotocoltcpip))_. + ## Resources * [**SqlAG**](#sqlag) diff --git a/build.yaml b/build.yaml index f8ad993e8..ed78604c0 100644 --- a/build.yaml +++ b/build.yaml @@ -59,6 +59,8 @@ Pester: OutputFormat: NUnitXML ExcludeFromCodeCoverage: - Modules/DscResource.Common + # Deprecated resources + - source/DSCResources/MSFT_SqlServerNetwork Script: - tests/Unit ExcludeTag: @@ -73,8 +75,12 @@ DscTest: Tag: ExcludeSourceFile: - output + # Deprecated resources + - source/DSCResources/MSFT_SqlServerNetwork ExcludeModuleFile: - Modules/DscResource.Common + # Deprecated resources + - DSCResources/MSFT_SqlServerNetwork Resolve-Dependency: Gallery: 'PSGallery' diff --git a/codecov.yml b/codecov.yml index 7cc2cb6d7..33363e7ad 100644 --- a/codecov.yml +++ b/codecov.yml @@ -26,3 +26,7 @@ coverage: fixes: - '\d+\.\d+\.\d+\/::source/' # move path "X.Y.Z/" => "source/" + +# Deprecated resources +ignore: + - 'source/DSCResources/MSFT_SqlServerNetwork' diff --git a/source/DSCResources/MSFT_SqlServerNetwork/MSFT_SqlServerNetwork.psm1 b/source/DSCResources/MSFT_SqlServerNetwork/MSFT_SqlServerNetwork.psm1 new file mode 100644 index 000000000..7cfb301b5 --- /dev/null +++ b/source/DSCResources/MSFT_SqlServerNetwork/MSFT_SqlServerNetwork.psm1 @@ -0,0 +1,399 @@ +<# + DEPRECATION NOTICE: + + THIS RESOURCE IS DEPRECATED! + + Changes to this resource will no longer be merged. Instead please use the + resources SqlServerProtocol and SqlServerProtocolTcpIp. +#> +$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 network properties. + + .PARAMETER InstanceName + The name of the SQL instance to be configured. + + .PARAMETER ProtocolName + The name of network protocol to be configured. Only tcp is currently supported. +#> +function Get-TargetResource +{ + [CmdletBinding()] + [OutputType([System.Collections.Hashtable])] + param + ( + [Parameter(Mandatory = $true)] + [System.String] + $InstanceName, + + # For now there is only support for the tcp protocol. + [Parameter(Mandatory = $true)] + [ValidateSet('Tcp')] + [System.String] + $ProtocolName + ) + + Import-SQLPSModule + + $managedComputerObject = New-Object -TypeName Microsoft.SqlServer.Management.Smo.Wmi.ManagedComputer + + Write-Verbose -Message ($script:localizedData.GetNetworkProtocol -f $ProtocolName, $InstanceName) + $tcp = $managedComputerObject.ServerInstances[$InstanceName].ServerProtocols[$ProtocolName] + + Write-Verbose -Message $script:localizedData.ReadingNetworkProperties + $returnValue = @{ + InstanceName = $InstanceName + ProtocolName = $ProtocolName + IsEnabled = $tcp.IsEnabled + TcpDynamicPort = ($tcp.IPAddresses['IPAll'].IPAddressProperties['TcpDynamicPorts'].Value -ge 0) + TcpPort = $tcp.IPAddresses['IPAll'].IPAddressProperties['TcpPort'].Value + } + + $returnValue.Keys | ForEach-Object { + Write-Verbose -Message "$_ = $($returnValue[$_])" + } + + return $returnValue +} + +<# + .SYNOPSIS + Sets the SQL Server network properties. + + .PARAMETER ServerName + The host name of the SQL Server to be configured. Default value is $env:COMPUTERNAME. + + .PARAMETER InstanceName + The name of the SQL instance to be configured. + + .PARAMETER ProtocolName + The name of network protocol to be configured. Only tcp is currently supported. + + .PARAMETER IsEnabled + Enables or disables the network protocol. + + .PARAMETER TcpDynamicPort + Specifies whether the SQL Server instance should use a dynamic port. + Value cannot be set to $true if TcpPort is set to a non-empty string. + + .PARAMETER TcpPort + The TCP port(s) that SQL Server should be listening on. + If the IP address should listen on more than one port, list all ports + separated with a comma ('1433,1500,1501'). To use this parameter set + TcpDynamicPort to 'False'. + + .PARAMETER RestartService + If set to $true then SQL Server and dependent services will be restarted + if a change to the configuration is made. The default value is $false. + + .PARAMETER RestartTimeout + Timeout value for restarting the SQL Server services. The default value + is 120 seconds. +#> +function Set-TargetResource +{ + [CmdletBinding()] + param + ( + [Parameter()] + [ValidateNotNullOrEmpty()] + [System.String] + $ServerName = $env:COMPUTERNAME, + + [Parameter(Mandatory = $true)] + [System.String] + $InstanceName, + + [Parameter(Mandatory = $true)] + [ValidateSet('Tcp')] + [System.String] + $ProtocolName, + + [Parameter()] + [System.Boolean] + $IsEnabled, + + [Parameter()] + [System.Boolean] + $TcpDynamicPort, + + [Parameter()] + [System.String] + $TcpPort, + + [Parameter()] + [System.Boolean] + $RestartService = $false, + + [Parameter()] + [System.UInt16] + $RestartTimeout = 120 + ) + + if ($TcpDynamicPort -and $TcpPort) + { + $errorMessage = $script:localizedData.ErrorDynamicAndStaticPortSpecified + New-InvalidOperationException -Message $errorMessage + } + + $getTargetResourceResult = Get-TargetResource -InstanceName $InstanceName -ProtocolName $ProtocolName + + $desiredState = @{ + InstanceName = $InstanceName + ProtocolName = $ProtocolName + IsEnabled = $IsEnabled + TcpDynamicPort = $TcpDynamicPort + TcpPort = $TcpPort + } + + $isRestartNeeded = $false + + # Get-TargetResource makes the necessary calls so the type ManagedComputer is available. + $managedComputerObject = New-Object -TypeName Microsoft.SqlServer.Management.Smo.Wmi.ManagedComputer + + Write-Verbose -Message ($script:localizedData.GetNetworkProtocol -f $ProtocolName, $InstanceName) + $tcp = $managedComputerObject.ServerInstances[$InstanceName].ServerProtocols[$ProtocolName] + + Write-Verbose -Message ($script:localizedData.CheckingProperty -f 'IsEnabled') + if ($desiredState.IsEnabled -ine $getTargetResourceResult.IsEnabled) + { + Write-Verbose -Message ($script:localizedData.UpdatingProperty -f 'IsEnabled', $getTargetResourceResult.IsEnabled, $desiredState.IsEnabled) + $tcp.IsEnabled = $desiredState.IsEnabled + $tcp.Alter() + + $isRestartNeeded = $true + } + + Write-Verbose -Message ($script:localizedData.CheckingProperty -f 'TcpDynamicPort') + if ($desiredState.TcpDynamicPort -ne $getTargetResourceResult.TcpDynamicPort) + { + # Translates the current and desired state to a string for display + $dynamicPortDisplayValueTable = @{ + $true = 'enabled' + $false = 'disabled' + } + + # Translates the desired state to a valid value + $desiredDynamicPortValue = @{ + $true = '0' + $false = '' + } + + $fromTcpDynamicPortDisplayValue = $dynamicPortDisplayValueTable[$getTargetResourceResult.TcpDynamicPort] + $toTcpDynamicPortDisplayValue = $dynamicPortDisplayValueTable[$desiredState.TcpDynamicPort] + + Write-Verbose -Message ($script:localizedData.UpdatingProperty -f 'TcpDynamicPorts', $fromTcpDynamicPortDisplayValue, $toTcpDynamicPortDisplayValue) + $tcp.IPAddresses['IPAll'].IPAddressProperties['TcpDynamicPorts'].Value = $desiredDynamicPortValue[$desiredState.TcpDynamicPort] + $tcp.Alter() + + $isRestartNeeded = $true + } + + Write-Verbose -Message ($script:localizedData.CheckingProperty -f 'TcpPort') + if ($desiredState.TcpPort -ine $getTargetResourceResult.TcpPort) + { + $fromTcpPort = $getTargetResourceResult.TcpPort + if ($fromTcpPort -eq '') + { + $fromTcpPort = 'none' + } + + $toTcpPort = $desiredState.TcpPort + if ($toTcpPort -eq '') + { + $toTcpPort = 'none' + } + + Write-Verbose -Message ($script:localizedData.UpdatingProperty -f 'TcpPort', $fromTcpPort, $toTcpPort) + $tcp.IPAddresses['IPAll'].IPAddressProperties['TcpPort'].Value = $desiredState.TcpPort + $tcp.Alter() + + $isRestartNeeded = $true + } + + if ($RestartService -and $isRestartNeeded) + { + $restartSqlServiceParameters = @{ + ServerName = $ServerName + InstanceName = $InstanceName + Timeout = $RestartTimeout + } + + if ($getTargetResourceResult.IsEnabled -eq $false -and $IsEnabled -eq $true) + { + <# + If the protocol was disabled and now being enabled, is not possible + to connect to the instance to evaluate if it is a clustered instance. + This is being tracked in issue #1174. + #> + $restartSqlServiceParameters['SkipClusterCheck'] = $true + } + + if ($PSBoundParameters.ContainsKey('IsEnabled') -and $IsEnabled -eq $false) + { + # If the protocol is disabled it is not possible to connect to the instance. + $restartSqlServiceParameters['SkipWaitForOnline'] = $true + } + + Restart-SqlService @restartSqlServiceParameters + } +} + +<# + .SYNOPSIS + Sets the SQL Server network properties. + + .PARAMETER ServerName + The host name of the SQL Server to be configured. Default value is $env:COMPUTERNAME. + + Not used in Test-TargetResource. + + .PARAMETER InstanceName + The name of the SQL instance to be configured. + + .PARAMETER ProtocolName + The name of network protocol to be configured. Only tcp is currently supported. + + .PARAMETER IsEnabled + Enables or disables the network protocol. + + .PARAMETER TcpDynamicPort + Specifies whether the SQL Server instance should use a dynamic port. + Value cannot be set to $true if TcpPort is set to a non-empty string. + + .PARAMETER TcpPort + The TCP port(s) that SQL Server should be listening on. + If the IP address should listen on more than one port, list all ports + separated with a comma ('1433,1500,1501'). To use this parameter set + TcpDynamicPort to 'False'. + + .PARAMETER RestartService + If set to $true then SQL Server and dependent services will be restarted + if a change to the configuration is made. The default value is $false. + + Not used in Test-TargetResource. + + .PARAMETER RestartTimeout + Timeout value for restarting the SQL Server services. The default value + is 120 seconds. + + Not used in Test-TargetResource. +#> +function Test-TargetResource +{ + [CmdletBinding()] + [OutputType([System.Boolean])] + param + ( + [Parameter()] + [ValidateNotNullOrEmpty()] + [System.String] + $ServerName = $env:COMPUTERNAME, + + [Parameter(Mandatory = $true)] + [System.String] + $InstanceName, + + [Parameter(Mandatory = $true)] + [ValidateSet('Tcp')] + [System.String] + $ProtocolName, + + [Parameter()] + [System.Boolean] + $IsEnabled, + + [Parameter()] + [System.Boolean] + $TcpDynamicPort, + + [Parameter()] + [System.String] + $TcpPort, + + [Parameter()] + [System.Boolean] + $RestartService = $false, + + [Parameter()] + [System.UInt16] + $RestartTimeout = 120 + ) + + if ($TcpDynamicPort -and $TcpPort) + { + $errorMessage = $script:localizedData.ErrorDynamicAndStaticPortSpecified + New-InvalidOperationException -Message $errorMessage + } + + $getTargetResourceResult = Get-TargetResource -InstanceName $InstanceName -ProtocolName $ProtocolName + + Write-Verbose -Message $script:localizedData.CompareStates + + $isInDesiredState = $true + + if ($ProtocolName -ne $getTargetResourceResult.ProtocolName) + { + Write-Verbose -Message ($script:localizedData.ExpectedPropertyValue -f 'ProtocolName', $ProtocolName, $getTargetResourceResult.ProtocolName) + + $isInDesiredState = $false + } + + if ($PSBoundParameters.ContainsKey('IsEnabled')) + { + if ($IsEnabled -ne $getTargetResourceResult.IsEnabled) + { + $evaluateEnableOrDisable = @{ + $true = 'enabled' + $false = 'disabled' + } + + Write-Verbose -Message ($script:localizedData.ExpectedPropertyValue -f 'IsEnabled', $evaluateEnableOrDisable[$IsEnabled], $evaluateEnableOrDisable[$getTargetResourceResult.IsEnabled]) + + $isInDesiredState = $false + } + } + + if ($PSBoundParameters.ContainsKey('TcpDynamicPort')) + { + if ($TcpDynamicPort -and $getTargetResourceResult.TcpDynamicPort -eq $false) + { + Write-Verbose -Message ($script:localizedData.ExpectedPropertyValue -f 'TcpDynamicPort', $TcpDynamicPort, $getTargetResourceResult.TcpDynamicPort) + + $isInDesiredState = $false + } + } + + if ($PSBoundParameters.ContainsKey('TcpPort')) + { + if ($getTargetResourceResult.TcpPort -eq '') + { + Write-Verbose -Message ($script:localizedData.ExpectedPropertyValue -f 'TcpPort', $TcpPort, $getTargetResourceResult.TcpPort) + + $isInDesiredState = $false + } + elseif ($TcpPort -ne $getTargetResourceResult.TcpPort) + { + Write-Verbose -Message ($script:localizedData.ExpectedPropertyValue -f 'TcpPort', $TcpPort, $getTargetResourceResult.TcpPort) + + $isInDesiredState = $false + } + } + + if ($isInDesiredState) + { + Write-Verbose -Message ($script:localizedData.InDesiredState) + } + + return $isInDesiredState +} + +Export-ModuleMember -Function *-TargetResource diff --git a/source/DSCResources/MSFT_SqlServerNetwork/MSFT_SqlServerNetwork.schema.mof b/source/DSCResources/MSFT_SqlServerNetwork/MSFT_SqlServerNetwork.schema.mof new file mode 100644 index 000000000..1ce38653c --- /dev/null +++ b/source/DSCResources/MSFT_SqlServerNetwork/MSFT_SqlServerNetwork.schema.mof @@ -0,0 +1,12 @@ +[ClassVersion("1.0.0.0"), FriendlyName("SqlServerNetwork")] +class MSFT_SqlServerNetwork : OMI_BaseResource +{ + [Key, Description("The name of the SQL instance to be configured.")] String InstanceName; + [Required, Description("The name of network protocol to be configured. Only tcp is currently supported."), ValueMap{"Tcp"}, Values{"Tcp"}] String ProtocolName; + [Write, Description("The host name of the SQL Server to be configured. Default value is $env:COMPUTERNAME.")] String ServerName; + [Write, Description("Enables or disables the network protocol.")] Boolean IsEnabled; + [Write, Description("Specifies whether the SQL Server instance should use a dynamic port. Value cannot be set to 'True' if TcpPort is set to a non-empty string.")] Boolean TcpDynamicPort; + [Write, Description("The TCP port(s) that SQL Server should be listening on. If the IP address should listen on more than one port, list all ports separated with a comma ('1433,1500,1501'). To use this parameter set TcpDynamicPorts to 'False'.")] String TcpPort; + [Write, Description("If set to $true then SQL Server and dependent services will be restarted if a change to the configuration is made. The default value is $false.")] Boolean RestartService; + [Write, Description("Timeout value for restarting the SQL Server services. The default value is 120 seconds.")] UInt16 RestartTimeout; +}; diff --git a/source/DSCResources/MSFT_SqlServerNetwork/en-US/MSFT_SqlServerNetwork.strings.psd1 b/source/DSCResources/MSFT_SqlServerNetwork/en-US/MSFT_SqlServerNetwork.strings.psd1 new file mode 100644 index 000000000..c6269473b --- /dev/null +++ b/source/DSCResources/MSFT_SqlServerNetwork/en-US/MSFT_SqlServerNetwork.strings.psd1 @@ -0,0 +1,12 @@ +# Localized resources for SqlServerNetwork + +ConvertFrom-StringData @' + GetNetworkProtocol = THIS RESOURCE IS DEPRECATED! Getting network protocol [{0}] for SQL instance [{1}]. + ReadingNetworkProperties = Reading current network properties. + CheckingProperty = Checking [{0}] property. + UpdatingProperty = Updating property [{0}] from [{1}] to [{2}]. + ExpectedPropertyValue = Expected property [{0}] value to be [{1}] but was [{2}]. + CompareStates = Comparing desired state with current state. + InDesiredState = System is in the desired state. + ErrorDynamicAndStaticPortSpecified = Unable to set both tcp dynamic port and tcp static port. Only one can be set. +'@