From 4da80e5dd96d71ae0d2bd37d5ce04c873040b90d Mon Sep 17 00:00:00 2001 From: Rain Sallow Date: Fri, 26 Sep 2025 15:28:15 -0400 Subject: [PATCH 1/2] (#1074) Add docs for Expand-ChocolateyArchive --- .../cmdlets/Expand-ChocolateyArchive.mdx | 268 ++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 src/content/docs/en-us/create/cmdlets/Expand-ChocolateyArchive.mdx diff --git a/src/content/docs/en-us/create/cmdlets/Expand-ChocolateyArchive.mdx b/src/content/docs/en-us/create/cmdlets/Expand-ChocolateyArchive.mdx new file mode 100644 index 0000000000..be852740df --- /dev/null +++ b/src/content/docs/en-us/create/cmdlets/Expand-ChocolateyArchive.mdx @@ -0,0 +1,268 @@ +--- +description: Information on Expand-ChocolateyArchive cmdlet +external help file: Chocolatey.PowerShell.dll-Help.xml +Module Name: Chocolatey.PowerShell +online version: https://docs.chocolatey.org/en-us/create/cmdlets/expand-chocolateyarchive +order: 50 +schema: 2.0.0 +title: Expand-ChocolateyArchive +xref: expand-chocolateyarchive +--- +import Xref from '@components/Xref.astro'; + +# Expand-ChocolateyArchive + +## SYNOPSIS +Unzips an archive file and returns the location for further processing. + +## SYNTAX + +### Path (Default) +``` +Expand-ChocolateyArchive [-Path] [-Destination] [[-FilesToExtract] ] + [[-PackageName] ] [-DisableLogging] [-UseBuiltinCompression] [-IgnoredArguments ] [-WhatIf] + [-Confirm] [] +``` + +### BothPaths +``` +Expand-ChocolateyArchive [-Path] [-Destination] [[-FilesToExtract] ] + [[-PackageName] ] -Path64 [-DisableLogging] [-UseBuiltinCompression] + [-IgnoredArguments ] [-WhatIf] [-Confirm] [] +``` + +### Path64 +``` +Expand-ChocolateyArchive [-Destination] [[-FilesToExtract] ] [[-PackageName] ] + -Path64 [-DisableLogging] [-UseBuiltinCompression] [-IgnoredArguments ] [-WhatIf] + [-Confirm] [] +``` + +## DESCRIPTION +This unzips files using the 7-zip command line tool 7z.exe by default. +Supported archive formats are listed in the [7-Zip documentation](https://sevenzip.osdn.jp/chm/general/formats.htm). + +When the `useBuiltinCompression` feature is enabled, or if the `-UseBuiltinCompression` switch is provided, +7-zip is not used. In this mode, only `.zip` archive formats are supported. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Expand-ChocolateyArchive -Path "c:\someFile.zip" -Destination $toolsDir +``` + +Extracts the contents of `someFile.zip` to `$toolsDir`. +The destination folder will be created if it doesn't exist. + +### Example 2 +```powershell +PS C:\> Expand-ChocolateyArchive -Path "c:\someFile.zip" -Path64 "C:\someFile64.zip" -Destination $toolsDir +``` + +Extracts the contents of one of the target zip files to `$toolsDir`. +Depending on whether this invocation is performed on a 32-bit or a 64-bit system, the corresponding archive is selected for extraction. +The destination folder will be created if it doesn't exist. + +### Example 3 +```powershell +PS C:\> Expand-ChocolateyArchive -Path "c:\someFile.zip" -Destination $toolsDir -FilesToExtract *.exe +``` + +Extracts all `*.exe` files from `someFile.zip` to `$toolsDir`. +The destination folder will be created if it doesn't exist. + +## PARAMETERS + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Destination +The path to a directory where you would like the unzipped files to end up. +If it does not exist, it will be created. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: UnzipLocation + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DisableLogging +Disables logging of the extracted items to speed up extraction of archives containing large numbers of files. +Usage of this parameter will prevent `Uninstall-ChocolateyZipPackage` from working; extracted files will have to be cleaned up with `Remove-Item` or a similar command instead. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FilesToExtract +Provide a folder path or a glob pattern to specify which file(s) or folder(s) to extract from the archive. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: SpecificFolder + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IgnoredArguments +Allows splatting with arguments that do not apply. Do not use directly. + +```yaml +Type: Object[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PackageName +Facilitates logging unzip activity for subsequent uninstalls. +Does not normally need to be set explicitly; Chocolatey CLI will provide the package name to the command. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +The path to the archive to be extracted. +If embedding the archive in the package next to the install script, the path should be something like `"$PSScriptRoot\file.zip"` + +This can be a 32-bit or 64-bit file. This parameter was mandatory in earlier versions of Chocolatey, but is optional if `-Path64` has been provided. + +```yaml +Type: String +Parameter Sets: Path, BothPaths +Aliases: File, FileFullPath + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path64 +Full file path to a 64-bit native installer to run. If embedding in the package, you can get it to the path with +`"$PSScriptRoot\INSTALLER_FILE"` + +Provide this when you want to provide both 32-bit and 64-bit installers, or explicitly only a 64-bit installer +(which will cause a package install failure on 32-bit systems). + +```yaml +Type: String +Parameter Sets: BothPaths, Path64 +Aliases: File64, FileFullPath64 + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -UseBuiltinCompression +If provided, uses .NET compression methods to extract files from the archive to avoid usage of `7-Zip`. +Note that with this option active, only `.zip` archives are supported. +This should not typically be provided explicitly; it is designed to be controlled via the `useBuiltinCompression` feature. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### System.String +Returns the designated `-Destination` value the archive was extracted to. + +## NOTES +If extraction fails, an exception is thrown. + +If you are embedding files into a package, ensure that you have the rights to redistribute those files if you are sharing this package publicly (like on the community feed). +Otherwise, please use `Install-ChocolateyZipPackage` to download those resources from their official distribution points. + +Will automatically call `Set-PowerShellExitCode` to set the package exit code based on 7-zip's exit code. + +## RELATED LINKS + + + + + + + + + + From 2abf220a0914e9417fdeede87d880e563d3e81e0 Mon Sep 17 00:00:00 2001 From: Rain Sallow Date: Tue, 30 Sep 2025 13:38:34 -0400 Subject: [PATCH 2/2] (#1074) Replace mentions/refs in existing docs --- astro.config.mjs | 6 +- .../create/functions/get-chocolateyunzip.mdx | 151 ------------------ .../docs/en-us/create/functions/index.mdx | 4 +- .../install-chocolateyzippackage.mdx | 80 +++++----- .../guides/create/create-zip-package.mdx | 13 +- 5 files changed, 51 insertions(+), 203 deletions(-) delete mode 100644 src/content/docs/en-us/create/functions/get-chocolateyunzip.mdx diff --git a/astro.config.mjs b/astro.config.mjs index c0dd7476ab..af19b862cf 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -215,8 +215,8 @@ export default defineConfig({ '/docs/helpersgetchocolateyconfigvalue': '/en-us/create/functions/get-chocolateyconfigvalue/', '/docs/helpers-get-chocolatey-path': '/en-us/create/functions/get-chocolateypath/', '/docs/helpersgetchocolateypath': '/en-us/create/functions/get-chocolateypath/', - '/docs/helpers-get-chocolatey-unzip': '/en-us/create/functions/get-chocolateyunzip/', - '/docs/helpersgetchocolateyunzip': '/en-us/create/functions/get-chocolateyunzip/', + '/docs/helpers-get-chocolatey-unzip': '/en-us/create/cmdlets/expand-chocolateyarchive/', + '/docs/helpersgetchocolateyunzip': '/en-us/create/cmdlets/expand-chocolateyarchive/', '/docs/helpers-get-chocolatey-web-file': '/en-us/create/functions/get-chocolateywebfile/', '/docs/helpersgetchocolateywebfile': '/en-us/create/functions/get-chocolateywebfile/', '/docs/helpers-get-environment-variable': '/en-us/create/cmdlets/get-environmentvariable/', @@ -354,4 +354,4 @@ export default defineConfig({ '/en-us/create/functions/test-processadminrights': '/en-us/create/cmdlets/test-processadminrights/', '/en-us/create/functions/update-sessionenvironment': '/en-us/create/cmdlets/update-sessionenvironment/', } -}); \ No newline at end of file +}); diff --git a/src/content/docs/en-us/create/functions/get-chocolateyunzip.mdx b/src/content/docs/en-us/create/functions/get-chocolateyunzip.mdx deleted file mode 100644 index 7f262eb489..0000000000 --- a/src/content/docs/en-us/create/functions/get-chocolateyunzip.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -order: 50 -xref: get-chocolateyunzip -title: Get-ChocolateyUnzip -description: Information on Get-ChocolateyUnzip function ---- -import Xref from '@components/Xref.astro'; - -# Get-ChocolateyUnzip - -{/* This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyUnzip.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). */} - -Unzips an archive file and returns the location for further processing. - -## Syntax - -~~~powershell -Get-ChocolateyUnzip ` - [-FileFullPath ] ` - -Destination ` - [-SpecificFolder ] ` - [-PackageName ] ` - [-FileFullPath64 ] ` - [-DisableLogging] ` - [-IgnoredArguments ] [] -~~~ - -## Description - -This unzips files using the 7-zip command line tool 7z.exe. -Supported archive formats are listed at: -https://sevenzip.osdn.jp/chm/general/formats.htm - -## Notes - -If extraction fails, an exception is thrown. - -If you are embedding files into a package, ensure that you have the -rights to redistribute those files if you are sharing this package -publicly (like on the [community feed](https://community.chocolatey.org/packages)). Otherwise, please use -Install-ChocolateyZipPackage to download those resources from their -official distribution points. - -Will automatically call Set-PowerShellExitCode to set the package exit code -based on 7-zip's exit code. - -## Aliases - -None - -## Examples - - **EXAMPLE 1** - -~~~powershell - -# Path to the folder where the script is executing -$toolsDir = (Split-Path -parent $MyInvocation.MyCommand.Definition) -Get-ChocolateyUnzip -FileFullPath "c:\someFile.zip" -Destination $toolsDir -~~~ - -## Inputs - -None - -## Outputs - -None - -## Parameters - -### -FileFullPath [<String>] -Property | Value ----------------------- | ----- -Aliases | file -Required? | false -Position? | 1 -Default Value | -Accept Pipeline Input? | false - -### -Destination <String> -Property | Value ----------------------- | ------------- -Aliases | unzipLocation -Required? | true -Position? | 2 -Default Value | -Accept Pipeline Input? | false - -### -SpecificFolder [<String>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 3 -Default Value | -Accept Pipeline Input? | false - -### -PackageName [<String>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | 4 -Default Value | -Accept Pipeline Input? | false - -### -FileFullPath64 [<String>] -Property | Value ----------------------- | ------ -Aliases | file64 -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### -DisableLogging -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | False -Accept Pipeline Input? | false - -### -IgnoredArguments [<Object[]>] -Property | Value ----------------------- | ----- -Aliases | -Required? | false -Position? | named -Default Value | -Accept Pipeline Input? | false - -### <CommonParameters> - -This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . - - -## Links - - * - - - - -> :choco-info: **NOTE** -> -> This documentation has been automatically generated from `Import-Module "$env:ChocolateyInstall\helpers\chocolateyInstaller.psm1" -Force; Get-Help Get-ChocolateyUnzip -Full`. - -View the source for [Get-ChocolateyUnzip](https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Get-ChocolateyUnzip.ps1) diff --git a/src/content/docs/en-us/create/functions/index.mdx b/src/content/docs/en-us/create/functions/index.mdx index bba45e3f95..ffe446ee2d 100644 --- a/src/content/docs/en-us/create/functions/index.mdx +++ b/src/content/docs/en-us/create/functions/index.mdx @@ -47,11 +47,11 @@ When you have a need to run Chocolatey without Administrative access required (n These are the functions from above as one list. +* * * * * -* * - when specifying user path * - when specifying user path * @@ -61,11 +61,11 @@ These are the functions from above as one list. ## Complete List (alphabetical order) + * * * * * - * * * * diff --git a/src/content/docs/en-us/create/functions/install-chocolateyzippackage.mdx b/src/content/docs/en-us/create/functions/install-chocolateyzippackage.mdx index c21ab866d1..98aec530bb 100644 --- a/src/content/docs/en-us/create/functions/install-chocolateyzippackage.mdx +++ b/src/content/docs/en-us/create/functions/install-chocolateyzippackage.mdx @@ -11,7 +11,7 @@ import Xref from '@components/Xref.astro'; {/* This documentation is automatically generated from https://github.com/chocolatey/choco/blob/master/src/chocolatey.resources/helpers/functions/Install-ChocolateyZipPackage.ps1 using https://github.com/chocolatey/choco/blob/master/GenerateDocs.ps1. Contributions are welcome at the original location(s). */} Downloads file from a url and unzips it on your machine. Use -Get-ChocolateyUnzip when local or embedded file. +Expand-ChocolateyArchive when local or embedded file. ## Syntax @@ -37,7 +37,7 @@ Install-ChocolateyZipPackage ` This will download a file from a url and unzip it on your machine. If you are embedding the file(s) directly in the package (or do not need -to download a file first), use Get-ChocolateyUnzip instead. +to download a file first), use Expand-ChocolateyArchive instead. ## Notes @@ -79,7 +79,7 @@ Install-ChocolateyZipPackage -PackageName 'sysinternals' ` -Url 'http://download.sysinternals.com/Files/SysinternalsSuite.zip' ` -UnzipLocation "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)" ` -Url64 'http://download.sysinternals.com/Files/SysinternalsSuitex64.zip' -~~~ +~~~ ## Inputs @@ -94,129 +94,129 @@ None ### -PackageName <String> Property | Value ---------------------- | ----- -Aliases | +Aliases | Required? | true Position? | 1 -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -Url [<String>] Property | Value ---------------------- | ----- -Aliases | +Aliases | Required? | false Position? | 2 -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -UnzipLocation <String> Property | Value ---------------------- | ----------- Aliases | destination Required? | true Position? | 3 -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -Url64bit [<String>] Property | Value ---------------------- | ----- Aliases | url64 Required? | false Position? | 4 -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -SpecificFolder [<String>] Property | Value ---------------------- | ----- -Aliases | +Aliases | Required? | false Position? | named -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -Checksum [<String>] Property | Value ---------------------- | ----- -Aliases | +Aliases | Required? | false Position? | named -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -ChecksumType [<String>] Property | Value ---------------------- | ----- -Aliases | +Aliases | Required? | false Position? | named -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -Checksum64 [<String>] Property | Value ---------------------- | ----- -Aliases | +Aliases | Required? | false Position? | named -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -ChecksumType64 [<String>] Property | Value ---------------------- | ----- -Aliases | +Aliases | Required? | false Position? | named -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -Options [<Hashtable>] Property | Value ---------------------- | ------------------- -Aliases | +Aliases | Required? | false Position? | named Default Value | `@{Headers = @{}` } Accept Pipeline Input? | false - + ### -File [<String>] Property | Value ---------------------- | ------------ Aliases | fileFullPath Required? | false Position? | named -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -File64 [<String>] Property | Value ---------------------- | -------------- Aliases | fileFullPath64 Required? | false Position? | named -Default Value | +Default Value | Accept Pipeline Input? | false - + ### -DisableLogging Property | Value ---------------------- | ----- -Aliases | +Aliases | Required? | false Position? | named Default Value | False Accept Pipeline Input? | false - + ### -IgnoredArguments [<Object[]>] Property | Value ---------------------- | ----- -Aliases | +Aliases | Required? | false Position? | named -Default Value | +Default Value | Accept Pipeline Input? | false - + ### <CommonParameters> This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see `about_CommonParameters` http://go.microsoft.com/fwlink/p/?LinkID=113216 . @@ -225,7 +225,7 @@ This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -Err ## Links * - * + * diff --git a/src/content/docs/en-us/guides/create/create-zip-package.mdx b/src/content/docs/en-us/guides/create/create-zip-package.mdx index 1548b6b033..1cf06e80c6 100644 --- a/src/content/docs/en-us/guides/create/create-zip-package.mdx +++ b/src/content/docs/en-us/guides/create/create-zip-package.mdx @@ -14,9 +14,9 @@ In this walk-through we'll learn how to leverage zip archives within our packagi If you have not yet read , please do so now and ensure you are ready to go before continuing. -### Using `Get-ChocolateyUnzip` +### Using `Expand-ChocolateyArchive` -In our first example, we'll leverage to extract a Zip archive to disk. This function requires +In our first example, we'll leverage to extract a Zip archive to disk. This function requires that you include the Zip archive as part of the package. We'll look at downloading an archive from an external location later in our **Creating A Large Package** tutorial. #### Creating Your Package @@ -33,7 +33,7 @@ Perform the following steps: Your new package will be created in the `tutorials` folder, visible in the Explorer pane of VS Code. Expand the `tools` folder and open up the `chocolateyInstall.ps1` file. The `chocolateyInstall.ps1` file is -executed when you run either the `install` or `upgrade` commands with your package. +executed when you run either the `install` or `upgrade` commands with your package. The default template fills this file out for us and provides a LOT of information. For our purposes, we can press `Ctrl+A` and delete the contents of this file. @@ -44,13 +44,12 @@ $ErrorActionPreference = 'Stop' # stop on all errors $toolsDir = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)" $zipArchive = Join-Path $toolsDir -ChildPath 'tutorial.zip' - $unzipArgs = @{ - FileFullPath = $zipArchive + Path = $zipArchive Destination = 'C:\zip_tutorial' } -Get-ChocolateyUnzip @unzipArgs +Expand-ChocolateyArchive @unzipArgs ``` @@ -138,4 +137,4 @@ choco uninstall embedded-zip -y ## Conclusion -At this point, you should have a working Zip archive package! Congratulations! Hopefully you can apply this to other Zip archives! \ No newline at end of file +At this point, you should have a working Zip archive package! Congratulations! Hopefully you can apply this to other Zip archives!