Add new public commands

.github/instructions/dsc-community-style-guidelines-powershell.instructions.md

@@ -82,7 +82,7 @@ applyTo: "**/*.ps?(m|d)1"
   - `$PSCmdlet.ShouldProcess` must use required pattern
   - Inside `$PSCmdlet.ShouldProcess`-block, avoid using `Write-Verbose`
 - Never use backtick as line continuation in production code.
-- Set `$ErrorActionPreference = 'Stop'` before commands using `-ErrorAction 'Stop'`; restore previous value after
+- Set `$ErrorActionPreference = 'Stop'` before commands using `-ErrorAction 'Stop'`; restore previous value directly after invocation (do not use try-catch-finally)
 
 ## Output streams
 

CHANGELOG.md

@@ -118,6 +118,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added private function `Get-CommandParameter` to filter command parameters
   by excluding specified parameter names and common parameters, providing a
   reusable way to determine settable properties on objects.
+- `Get-SqlDscServerProtocolName`
+  - New public command for SQL Server protocol name mappings with support
+    for protocol name, display name, and short name parameter sets.
+- `Get-SqlDscManagedComputerInstance`
+  - New public command for retrieving SQL Server managed computer instance
+    information with pipeline support.
+- `Get-SqlDscServerProtocol`
+  - Enhanced to support multiple parameter sets including pipeline input
+    from managed computer and instance objects.
+  - Enhanced to optionally return all protocols when ProtocolName parameter
+    is not specified.
 
 ### Changed
 

azure-pipelines.yml

@@ -296,6 +296,9 @@ stages:
                   'tests/Integration/Commands/Get-SqlDscConfigurationOption.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscConfigurationOption.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscConfigurationOption.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Get-SqlDscManagedComputerInstance.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Get-SqlDscServerProtocolName.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Get-SqlDscServerProtocol.Integration.Tests.ps1'
                   'tests/Integration/Commands/Disable-SqlDscLogin.Integration.Tests.ps1'
                   'tests/Integration/Commands/Enable-SqlDscLogin.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscIsLoginEnabled.Integration.Tests.ps1'

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

@@ -1980,6 +1980,9 @@ function Find-ExceptionByNumber
         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.
+
+        The Get-ProtocolNameProperties function is deprecated and should be removed
+        in the future when existing code has moved to new public commands.
 #>
 function Get-ProtocolNameProperties
 {

source/Public/Get-SqlDscManagedComputerInstance.ps1

@@ -0,0 +1,127 @@
+<#
+    .SYNOPSIS
+        Returns managed computer server instance information.
+
+    .DESCRIPTION
+        Returns managed computer server instance information for a SQL Server instance
+        using SMO (SQL Server Management Objects). The command can retrieve a specific
+        instance or all instances on a managed computer.
+
+    .PARAMETER ServerName
+        Specifies the name of the server where the SQL Server instance is running.
+        Defaults to the local computer name.
+
+    .PARAMETER InstanceName
+        Specifies the name of the SQL Server instance to retrieve.
+        If not specified, all instances are returned.
+
+    .PARAMETER ManagedComputerObject
+        Specifies a managed computer object from which to retrieve server instances.
+        This parameter accepts pipeline input from Get-SqlDscManagedComputer.
+
+    .EXAMPLE
+        Get-SqlDscManagedComputerInstance -InstanceName 'MSSQLSERVER'
+
+        Returns the default SQL Server instance information from the local computer.
+
+    .EXAMPLE
+        Get-SqlDscManagedComputerInstance -ServerName 'MyServer' -InstanceName 'MyInstance'
+
+        Returns the MyInstance SQL Server instance information from the MyServer computer.
+
+    .EXAMPLE
+        Get-SqlDscManagedComputerInstance -ServerName 'MyServer'
+
+        Returns all SQL Server instances information from the MyServer computer.
+
+    .EXAMPLE
+        Get-SqlDscManagedComputer -ServerName 'MyServer' | Get-SqlDscManagedComputerInstance -InstanceName 'MyInstance'
+
+        Uses pipeline input to retrieve a specific instance from a managed computer object.
+
+    .INPUTS
+        Microsoft.SqlServer.Management.Smo.Wmi.ManagedComputer
+
+        A managed computer object can be piped to this command.
+
+    .OUTPUTS
+        Microsoft.SqlServer.Management.Smo.Wmi.ServerInstance
+
+        Returns server instance objects from SMO (SQL Server Management Objects).
+
+    .NOTES
+        This command uses SMO (SQL Server Management Objects) to retrieve server
+        instance information from the specified managed computer.
+#>
+function Get-SqlDscManagedComputerInstance
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the rule does not yet support parsing the code when a parameter type is not available. The ScriptAnalyzer rule UseSyntacticallyCorrectExamples will always error in the editor due to https://github.com/indented-automation/Indented.ScriptAnalyzerRules/issues/8.')]
+    [CmdletBinding(DefaultParameterSetName = 'ByServerName')]
+    [OutputType([Microsoft.SqlServer.Management.Smo.Wmi.ServerInstance])]
+    param
+    (
+        [Parameter(ParameterSetName = 'ByServerName')]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $ServerName = (Get-ComputerName),
+
+        [Parameter(ParameterSetName = 'ByServerName')]
+        [Parameter(ParameterSetName = 'ByManagedComputerObject')]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $InstanceName,
+
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'ByManagedComputerObject')]
+        [Microsoft.SqlServer.Management.Smo.Wmi.ManagedComputer]
+        $ManagedComputerObject
+    )
+
+    process
+    {
+        if ($PSCmdlet.ParameterSetName -eq 'ByServerName')
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ManagedComputerInstance_GetFromServer -f $ServerName
+            )
+
+            $ManagedComputerObject = Get-SqlDscManagedComputer -ServerName $ServerName
+        }
+        else
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ManagedComputerInstance_GetFromObject
+            )
+        }
+
+        if ($PSBoundParameters.ContainsKey('InstanceName'))
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ManagedComputerInstance_GetSpecificInstance -f $InstanceName
+            )
+
+            $serverInstance = $ManagedComputerObject.ServerInstances[$InstanceName]
+
+            if (-not $serverInstance)
+            {
+                $errorMessage = $script:localizedData.ManagedComputerInstance_InstanceNotFound -f $InstanceName, $ManagedComputerObject.Name
+                $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+                    [System.InvalidOperationException]::new($errorMessage),
+                    'SqlServerInstanceNotFound',
+                    [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                    $InstanceName
+                )
+                $PSCmdlet.ThrowTerminatingError($errorRecord)
+            }
+
+            return $serverInstance
+        }
+        else
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ManagedComputerInstance_GetAllInstances
+            )
+
+            return $ManagedComputerObject.ServerInstances
+        }
+    }
+}

source/Public/Get-SqlDscServerProtocol.ps1

@@ -0,0 +1,202 @@
+<#
+    .SYNOPSIS
+        Returns server protocol information for a SQL Server instance.
+
+    .DESCRIPTION
+        Returns server protocol information for a SQL Server instance using
+        SMO (SQL Server Management Objects). The command supports getting
+        information for TcpIp, NamedPipes, and SharedMemory protocols.
+        If no protocol is specified, all protocols are returned.
+
+    .PARAMETER ServerName
+        Specifies the name of the server where the SQL Server instance is running.
+        Defaults to the local computer name.
+
+    .PARAMETER InstanceName
+        Specifies the name of the SQL Server instance for which to return protocol
+        information.
+
+    .PARAMETER ProtocolName
+        Specifies the name of the network protocol to return information for.
+        Valid values are 'TcpIp', 'NamedPipes', and 'SharedMemory'.
+        If not specified, all protocols are returned.
+
+    .PARAMETER ManagedComputerObject
+        Specifies a managed computer object from which to retrieve server protocol
+        information. This parameter accepts pipeline input from Get-SqlDscManagedComputer.
+
+    .PARAMETER ManagedComputerInstanceObject
+        Specifies a managed computer instance object from which to retrieve server
+        protocol information. This parameter accepts pipeline input from
+        Get-SqlDscManagedComputerInstance.
+
+    .EXAMPLE
+        Get-SqlDscServerProtocol -InstanceName 'MSSQLSERVER' -ProtocolName 'TcpIp'
+
+        Returns TcpIp protocol information for the default SQL Server instance
+        on the local computer.
+
+    .EXAMPLE
+        Get-SqlDscServerProtocol -ServerName 'MyServer' -InstanceName 'MyInstance' -ProtocolName 'NamedPipes'
+
+        Returns NamedPipes protocol information for the MyInstance SQL Server
+        instance on the MyServer computer.
+
+    .EXAMPLE
+        Get-SqlDscServerProtocol -InstanceName 'MSSQLSERVER'
+
+        Returns all protocol information for the default SQL Server instance
+        on the local computer.
+
+    .EXAMPLE
+        Get-SqlDscManagedComputer -ServerName 'MyServer' | Get-SqlDscServerProtocol -InstanceName 'MyInstance'
+
+        Uses pipeline input from Get-SqlDscManagedComputer to retrieve all protocols
+        for the specified instance.
+
+    .EXAMPLE
+        Get-SqlDscManagedComputerInstance -InstanceName 'MyInstance' | Get-SqlDscServerProtocol -ProtocolName 'TcpIp'
+
+        Uses pipeline input from Get-SqlDscManagedComputerInstance to retrieve TcpIp
+        protocol information.
+
+    .INPUTS
+        Microsoft.SqlServer.Management.Smo.Wmi.ManagedComputer
+
+        A managed computer object can be piped to this command.
+
+        Microsoft.SqlServer.Management.Smo.Wmi.ServerInstance
+
+        A server instance object can be piped to this command.
+
+    .OUTPUTS
+        Microsoft.SqlServer.Management.Smo.Wmi.ServerProtocol
+
+        Returns server protocol objects from SMO (SQL Server Management Objects).
+#>
+function Get-SqlDscServerProtocol
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the rule does not yet support parsing the code when a parameter type is not available. The ScriptAnalyzer rule UseSyntacticallyCorrectExamples will always error in the editor due to https://github.com/indented-automation/Indented.ScriptAnalyzerRules/issues/8.')]
+    [CmdletBinding(DefaultParameterSetName = 'ByServerName')]
+    [OutputType([Microsoft.SqlServer.Management.Smo.Wmi.ServerProtocol])]
+    param
+    (
+        [Parameter(ParameterSetName = 'ByServerName')]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $ServerName,
+
+        [Parameter(Mandatory = $true, ParameterSetName = 'ByServerName')]
+        [Parameter(Mandatory = $true, ParameterSetName = 'ByManagedComputerObject')]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $InstanceName,
+
+        [Parameter(ParameterSetName = 'ByServerName')]
+        [Parameter(ParameterSetName = 'ByManagedComputerObject')]
+        [Parameter(ParameterSetName = 'ByManagedComputerInstanceObject')]
+        [ValidateSet('TcpIp', 'NamedPipes', 'SharedMemory')]
+        [System.String]
+        $ProtocolName,
+
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'ByManagedComputerObject')]
+        [Microsoft.SqlServer.Management.Smo.Wmi.ManagedComputer]
+        $ManagedComputerObject,
+
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'ByManagedComputerInstanceObject')]
+        [Microsoft.SqlServer.Management.Smo.Wmi.ServerInstance]
+        $ManagedComputerInstanceObject
+    )
+
+    process
+    {
+        $previousErrorActionPreference = $ErrorActionPreference
+        $ErrorActionPreference = 'Stop'
+
+        # Set default value for ServerName if not provided
+        if (-not $PSBoundParameters.ContainsKey('ServerName'))
+        {
+            $ServerName = Get-ComputerName -ErrorAction 'Stop'
+        }
+
+        if ($PSBoundParameters.ContainsKey('ProtocolName'))
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ServerProtocol_GetState -f $ProtocolName, $InstanceName, $ServerName
+            )
+        }
+        else
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ServerProtocol_GetAllProtocols -f $InstanceName, $ServerName
+            )
+        }
+
+        switch ($PSCmdlet.ParameterSetName)
+        {
+            'ByServerName'
+            {
+                $serverInstance = Get-SqlDscManagedComputerInstance -ServerName $ServerName -InstanceName $InstanceName -ErrorAction 'Stop'
+            }
+
+            'ByManagedComputerObject'
+            {
+                $serverInstance = $ManagedComputerObject | Get-SqlDscManagedComputerInstance -InstanceName $InstanceName -ErrorAction 'Stop'
+            }
+
+            'ByManagedComputerInstanceObject'
+            {
+                $serverInstance = $ManagedComputerInstanceObject
+            }
+        }
+
+        if ($PSBoundParameters.ContainsKey('ProtocolName'))
+        {
+            # Get specific protocol
+            $protocolMapping = Get-SqlDscServerProtocolName -ProtocolName $ProtocolName -ErrorAction 'Stop'
+
+            $serverProtocolObject = $serverInstance.ServerProtocols[$protocolMapping.ShortName]
+
+            $ErrorActionPreference = $previousErrorActionPreference
+
+            if (-not $serverProtocolObject)
+            {
+                $errorMessage = $script:localizedData.ServerProtocol_ProtocolNotFound -f $protocolMapping.DisplayName, $InstanceName, $serverInstance.Parent.Name
+                $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+                    [System.InvalidOperationException]::new($errorMessage),
+                    'SqlServerProtocolNotFound',
+                    [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                    $ProtocolName
+                )
+                $PSCmdlet.ThrowTerminatingError($errorRecord)
+            }
+
+            return $serverProtocolObject
+        }
+        else
+        {
+            # Get all protocols
+            $allProtocolMappings = Get-SqlDscServerProtocolName -All -ErrorAction 'Stop'
+            $allServerProtocols = @()
+
+            foreach ($protocolMapping in $allProtocolMappings)
+            {
+                $serverProtocolObject = $serverInstance.ServerProtocols[$protocolMapping.ShortName]
+
+                if ($serverProtocolObject)
+                {
+                    $allServerProtocols += $serverProtocolObject
+                }
+            }
+
+            $ErrorActionPreference = $previousErrorActionPreference
+
+            if ($allServerProtocols.Count -eq 0)
+            {
+                return $null
+            }
+
+            return $allServerProtocols
+        }
+    }
+}