# Expand-CompressedFile

[Function index](README.md) | [Repository readme](../README.md) | [Source](../Toolkit/Functions/Expand-CompressedFile.ps1)

> Expands a compressed file or archive using the first available extraction provider.

## Description

The extraction provider is selected based upon the archive format and the tooling that is available on the device.

1. 7-Zip - "Toolkit\Tools\<Architecture>\7z.exe" is preferred, followed by any copy of "7z.exe" or "7za.exe" that is available within the process path, followed by the installed copy within the program files directory. This provider handles every supported format, including a raw bzip2 stream such as an OPNsense disc image.
2. BSDTar - "tar.exe" is included with the operating system, but it can only read genuine tar archives. It is the only provider that natively supports the removal of leading path components.
3. .NET - The "System.IO.Compression" namespace is used for zip archives and raw gzip streams.

Extraction always occurs within a staging directory so that the leading path component removal and the inclusion filter can be applied before anything is placed into the destination directory.

## Parameters

| Name | Type | Required | Aliases | Description |
| --- | --- | --- | --- | --- |
| `Path` | `IO.FileInfo` | Yes | P | A valid file path to the compressed file or archive that will be expanded. |
| `Destination` | `IO.DirectoryInfo` | Yes | D | A valid folder path. If the folder does not exist, it will be created. |
| `StripComponents` | `Int32` | No | SC | The number of leading path components to remove from each extracted item. This is the equivalent of the tar "--strip-components" argument and allows a single nested item, such as a disc image, to be placed directly within the destination directory. |
| `IncludeFilter` | `String[]` | No | IF | One or more wildcard expressions. Only the extracted items whose name matches one of the expressions will be placed into the destination directory. |
| `Force` | `Switch` | No | F | Overwrite any item that already exists within the destination directory. |
| `ContinueOnError` | `Switch` | No | COE | Ignore failures. |

## Examples

### Example 1

```powershell
$ExpandCompressedFileParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary'
  $ExpandCompressedFileParameters.Path = "$($ContentDirectory.FullName)\ISOs\OPNsense-26.1.6-dvd-amd64.iso.bz2"
  $ExpandCompressedFileParameters.Destination = "$($ContentDirectory.FullName)\ISOs"
  $ExpandCompressedFileParameters.StripComponents = 1
  $ExpandCompressedFileParameters.IncludeFilter = New-Object -TypeName 'System.Collections.Generic.List[System.String]'
    $ExpandCompressedFileParameters.IncludeFilter.Add('*.iso')
  $ExpandCompressedFileParameters.Verbose = $True
$ExpandCompressedFileResult = Expand-CompressedFile @ExpandCompressedFileParameters

Write-Output -InputObject ($ExpandCompressedFileResult.ItemList)
```

## Notes

The copy of "tar.exe" that is included with the operating system cannot read a raw, non-tar bzip2 stream. It fails with "Unrecognized archive format", which is the reason that 7-Zip is bundled within the toolkit.

## Reference

- <https://learn.microsoft.com/en-us/windows/win32/wsw/tar>