Get‑SqlDscBackupFileList

SYNOPSIS

Gets the list of files contained in a SQL Server backup file.

SYNTAX

Get-SqlDscBackupFileList [-ServerObject] <Server> [-BackupFile] <String> [[-FileNumber] <Int32>]
 [<CommonParameters>]

DESCRIPTION

This command reads and returns the list of database files contained in a SQL Server backup file using SQL Server Management Objects (SMO). This is useful for understanding the file structure of a backup before performing a restore operation, especially when file relocation is needed.

EXAMPLES

EXAMPLE 1

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$serverObject | Get-SqlDscBackupFileList -BackupFile 'C:\Backups\MyDatabase.bak'

Gets the list of files contained in the specified backup file.

EXAMPLE 2

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$files = $serverObject | Get-SqlDscBackupFileList -BackupFile 'C:\Backups\MyDatabase.bak'
$relocateFiles = $files | ForEach-Object {
    $newPath = if ($_.Type -eq 'L') { 'L:\SQLLogs' } else { 'D:\SQLData' }
    [Microsoft.SqlServer.Management.Smo.RelocateFile]::new(
        $_.LogicalName,
        (Join-Path -Path $newPath -ChildPath ([System.IO.Path]::GetFileName($_.PhysicalName)))
    )
}
$serverObject | Restore-SqlDscDatabase -Name 'MyDatabase' -BackupFile 'C:\Backups\MyDatabase.bak' -RelocateFile $relocateFiles

Gets the file list and creates RelocateFile objects for a restore operation that moves files to different directories.

PARAMETERS

-BackupFile

Specifies the full path to the backup file to read.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-FileNumber

Specifies the backup set number to read when the backup file contains multiple backup sets. Default is 1.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-ServerObject

Specifies the current server connection object.

Type: Server
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

Microsoft.SqlServer.Management.Smo.Server

Server object accepted from the pipeline.

OUTPUTS

BackupFileSpec[]

Returns an array of BackupFileSpec objects describing each file in the backup.

NOTES

RELATED LINKS