Add PassThru parameter to Backup-SqlDscDatabase for returning database object and enhance tests

Author: johlju

source/Public/Backup-SqlDscDatabase.ps1

@@ -63,6 +63,10 @@
     .PARAMETER Force
         Specifies that the backup should be performed without any confirmation.
 
+    .PARAMETER PassThru
+        Returns the database object that was backed up. By default, this command
+        does not generate any output.
+
     .EXAMPLE
         $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
         $serverObject | Backup-SqlDscDatabase -Name 'MyDatabase' -BackupFile 'C:\Backups\MyDatabase.bak'
@@ -104,6 +108,14 @@
         Performs a compressed full backup with checksum verification of the
         database named **MyDatabase**.
 
+    .EXAMPLE
+        $serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
+        $databaseObject = $serverObject | Backup-SqlDscDatabase -Name 'MyDatabase' -BackupFile 'C:\Backups\MyDatabase.bak' -PassThru -Force
+        $databaseObject | Set-SqlDscDatabaseProperty -RecoveryModel 'Simple' -Force
+
+        Performs a full backup of the database named **MyDatabase** and returns
+        the database object for further pipeline operations.
+
     .INPUTS
         `Microsoft.SqlServer.Management.Smo.Server`
 
@@ -116,11 +128,19 @@
 
     .OUTPUTS
         None.
+
+        No output when the **PassThru** parameter is not specified.
+
+    .OUTPUTS
+        `Microsoft.SqlServer.Management.Smo.Database`
+
+        Returns the database object that was backed up when using the **PassThru** parameter.
 #>
 function Backup-SqlDscDatabase
 {
     [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()]
+    [OutputType([Microsoft.SqlServer.Management.Smo.Database])]
     [CmdletBinding(DefaultParameterSetName = 'ServerObject', SupportsShouldProcess = $true, ConfirmImpact = 'Low')]
     param
     (
@@ -179,7 +199,11 @@ function Backup-SqlDscDatabase
 
         [Parameter()]
         [System.Management.Automation.SwitchParameter]
-        $Force
+        $Force,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $PassThru
     )
 
     begin
@@ -351,6 +375,11 @@ function Backup-SqlDscDatabase
                 $backup.SqlBackup($ServerObject)
 
                 Write-Debug -Message ($script:localizedData.Database_Backup_Success -f $backupTypeDescription, $Name)
+
+                if ($PassThru.IsPresent)
+                {
+                    return $DatabaseObject
+                }
             }
             catch
             {

tests/Unit/Public/Backup-SqlDscDatabase.Tests.ps1

@@ -242,11 +242,57 @@ Describe 'Backup-SqlDscDatabase' -Tag 'Public' {
         }
     }
 
+    Context 'When using PassThru parameter' {
+        BeforeAll {
+            $mockDatabaseObject = New-Object -TypeName 'Microsoft.SqlServer.Management.Smo.Database'
+            $mockDatabaseObject | Add-Member -MemberType 'NoteProperty' -Name 'Name' -Value 'TestDatabase' -Force
+            $mockDatabaseObject | Add-Member -MemberType 'NoteProperty' -Name 'RecoveryModel' -Value ([Microsoft.SqlServer.Management.Smo.RecoveryModel]::Full) -Force
+            $mockDatabaseObject | Add-Member -MemberType 'NoteProperty' -Name 'Status' -Value ([Microsoft.SqlServer.Management.Smo.DatabaseStatus]::Normal) -Force
+            $mockDatabaseObject | Add-Member -MemberType 'ScriptProperty' -Name 'Parent' -Value {
+                $mockParent = New-Object -TypeName 'Microsoft.SqlServer.Management.Smo.Server'
+                $mockParent | Add-Member -MemberType 'NoteProperty' -Name 'InstanceName' -Value 'TestInstance' -Force
+                return $mockParent
+            } -Force
+
+            $mockServerObject = New-Object -TypeName 'Microsoft.SqlServer.Management.Smo.Server'
+            $mockServerObject | Add-Member -MemberType 'NoteProperty' -Name 'InstanceName' -Value 'TestInstance' -Force
+            $mockServerObject | Add-Member -MemberType 'ScriptProperty' -Name 'Databases' -Value {
+                return @{
+                    'TestDatabase' = $mockDatabaseObject
+                } | Add-Member -MemberType 'ScriptMethod' -Name 'Refresh' -Value {
+                    # Mock implementation
+                } -PassThru -Force
+            } -Force
+        }
+
+        It 'Should return database object when PassThru is specified with ServerObject' {
+            $result = Backup-SqlDscDatabase -ServerObject $mockServerObject -Name 'TestDatabase' -BackupFile 'C:\Backups\TestDatabase.bak' -PassThru -Force
+
+            $result | Should -Not -BeNullOrEmpty
+            $result | Should -BeOfType 'Microsoft.SqlServer.Management.Smo.Database'
+            $result.Name | Should -Be 'TestDatabase'
+        }
+
+        It 'Should return database object when PassThru is specified with DatabaseObject' {
+            $result = Backup-SqlDscDatabase -DatabaseObject $mockDatabaseObject -BackupFile 'C:\Backups\TestDatabase.bak' -PassThru -Force
+
+            $result | Should -Not -BeNullOrEmpty
+            $result | Should -BeOfType 'Microsoft.SqlServer.Management.Smo.Database'
+            $result.Name | Should -Be 'TestDatabase'
+        }
+
+        It 'Should not return anything when PassThru is not specified' {
+            $result = Backup-SqlDscDatabase -DatabaseObject $mockDatabaseObject -BackupFile 'C:\Backups\TestDatabase.bak' -Force
+
+            $result | Should -BeNullOrEmpty
+        }
+    }
+
     Context 'Parameter validation' {
         It 'Should have the correct parameters in parameter set ServerObject' -ForEach @(
             @{
                 ExpectedParameterSetName = 'ServerObject'
-                ExpectedParameters       = '-ServerObject <Server> -Name <string> -BackupFile <string> [-BackupType <string>] [-CopyOnly] [-Compress] [-Checksum] [-Description <string>] [-RetainDays <int>] [-Initialize] [-Refresh] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]'
+                ExpectedParameters       = '-ServerObject <Server> -Name <string> -BackupFile <string> [-BackupType <string>] [-CopyOnly] [-Compress] [-Checksum] [-Description <string>] [-RetainDays <int>] [-Initialize] [-Refresh] [-Force] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]'
             }
         ) {
             $result = (Get-Command -Name 'Backup-SqlDscDatabase').ParameterSets |
@@ -263,7 +309,7 @@ Describe 'Backup-SqlDscDatabase' -Tag 'Public' {
         It 'Should have the correct parameters in parameter set DatabaseObject' -ForEach @(
             @{
                 ExpectedParameterSetName = 'DatabaseObject'
-                ExpectedParameters       = '-DatabaseObject <Database> -BackupFile <string> [-BackupType <string>] [-CopyOnly] [-Compress] [-Checksum] [-Description <string>] [-RetainDays <int>] [-Initialize] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]'
+                ExpectedParameters       = '-DatabaseObject <Database> -BackupFile <string> [-BackupType <string>] [-CopyOnly] [-Compress] [-Checksum] [-Description <string>] [-RetainDays <int>] [-Initialize] [-Force] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]'
             }
         ) {
             $result = (Get-Command -Name 'Backup-SqlDscDatabase').ParameterSets |