SqlServerProtocolTcpIp: New resource proposal (#1517)

- SqlServerDsc - Added new resource SqlServerProtocolTcpIp (issue #1378). - Changed to use the property `NuGetVersionV2` from GitVersion in the CI pipeline.
dsccommunity · May 5, 2020 · 83760fe · 83760fe
1 parent fab9419
commit 83760fe
Show file tree

Hide file tree

Showing 20 changed files with 2,609 additions and 197 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@ For older change log history see the [historic changelog](HISTORIC_CHANGELOG.md)
 
 - SqlServerDsc
   - Added new resource SqlServerProtocol ([issue #1377](https://github.com/dsccommunity/SqlServerDsc/issues/1377)).
+  - Added new resource SqlServerProtocolTcpIp ([issue #1378](https://github.com/dsccommunity/SqlServerDsc/issues/1378)).
 - SqlSetup
   - A read only property `IsClustered` was added that can be used to determine
     if the instance is clustered.
@@ -33,6 +34,8 @@ For older change log history see the [historic changelog](HISTORIC_CHANGELOG.md)
     marked as stale if the PR is not merged for 30 days (for example it is
     dependent on something else) ([issue #1504](https://github.com/dsccommunity/SqlServerDsc/issues/1504)).
   - Updated the CI pipeline to use latest version of the module ModuleBuilder.
+  - Changed to use the property `NuGetVersionV2` from GitVersion in the
+    CI pipeline.
 - SqlAlwaysOnService
   - BREAKING CHANGE: The parameter `ServerName` is now non-mandatory and
     defaults to `$env:COMPUTERNAME` ([issue #319](https://github.com/dsccommunity/SqlServerDsc/issues/319)).

diff --git a/README.md b/README.md
@@ -123,6 +123,8 @@ A full list of changes in each version can be found in the [change log](CHANGELO
   the SQL Server.
 * [**SqlServerProtocol**](#sqlserverprotocol) resource manage the SQL Server
   protocols for a SQL Server instance.
+* [**SqlServerProtocolTcpIp**](#sqlserverprotocoltcpip) resource manage the TCP/IP
+  protocol IP address groups for a SQL Server instance.
 * [**SqlServerReplication**](#sqlserverreplication) resource to manage SQL Replication
   distribution and publishing.
 * [**SqlServerRole**](#sqlserverrole) resource to manage SQL server roles.
@@ -1693,7 +1695,7 @@ for a SQL Server instance.
 * **`[UInt16]` KeepAlive** _(Write)_: Specifies the keep alive duration
   in milliseconds. Only used for the TCP/IP protocol, ignored for all other
   protocols.
-* **`[String` PipeName** _(Write)_: Specifies the name of the named pipe.
+* **`[String]` PipeName** _(Write)_: Specifies the name of the named pipe.
   Only used for the Named Pipes protocol, ignored for all other protocols.
 * **`[Boolean]` SuppressRestart** _(Write)_: If set to $true then the any
   attempt by the resource to restart the service is suppressed. The default
@@ -1719,6 +1721,73 @@ for a SQL Server instance.
 
 All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlServerProtocol).
 
+### SqlServerProtocolTcpIp
+
+The `SqlServerProtocolTcpIp` DSC resource manage the TCP/IP protocol IP
+address groups for a SQL Server instance.
+
+#### Requirements
+
+* Target machine must be running Windows Server 2012 or later.
+* Target machine must be running SQL Server Database Engine 2012 or later.
+* Target machine must have access to the SQLPS PowerShell module or the SqlServer
+  PowerShell module.
+* To configure a single IP address to listen on multiple ports, the
+  TcpIp protocol must also set the **Listen All** property to **No**.
+  This can be done with the resource `SqlServerProtocol` using the
+  parameter `ListenOnAllIpAddresses`.
+
+#### Parameters
+
+* **`[String]` InstanceName** _(Key)_: Specifies the name of the SQL Server
+  instance to enable the protocol for.
+* **`[String]` IpAddressGroup** _(Key)_: Specifies the name of the IP address
+  group in the TCP/IP protocol, e.g. 'IP1', 'IP2' etc., or 'IPAll'.
+* **`[String]` ServerName** _(Write)_: 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 `$env:COMPUTERNAME`.
+* **`[Boolean]` Enabled** _(Write)_: Specified if the IP address group  should
+  be enabled or disabled. Only used if the IP address group is not set to
+  'IPAll'. If not specified, the existing value will not be changed.
+* **`[String]` IpAddress** _(Write)_: Specifies the IP address for the IP
+  adress group. Only used if the IP address group is not set to 'IPAll'. If
+  not specified, the existing value will not be changed.
+* **`[Boolean]` UseTcpDynamicPort** _(Write)_: Specifies whether the SQL Server
+  instance should use a dynamic port. If not specified, the existing value
+  will not be changed. This parameter is not allowed to be used at the same
+  time as the parameter TcpPort.
+* **`[String]` TcpPort** _(Write)_: Specifies 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 as a string value with the port numbers separated with a comma,
+  e.g. '1433,1500,1501'. This parameter is limited to 2047 characters. If not
+  specified, the existing value will not be changed. This parameter is not
+  allowed to be used at the same time as the parameter UseTcpDynamicPort.
+* **`[Boolean]` SuppressRestart** _(Write)_: If set to $true then the any
+  attempt by the resource to restart the service is suppressed. The default
+  value is $false.
+* **`[UInt16]` RestartTimeout** _(Write)_: Timeout value for restarting
+  the SQL Server services. The default value is 120 seconds.
+
+#### Read-Only Properties from Get-TargetResource
+
+* **`[Boolean]` IsActive** _(Read)_: Returns $true or $false whether the
+  IP address group is active. Not applicable for IP address group 'IPAll'.
+* **`[String]` AddressFamily** _(Read)_: Returns the IP address's adress
+  family. Not applicable for IP address group 'IPAll'.
+* **`[String]` TcpDynamicPort** _(Read)_: Returns the TCP/IP dynamic port.
+  Only applicable for the IP address group 'IPAll'.
+
+#### Examples
+
+* [Configure the IP address group IPAll with dynamic port](/source/Examples/Resources/SqlServerProtocolTcpIp/1-ConfigureIPAddressGroupIPAllWithDynamicPort.ps1)
+* [Configure the IP address group IPAll with static port(s)](/source/Examples/Resources/SqlServerProtocolTcpIp/2-ConfigureIPAddressGroupIPAllWithStaticPort.ps1)
+* [Configure the IP address group IP1 with IP address and static port(s)](/source/Examples/Resources/SqlServerProtocolTcpIp/3-ConfigureIPAddressGroupIP1.ps1)
+
+#### Known issues
+
+All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlServerProtocolTcpIp).
+
 ### SqlServerReplication
 
 This resource manage SQL Replication distribution and publishing.

diff --git a/azure-pipelines.yml b/azure-pipelines.yml
@@ -38,7 +38,7 @@ stages:
               arguments: '-ResolveDependency -tasks pack'
               pwsh: true
             env:
-              ModuleVersion: $(gitVersion.InformationalVersion)
+              ModuleVersion: $(gitVersion.NuGetVersionV2)
           - task: PublishBuildArtifacts@1
             displayName: 'Publish Build Artifact'
             inputs:
@@ -164,6 +164,8 @@ stages:
                   'tests/Integration/DSC_SqlServerSecureConnection.Integration.Tests.ps1'
                   'tests/Integration/DSC_SqlScriptQuery.Integration.Tests.ps1'
                   'tests/Integration/DSC_SqlServerProtocol.Integration.Tests.ps1'
+                  # Group 6 (tests makes changes that could make SQL Server to loose connectivity)
+                  'tests/Integration/DSC_SqlServerProtocolTcpIp.Integration.Tests.ps1'
               )
             name: test
             displayName: 'Run Integration Test'
@@ -228,6 +230,8 @@ stages:
                   'tests/Integration/DSC_SqlServerSecureConnection.Integration.Tests.ps1'
                   'tests/Integration/DSC_SqlScriptQuery.Integration.Tests.ps1'
                   'tests/Integration/DSC_SqlServerProtocol.Integration.Tests.ps1'
+                  # Group 6 (tests makes changes that could make SQL Server to loose connectivity)
+                  'tests/Integration/DSC_SqlServerProtocolTcpIp.Integration.Tests.ps1'
               )
             name: test
             displayName: 'Run Integration Test'

diff --git a/source/DSCResources/DSC_SqlServerProtocol/DSC_SqlServerProtocol.psm1 b/source/DSCResources/DSC_SqlServerProtocol/DSC_SqlServerProtocol.psm1
@@ -660,116 +660,3 @@ function Compare-TargetResourceState
 
     return Compare-ResourcePropertyState @compareTargetResourceStateParameters
 }
-
-<#
-    .SYNOPSIS
-        Get static name properties of he specified protocol.
-
-    .PARAMETER ProtocolName
-        Specifies the name of network protocol to return name properties for.
-        Possible values are 'TcpIp', 'NamedPipes', or 'ShareMemory'.
-
-    .NOTES
-        The static values returned matches the values returned by the class
-        ServerProtocol. The property DisplayName could potentially be localized
-        while the property Name must be exactly like it is returned by the
-        class ServerProtocol, with the correct casing.
-
-#>
-function Get-ProtocolNameProperties
-{
-    [CmdletBinding()]
-    [OutputType([System.Collections.Hashtable])]
-    param
-    (
-        [Parameter(Mandatory = $true)]
-        [ValidateSet('TcpIp', 'NamedPipes', 'SharedMemory')]
-        [System.String]
-        $ProtocolName
-    )
-
-    $protocolNameProperties = @{ }
-
-    switch ($ProtocolName)
-    {
-        'TcpIp'
-        {
-            $protocolNameProperties.DisplayName = 'TCP/IP'
-            $protocolNameProperties.Name = 'Tcp'
-        }
-
-        'NamedPipes'
-        {
-            $protocolNameProperties.DisplayName = 'Named Pipes'
-            $protocolNameProperties.Name = 'Np'
-        }
-
-        'SharedMemory'
-        {
-            $protocolNameProperties.DisplayName = 'Shared Memory'
-            $protocolNameProperties.Name = 'Sm'
-        }
-    }
-
-    return $protocolNameProperties
-}
-
-<#
-    .SYNOPSIS
-        Returns the ServerProtocol object for the specified SQL Server instance
-        and protocol name.
-
-    .PARAMETER InstanceName
-        Specifies the name of the SQL Server instance to connect to.
-
-    .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 connect to.
-
-    .NOTES
-        The class Microsoft.SqlServer.Management.Smo.Wmi.ServerProtocol is
-        returned by this function.
-#>
-function Get-ServerProtocolObject
-{
-    [CmdletBinding()]
-    param
-    (
-        [Parameter(Mandatory = $true)]
-        [System.String]
-        $InstanceName,
-
-        [Parameter(Mandatory = $true)]
-        [ValidateSet('TcpIp', 'NamedPipes', 'SharedMemory')]
-        [System.String]
-        $ProtocolName,
-
-        [Parameter(Mandatory = $true)]
-        [ValidateNotNullOrEmpty()]
-        [System.String]
-        $ServerName
-    )
-
-    $serverProtocolProperties = $null
-
-    $newObjectParameters = @{
-        TypeName     = 'Microsoft.SqlServer.Management.Smo.Wmi.ManagedComputer'
-        ArgumentList = @($ServerName)
-    }
-
-    $managedComputerObject = New-Object @newObjectParameters
-
-    $serverInstance = $managedComputerObject.ServerInstances[$InstanceName]
-
-    if ($serverInstance)
-    {
-        $protocolNameProperties = Get-ProtocolNameProperties -ProtocolName $ProtocolName
-
-        $serverProtocolProperties = $serverInstance.ServerProtocols[$protocolNameProperties.Name]
-    }
-
-    return $serverProtocolProperties
-}
diff --git a/source/DSCResources/DSC_SqlServerProtocol/README.md b/source/DSCResources/DSC_SqlServerProtocol/README.md
@@ -3,6 +3,12 @@
 The `SqlServerProtocol` DSC resource manage the SQL Server protocols
 for a SQL Server instance.
 
+For more information about protocol properties look at the following articles:
+
+* [TCP/IP Properties (Protocols Tab)](https://docs.microsoft.com/en-us/sql/tools/configuration-manager/tcp-ip-properties-protocols-tab).
+* [Shared Memory Properties](https://docs.microsoft.com/en-us/sql/tools/configuration-manager/shared-memory-properties).
+* [Named Pipes Properties](https://docs.microsoft.com/en-us/sql/tools/configuration-manager/named-pipes-properties).
+
 ## Requirements
 
 * Target machine must be running Windows Server 2012 or later.