From 034d258825c0a6e4dc896177ec06c8c7dcea8ee7 Mon Sep 17 00:00:00 2001 From: Santiago Squarzon Date: Tue, 24 Jun 2025 13:00:33 -0300 Subject: [PATCH] add a note to readme, compress-ziparchive, new-zipentry and set-zipentrycontent. solves #38. --- README.md | 3 +++ docs/en-US/Compress-ZipArchive.md | 9 ++++++--- docs/en-US/New-ZipEntry.md | 3 +++ docs/en-US/Set-ZipEntryContent.md | 7 +++++-- 4 files changed, 17 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 235480a..cbea1d0 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,9 @@ +> [!NOTE] +> Due to a .NET limitation, cmdlets like `New-ZipEntry`, `Compress-ZipArchive` with `-Update`, and `Set-ZipEntryContent` may fail when handling files or content > 2 GB __in existing zip archives__. As a workaround, recreate the zip archive or use tools like 7-Zip, which support larger files. See issue #19 for details. + ### Tar Archive Cmdlets diff --git a/docs/en-US/Compress-ZipArchive.md b/docs/en-US/Compress-ZipArchive.md index 85dcd91..7cd238a 100644 --- a/docs/en-US/Compress-ZipArchive.md +++ b/docs/en-US/Compress-ZipArchive.md @@ -45,9 +45,9 @@ Compress-ZipArchive PowerShell cmdlet that overcomes the limitation that the built-in cmdlet `Compress-Archive` has: -> The `Compress-Archive` cmdlet uses the Microsoft .NET API [`System.IO.Compression.ZipArchive`](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.ziparchive?view=net-6.0) to compress files. The maximum file size is 2 GB because there's a limitation of the underlying API. +> The `Compress-Archive` cmdlet uses the Microsoft .NET API [`System.IO.Compression.ZipArchive`](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.ziparchive) to compress files. The maximum file size is 2 GB because there's a limitation of the underlying API. -The easy workaround would be to use the [`ZipFile.CreateFromDirectory` Method](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.zipfile.createfromdirectory?view=net-6.0#system-io-compression-zipfile-createfromdirectory(system-string-system-string)). +The easy workaround would be to use the [`ZipFile.CreateFromDirectory` Method](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.zipfile.createfromdirectory#system-io-compression-zipfile-createfromdirectory(system-string-system-string)). However, there are 3 limitations while using this method: @@ -55,7 +55,10 @@ However, there are 3 limitations while using this method: 2. All files (recursively) on the source folder __will be compressed__, we can't pick / filter files to compress. 3. It's not possible to __Update__ the entries of an existing Zip Archive. -This cmdlet should be able to handle compression same as `ZipFile.CreateFromDirectory` Method but also allow filtering files and folders to compress while keeping the __file / folder structure untouched__. +This cmdlet should be able to handle compression same as `ZipFile.CreateFromDirectory` Method but also allow filtering files and folders to compress while keeping the __file / folder structure intact__. + +> [!NOTE] +> When appending to an existing zip archive using the [`-Update` parameter](#-update), a .NET limitation may cause failures for files larger than 2 GB. To handle such files, recreate the archive or use tools like 7-Zip. See issue #19 for details. ## EXAMPLES diff --git a/docs/en-US/New-ZipEntry.md b/docs/en-US/New-ZipEntry.md index 926b06e..113ac08 100644 --- a/docs/en-US/New-ZipEntry.md +++ b/docs/en-US/New-ZipEntry.md @@ -55,6 +55,9 @@ Entry paths, _arguments of the `-EntryPath` parameter_, are always normalized, a In addition, `New-ZipEntry` can set the content of the entries that it creates from string input or by specifying a source file path. +> [!NOTE] +> Due to a .NET limitation, adding files larger than 2 GB to an existing zip archive may fail. To handle such files, recreate the zip archive or use tools like 7-Zip. See issue #19 for details. + ## EXAMPLES ### Example 1: Create empty entries diff --git a/docs/en-US/Set-ZipEntryContent.md b/docs/en-US/Set-ZipEntryContent.md index b95e612..65a1ea5 100644 --- a/docs/en-US/Set-ZipEntryContent.md +++ b/docs/en-US/Set-ZipEntryContent.md @@ -18,7 +18,7 @@ Sets or appends content to an existing zip entry. ```powershell Set-ZipEntryContent -Value - -SourceEntry + [-SourceEntry] [-Encoding ] [-Append] [-PassThru] @@ -30,7 +30,7 @@ Set-ZipEntryContent ```powershell Set-ZipEntryContent -Value - -SourceEntry + [-SourceEntry] [-AsByteStream] [-Append] [-BufferSize ] @@ -44,6 +44,9 @@ The `Set-ZipEntryContent` cmdlet can write or append content to a Zip Archive En If you need to create a new Zip Archive Entry you can use the [`New-ZipEntry` cmdlet](./New-ZipEntry.md). +> [!NOTE] +> Due to a .NET limitation, writing or appending content larger than 2 GB to an existing zip entry may fail. To handle such content, recreate the zip archive or use tools like 7-Zip. See issue #19 for details. + ## EXAMPLES ### Example 1: Write new content to a Zip Archive Entry