SqlServerBase: Support connection protocol and port

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added public command `Get-SqlDscServerProtocolTcpIp` to retrieve TCP/IP address
+  group information for SQL Server instances. Returns `ServerIPAddress` objects
+  containing port configuration including `TcpPort`, `TcpDynamicPorts`, `Enabled`,
+  and `Active` properties. Supports filtering by specific IP address group name
+  and accepts pipeline input from `Get-SqlDscServerProtocol`.
+- `SqlResourceBase`
+  - Added `Protocol` property to specify the network protocol (`tcp`, `np`, `lpc`)
+    when connecting to SQL Server instances
+    ([issue #2041](https://github.com/dsccommunity/SqlServerDsc/issues/2041)).
+  - Added `Port` property to specify the TCP port number when connecting to SQL
+    Server instances
+    ([issue #2041](https://github.com/dsccommunity/SqlServerDsc/issues/2041)).
+- `Connect-SqlDscDatabaseEngine`
+  - Added `Protocol` parameter to specify the network protocol when connecting.
+  - Added `Port` parameter to specify the TCP port number when connecting.
+    Connection strings now support the format `[protocol:]hostname[\instance][,port]`.
 - `Install-SqlDscServer`
   - Added parameter `AllowDqRemoval` to the `Upgrade` parameter set
     ([issue #2155](https://github.com/dsccommunity/SqlServerDsc/issues/2155)).

azure-pipelines.yml

@@ -321,6 +321,7 @@ stages:
                   'tests/Integration/Commands/Get-SqlDscServerProtocolName.Integration.Tests.ps1'
                   'tests/Integration/Commands/ConvertTo-SqlDscEditionName.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscServerProtocol.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Get-SqlDscServerProtocolTcpIp.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscTraceFlag.Integration.Tests.ps1'
                   'tests/Integration/Commands/Disable-SqlDscLogin.Integration.Tests.ps1'
                   'tests/Integration/Commands/Enable-SqlDscLogin.Integration.Tests.ps1'

source/Classes/011.SqlResourceBase.ps1

@@ -17,8 +17,29 @@
         If parameter **Credential'* is not provided then the resource instance is
         run using the credential that runs the configuration.
 
+    .PARAMETER Protocol
+        Specifies the network protocol to use when connecting to the _SQL Server_
+        instance. Valid values are `'tcp'` for TCP/IP, `'np'` for Named Pipes,
+        and `'lpc'` for Shared Memory.
+
+        If not specified, the connection will use the default protocol order
+        configured on the client.
+
+    .PARAMETER Port
+        Specifies the TCP port number to use when connecting to the _SQL Server_
+        instance. This parameter is only applicable when connecting via TCP/IP.
+
+        If not specified for a named instance, the SQL Server Browser service
+        will be used to determine the port. For default instances, port 1433
+        is used by default.
+
     .PARAMETER Reasons
         Returns the reason a property is not in desired state.
+
+    .NOTES
+        The protocol values (`'tcp'`, `'np'`, `'lpc'`) are lowercase to match
+        the SQL Server connection string prefix format, e.g.,
+        `tcp:ServerName\Instance,Port`.
 #>
 class SqlResourceBase : ResourceBase
 {
@@ -42,6 +63,15 @@ class SqlResourceBase : ResourceBase
     [PSCredential]
     $Credential
 
+    [DscProperty()]
+    [ValidateSet('tcp', 'np', 'lpc')]
+    [System.String]
+    $Protocol
+
+    [DscProperty()]
+    [Nullable[System.UInt16]]
+    $Port
+
     [DscProperty(NotConfigurable)]
     [SqlReason[]]
     $Reasons
@@ -50,6 +80,18 @@ class SqlResourceBase : ResourceBase
     SqlResourceBase () : base ($PSScriptRoot)
     {
         $this.SqlServerObject = $null
+
+        <#
+            These connection properties will not be enforced. Child classes
+            should use += to append their own properties to this list.
+        #>
+        $this.ExcludeDscProperties = @(
+            'ServerName'
+            'InstanceName'
+            'Credential'
+            'Protocol'
+            'Port'
+        )
     }
 
     <#
@@ -75,6 +117,16 @@ class SqlResourceBase : ResourceBase
                 $connectSqlDscDatabaseEngineParameters.Credential = $this.Credential
             }
 
+            if ($this.Protocol)
+            {
+                $connectSqlDscDatabaseEngineParameters.Protocol = $this.Protocol
+            }
+
+            if ($this.Port)
+            {
+                $connectSqlDscDatabaseEngineParameters.Port = $this.Port
+            }
+
             $this.SqlServerObject = Connect-SqlDscDatabaseEngine @connectSqlDscDatabaseEngineParameters
         }
 

source/Classes/020.SqlAgentAlert.ps1

@@ -140,11 +140,8 @@ class SqlAgentAlert : SqlResourceBase
 
     SqlAgentAlert () : base ()
     {
-        # Property names that cannot be enforced
-        $this.ExcludeDscProperties = @(
-            'InstanceName',
-            'ServerName',
-            'Credential',
+        # Append to the properties set in SqlResourceBase that will not be enforced.
+        $this.ExcludeDscProperties += @(
             'Name'
         )
     }

source/Classes/020.SqlAudit.ps1

@@ -191,12 +191,9 @@ class SqlAudit : SqlResourceBase
 
     SqlAudit () : base ()
     {
-        # These properties will not be enforced.
-        $this.ExcludeDscProperties = @(
-            'ServerName'
-            'InstanceName'
+        # Append to the properties set in SqlResourceBase that will not be enforced.
+        $this.ExcludeDscProperties += @(
             'Name'
-            'Credential'
             'Force'
         )
     }

source/Classes/020.SqlDatabasePermission.ps1

@@ -163,13 +163,10 @@ class SqlDatabasePermission : SqlResourceBase
 
     SqlDatabasePermission() : base ()
     {
-        # These properties will not be enforced.
-        $this.ExcludeDscProperties = @(
-            'ServerName'
-            'InstanceName'
+        # Append to the properties set in SqlResourceBase that will not be enforced.
+        $this.ExcludeDscProperties += @(
             'DatabaseName'
             'Name'
-            'Credential'
         )
     }
 

source/Classes/020.SqlPermission.ps1

@@ -164,12 +164,9 @@ class SqlPermission : SqlResourceBase
 
     SqlPermission() : base ()
     {
-        # These properties will not be enforced.
-        $this.ExcludeDscProperties = @(
-            'ServerName'
-            'InstanceName'
+        # Append to the properties set in SqlResourceBase that will not be enforced.
+        $this.ExcludeDscProperties += @(
             'Name'
-            'Credential'
         )
     }
 

source/Modules/SqlServerDsc.Common/SqlServerDsc.Common.psm1

@@ -368,6 +368,15 @@ function Connect-SQL
         [System.String]
         $LoginType = 'WindowsUser',
 
+        [Parameter()]
+        [ValidateSet('tcp', 'np', 'lpc')]
+        [System.String]
+        $Protocol,
+
+        [Parameter()]
+        [System.UInt16]
+        $Port,
+
         [Parameter()]
         [ValidateNotNull()]
         [System.Int32]
@@ -380,6 +389,18 @@ function Connect-SQL
 
     Import-SqlDscPreferredModule
 
+    <#
+        Build the connection string in the format: [protocol:]hostname[\instance][,port]
+        Examples:
+        - ServerName (default instance, no protocol/port)
+        - ServerName\Instance (named instance)
+        - tcp:ServerName (default instance with protocol)
+        - tcp:ServerName\Instance (named instance with protocol)
+        - ServerName,1433 (default instance with port)
+        - ServerName\Instance,50200 (named instance with port)
+        - tcp:ServerName,1433 (default instance with protocol and port)
+        - tcp:ServerName\Instance,50200 (named instance with protocol and port)
+    #>
     if ($InstanceName -eq 'MSSQLSERVER')
     {
         $databaseEngineInstance = $ServerName
@@ -389,6 +410,18 @@ function Connect-SQL
         $databaseEngineInstance = '{0}\{1}' -f $ServerName, $InstanceName
     }
 
+    # Append port if specified
+    if ($PSBoundParameters.ContainsKey('Port'))
+    {
+        $databaseEngineInstance = '{0},{1}' -f $databaseEngineInstance, $Port
+    }
+
+    # Prepend protocol if specified
+    if ($PSBoundParameters.ContainsKey('Protocol'))
+    {
+        $databaseEngineInstance = '{0}:{1}' -f $Protocol, $databaseEngineInstance
+    }
+
     $sqlServerObject = New-Object -TypeName 'Microsoft.SqlServer.Management.Smo.Server'
     $sqlConnectionContext = $sqlServerObject.ConnectionContext
     $sqlConnectionContext.ServerInstance = $databaseEngineInstance

source/Public/Connect-SqlDscDatabaseEngine.ps1

@@ -28,6 +28,22 @@
         If set to 'SqlLogin' then it will impersonate using the native SQL
         login specified in the parameter Credential.
 
+    .PARAMETER Protocol
+        Specifies the network protocol to use when connecting to the SQL Server
+        instance. Valid values are 'tcp' for TCP/IP, 'np' for Named Pipes,
+        and 'lpc' for Shared Memory.
+
+        If not specified, the connection will use the default protocol order
+        configured on the client.
+
+    .PARAMETER Port
+        Specifies the TCP port number to use when connecting to the SQL Server
+        instance. This parameter is only applicable when connecting via TCP/IP.
+
+        If not specified for a named instance, the SQL Server Browser service
+        will be used to determine the port. For default instances, port 1433
+        is used by default.
+
     .PARAMETER StatementTimeout
         Set the query StatementTimeout in seconds. Default 600 seconds (10 minutes).
 
@@ -59,13 +75,29 @@
 
         Connects to the default instance on the local server using the SQL login 'sa'.
 
+    .EXAMPLE
+        Connect-SqlDscDatabaseEngine -ServerName '192.168.1.1' -InstanceName 'MyInstance' -Protocol 'tcp' -Port 50200
+
+        Connects to the named instance 'MyInstance' on server '192.168.1.1' using
+        TCP/IP on port 50200. The connection string format is 'tcp:192.168.1.1\MyInstance,50200'.
+
+    .EXAMPLE
+        Connect-SqlDscDatabaseEngine -ServerName '192.168.1.1' -Protocol 'tcp' -Port 1433
+
+        Connects to the default instance on server '192.168.1.1' using TCP/IP on
+        port 1433. The connection string format is 'tcp:192.168.1.1,1433'.
+
     .INPUTS
         None.
 
     .OUTPUTS
         `Microsoft.SqlServer.Management.Smo.Server`
 
         Returns the SQL Server server object.
+
+    .NOTES
+        The protocol values ('tcp', 'np', 'lpc') are lowercase to match the SQL
+        Server connection string prefix format, e.g., 'tcp:ServerName\Instance,Port'.
 #>
 function Connect-SqlDscDatabaseEngine
 {
@@ -97,6 +129,15 @@ function Connect-SqlDscDatabaseEngine
         [System.String]
         $LoginType = 'WindowsUser',
 
+        [Parameter()]
+        [ValidateSet('tcp', 'np', 'lpc')]
+        [System.String]
+        $Protocol,
+
+        [Parameter()]
+        [System.UInt16]
+        $Port,
+
         [Parameter()]
         [ValidateNotNull()]
         [System.Int32]