Add new commands to enable and disable SQL Server logins with comprehensive testing

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

@@ -165,7 +165,7 @@ function Get-Something
 
 ## File Rules
 
-- End files with a blank line
+- End files with only one blank line
 - Use CR+LF line endings
 - Maximum two consecutive newlines
 

CHANGELOG.md

@@ -24,7 +24,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     job-level env declaration.
 - `Assert-SqlDscLogin`
   - Added new public command to validate that a specified SQL Server principal
-    exists as a login, throwing a terminating error if it doesn't exist.
+    is a login.
+- `Enable-SqlDscLogin`
+  - Added new public command to enable a SQL Server login.
+- `Disable-SqlDscLogin`
+  - Added new public command to disable a SQL Server login.
+- `Test-SqlDscIsLoginEnabled`
+  - Added new public command to test whether a SQL Server login is enabled.
+    Throws a terminating error if the specified principal does not exist as a login.
   - Supports pipeline input and provides detailed error messages with localization.
   - Uses `Test-SqlDscIsLogin` command for login validation following module patterns.
 - Added `Get-SqlDscLogin`, `Get-SqlDscRole`, `New-SqlDscLogin`, `New-SqlDscRole`, `Remove-SqlDscRole`, and `Remove-SqlDscLogin` commands for retrieving and managing SQL Server logins and roles with support for refresh, pipeline input, and ShouldProcess.

azure-pipelines.yml

@@ -294,11 +294,13 @@ stages:
                   'tests/Integration/Commands/Assert-SqlDscLogin.Integration.Tests.ps1'
                   'tests/Integration/Commands/New-SqlDscLogin.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscLogin.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'
                   'tests/Integration/Commands/New-SqlDscRole.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscRole.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscRole.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscLogin.Integration.Tests.ps1'
-
                   # Group 9
                   'tests/Integration/Commands/Uninstall-SqlDscServer.Integration.Tests.ps1'
               )

source/Public/Disable-SqlDscLogin.ps1

@@ -0,0 +1,120 @@
+<#
+    .SYNOPSIS
+        Disables a SQL Server login.
+
+    .DESCRIPTION
+        This command disables a SQL Server login in a SQL Server Database Engine instance.
+
+    .PARAMETER ServerObject
+        Specifies current server connection object.
+
+    .PARAMETER LoginObject
+        Specifies a login object to disable.
+
+    .PARAMETER Name
+        Specifies the name of the server login to be disabled.
+
+    .PARAMETER Force
+        Specifies that the login should be disabled without any confirmation.
+
+    .PARAMETER Refresh
+        Specifies that the **ServerObject**'s logins should be refreshed before
+        trying to disable the login object. This is helpful when logins could have
+        been modified outside of the **ServerObject**, for example through T-SQL.
+        But on instances with a large amount of logins it might be better to make
+        sure the **ServerObject** is recent enough, or pass in **LoginObject**.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $loginObject = $serverObject | Get-SqlDscLogin -Name 'MyLogin'
+        $loginObject | Disable-SqlDscLogin
+
+        Disables the login named **MyLogin**.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $serverObject | Disable-SqlDscLogin -Name 'MyLogin'
+
+        Disables the login named **MyLogin**.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $serverObject | Disable-SqlDscLogin -Name 'MyLogin' -Force
+
+        Disables the login without confirmation using **-Force**.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $serverObject | Disable-SqlDscLogin -Name 'MyLogin' -Refresh
+
+        Refreshes the server logins collection before disabling **MyLogin**.
+    .INPUTS
+        [Microsoft.SqlServer.Management.Smo.Server]
+
+        Server object accepted from the pipeline (ServerObject parameter set).
+
+        [Microsoft.SqlServer.Management.Smo.Login]
+
+        Login object accepted from the pipeline (LoginObject parameter set).
+
+    .OUTPUTS
+        None.
+#>
+function Disable-SqlDscLogin
+{
+    [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.')]
+    [OutputType()]
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+    param
+    (
+        [Parameter(ParameterSetName = 'ServerObject', Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(ParameterSetName = 'LoginObject', Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Login]
+        $LoginObject,
+
+        [Parameter(ParameterSetName = 'ServerObject', Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $Force,
+
+        [Parameter(ParameterSetName = 'ServerObject')]
+        [System.Management.Automation.SwitchParameter]
+        $Refresh
+    )
+
+    process
+    {
+        if ($Force.IsPresent -and -not $Confirm)
+        {
+            $ConfirmPreference = 'None'
+        }
+
+        if ($PSCmdlet.ParameterSetName -eq 'ServerObject')
+        {
+            $getSqlDscLoginParameters = @{
+                ServerObject = $ServerObject
+                Name         = $Name
+                Refresh      = $Refresh
+                ErrorAction  = 'Stop'
+            }
+
+            # If this command does not find the login it will throw an exception.
+            $LoginObject = Get-SqlDscLogin @getSqlDscLoginParameters
+        }
+
+        $verboseDescriptionMessage = $script:localizedData.Login_Disable_ShouldProcessVerboseDescription -f $LoginObject.Name, $LoginObject.Parent.InstanceName
+        $verboseWarningMessage = $script:localizedData.Login_Disable_ShouldProcessVerboseWarning -f $LoginObject.Name
+        $captionMessage = $script:localizedData.Login_Disable_ShouldProcessCaption
+
+        if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage))
+        {
+            $LoginObject.Disable()
+        }
+    }
+}

source/Public/Enable-SqlDscLogin.ps1

@@ -0,0 +1,107 @@
+<#
+    .SYNOPSIS
+        Enables a SQL Server login.
+
+    .DESCRIPTION
+        This command enables a SQL Server login in a SQL Server Database Engine instance.
+
+    .PARAMETER ServerObject
+        Specifies current server connection object.
+
+    .PARAMETER LoginObject
+        Specifies a login object to enable.
+
+    .PARAMETER Name
+        Specifies the name of the server login to be enabled.
+
+    .PARAMETER Force
+        Specifies that the login should be enabled without any confirmation.
+
+    .PARAMETER Refresh
+        Specifies that the **ServerObject**'s logins should be refreshed before
+        trying to enable the login object. This is helpful when logins could have
+        been modified outside of the **ServerObject**, for example through T-SQL.
+        But on instances with a large amount of logins it might be better to make
+        sure the **ServerObject** is recent enough, or pass in **LoginObject**.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $loginObject = $serverObject | Get-SqlDscLogin -Name 'MyLogin'
+        $loginObject | Enable-SqlDscLogin
+
+        Enables the login named **MyLogin**.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $serverObject | Enable-SqlDscLogin -Name 'MyLogin'
+
+        Enables the login named **MyLogin**.
+
+    .INPUTS
+        Microsoft.SqlServer.Management.Smo.Server
+            When using the ServerObject parameter set, a Server object can be piped in.
+
+        Microsoft.SqlServer.Management.Smo.Login
+            When using the LoginObject parameter set, a Login object can be piped in.
+
+    .OUTPUTS
+        None.
+#>
+function Enable-SqlDscLogin
+{
+    [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.')]
+    [OutputType()]
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+    param
+    (
+        [Parameter(ParameterSetName = 'ServerObject', Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(ParameterSetName = 'LoginObject', Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Login]
+        $LoginObject,
+
+        [Parameter(ParameterSetName = 'ServerObject', Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $Force,
+
+        [Parameter(ParameterSetName = 'ServerObject')]
+        [System.Management.Automation.SwitchParameter]
+        $Refresh
+    )
+
+    process
+    {
+        if ($Force.IsPresent -and -not $Confirm)
+        {
+            $ConfirmPreference = 'None'
+        }
+
+        if ($PSCmdlet.ParameterSetName -eq 'ServerObject')
+        {
+            $getSqlDscLoginParameters = @{
+                ServerObject = $ServerObject
+                Name         = $Name
+                Refresh      = $Refresh
+                ErrorAction  = 'Stop'
+            }
+
+            # If this command does not find the login it will throw an exception.
+            $LoginObject = Get-SqlDscLogin @getSqlDscLoginParameters
+        }
+
+        $verboseDescriptionMessage = $script:localizedData.Login_Enable_ShouldProcessVerboseDescription -f $LoginObject.Name, $LoginObject.Parent.InstanceName
+        $verboseWarningMessage = $script:localizedData.Login_Enable_ShouldProcessVerboseWarning -f $LoginObject.Name
+        $captionMessage = $script:localizedData.Login_Enable_ShouldProcessCaption
+
+        if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage))
+        {
+            $LoginObject.Enable()
+        }
+    }
+}

source/Public/Test-SqlDscIsLoginEnabled.ps1

@@ -0,0 +1,112 @@
+<#
+    .SYNOPSIS
+        Returns whether the server login is enabled or disabled.
+
+    .DESCRIPTION
+        Tests the state of a SQL Server login and returns a Boolean result.
+        When a Server object is provided, the login is resolved using
+        Get-SqlDscLogin (optionally refreshing the server logins first).
+        When a Login object is provided, its current state is evaluated directly.
+    .PARAMETER ServerObject
+        Specifies current server connection object.
+
+    .PARAMETER LoginObject
+        Specifies a login object to test.
+
+    .PARAMETER Name
+        Specifies the name of the server login to test.
+
+    .PARAMETER Refresh
+        Specifies that the **ServerObject**'s logins should be refreshed before
+        trying to test the login object. This is helpful when logins could have
+        been modified outside of the **ServerObject**, for example through T-SQL.
+        But on instances with a large amount of logins it might be better to make
+        sure the **ServerObject** is recent enough, or pass in **LoginObject**.
+
+    .INPUTS
+        [Microsoft.SqlServer.Management.Smo.Server]
+
+        Server object accepted from the pipeline.
+
+        [Microsoft.SqlServer.Management.Smo.Login]
+
+        Login object accepted from the pipeline.
+
+    .OUTPUTS
+        [System.Boolean]
+
+        Returns $true if the login is enabled, $false if the login is disabled.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        Test-SqlDscIsLoginEnabled -ServerObject $serverObject -Name 'MyLogin'
+
+        Returns $true if the login is enabled, if not $false is returned.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $loginObject = $serverObject | Get-SqlDscLogin -Name 'MyLogin'
+        Test-SqlDscIsLoginEnabled -LoginObject $loginObject
+
+        Returns $true if the login is enabled, if not $false is returned.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $result = $serverObject | Test-SqlDscIsLoginEnabled -Name 'MyLogin'
+
+        Demonstrates pipeline usage with ServerObject. Returns $true if the login is enabled, if not $false is returned.
+
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $loginObject = $serverObject | Get-SqlDscLogin -Name 'MyLogin'
+        $result = $loginObject | Test-SqlDscIsLoginEnabled
+
+        Demonstrates pipeline usage with LoginObject. Returns $true if the login is enabled, if not $false is returned.
+#>
+function Test-SqlDscIsLoginEnabled
+{
+    [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()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(ParameterSetName = 'ServerObject', Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(ParameterSetName = 'LoginObject', Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Login]
+        $LoginObject,
+
+        [Parameter(ParameterSetName = 'ServerObject', Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter(ParameterSetName = 'ServerObject')]
+        [System.Management.Automation.SwitchParameter]
+        $Refresh
+    )
+
+    process
+    {
+        if ($PSCmdlet.ParameterSetName -eq 'ServerObject')
+        {
+            $getSqlDscLoginParameters = @{
+                ServerObject = $ServerObject
+                Name         = $Name
+                Refresh      = $Refresh
+                ErrorAction  = 'Stop'
+            }
+
+            # If this command does not find the login it will throw an exception.
+            $loginObjectArray = Get-SqlDscLogin @getSqlDscLoginParameters
+
+            # Pick the only object in the array.
+            $LoginObject = $loginObjectArray
+        }
+
+        $loginEnabled = -not $LoginObject.IsDisabled
+
+        return $loginEnabled
+    }
+}