Add Compression best practices guide by alinpahontu2912 · Pull Request #52968 · dotnet/docs

alinpahontu2912 · 2026-04-10T10:36:44Z

Summary

Add a guide explaining how to best work with Zip and Tar archives in .NET.

Internal previews

📄 File	🔗 Preview link
docs/fundamentals/toc.yml	docs/fundamentals/toc
docs/standard/io/zip-tar-best-practices.md	Best practices for working with ZIP and TAR archives in .NET

docs/standard/io/zip-tar-best-practices.md

docs/standard/io/snippets/zip-tar-best-practices/csharp/Program.cs

docs/standard/io/zip-tar-best-practices.md

rzikm

It's getting better, few additional comments.

rzikm · 2026-04-14T08:00:07Z

docs/standard/io/snippets/zip-tar-best-practices/csharp/Program.cs

+            continue;
+
+        // Normalize and validate the path, same as the ZIP example.
+        string destPath = Path.GetFullPath(Path.Join(fullDestDir, entry.Name));


Some samples use Path.Join, some Path.Combine, is there a meaningful difference between the two?

rzikm · 2026-04-14T08:01:47Z

docs/standard/io/snippets/zip-tar-best-practices/csharp/Program.cs

+            // Create the parent directory and any missing intermediate directories.
+            Directory.CreateDirectory(Path.GetDirectoryName(destPath)!);
+            using var fileStream = File.Create(destPath);
+            entry.DataStream.CopyTo(fileStream);


What about ExtractToFile (both for Tar and Zip), is it safe for them to use them after the validation above?

rzikm · 2026-04-14T08:06:03Z

docs/standard/io/snippets/zip-tar-best-practices/csharp/Program.cs

+void TarStreamingRead(Stream archiveStream)
+{
+    using var reader = new TarReader(archiveStream);
+    TarEntry? entry;
+    while ((entry = reader.GetNextEntry()) is not null)
+    {
+        if (entry.DataStream is not null)
+        {
+            string safePath = "output.bin";
+            // Copy now — the stream becomes invalid after the next GetNextEntry() call
+            using var fileStream = File.Create(safePath);
+            entry.DataStream.CopyTo(fileStream);
+        }
+    }
+}


I am not sure what this code snippet is supposed to illustrate

rzikm · 2026-04-14T08:07:10Z

docs/standard/io/zip-tar-best-practices.md

+### Convenience APIs (one-shot operations)
+
+- `ZipFile.CreateFromDirectory` / `ZipFile.ExtractToDirectory`—create or extract an entire archive in one call.
+- `TarFile.CreateFromDirectory` / `TarFile.ExtractToDirectory`—same for TAR.
+- Best for: simple workflows with trusted input, quick scripts, build tooling.
+
+### Streaming APIs (entry-by-entry control)
+
+- `ZipArchive`—open an archive, iterate entries, read or write selectively.
+- `TarReader` / `TarWriter`—sequential entry-by-entry access.
+- Best for: large archives, selective extraction, untrusted input, custom processing.
+
+If you control the archive source (your own build output, known-safe backups), the convenience APIs are the simplest choice. If the archive comes from an external source (user uploads, downloads, network transfers), use the streaming APIs with the safety checks described in this article.
+


this section is missing ExtractTo* helpers on ZipArchiveEntry or TarEntry

rzikm · 2026-04-14T08:10:02Z

docs/standard/io/zip-tar-best-practices.md

+
+### ZipArchiveMode.Update loads entries into memory
+
+Don't use `ZipArchiveMode.Update` for large or untrusted archives. When you open a `ZipArchive` in `Update` mode and call `Open()` or `OpenAsync()` on an entry, its uncompressed data is loaded into a `MemoryStream` to support in-place modifications. Accessing entry metadata (such as `FullName`, `Length`, or `ExternalAttributes`) does not trigger decompression. For large or malicious archives, opening entry content streams can cause `OutOfMemoryException`.


It would help to mention here that users should check Length before opening the entry

rzikm · 2026-04-14T08:10:55Z

docs/standard/io/zip-tar-best-practices.md

+
+Don't use `ZipArchiveMode.Update` for large or untrusted archives. When you open a `ZipArchive` in `Update` mode and call `Open()` or `OpenAsync()` on an entry, its uncompressed data is loaded into a `MemoryStream` to support in-place modifications. Accessing entry metadata (such as `FullName`, `Length`, or `ExternalAttributes`) does not trigger decompression. For large or malicious archives, opening entry content streams can cause `OutOfMemoryException`.
+
+Additionally, when you open a `ZipArchive` in `Read` mode with an **unseekable** stream (for example, a network stream), the runtime copies the entire stream into a `MemoryStream` up front to enable seeking through the central directory.


Suggested change

Additionally, when you open a `ZipArchive` in `Read` mode with an **unseekable** stream (for example, a network stream), the runtime copies the entire stream into a `MemoryStream` up front to enable seeking through the central directory.

Additionally, when you open a `ZipArchive` in `Read` mode with an **unseekable** stream (for example, a network stream), the runtime buffers the entire archive contents in memory to enable seeking through the central directory.

Also, this sentence is in ZipArchiveMode.Update loads entries into memory subsection, but talks about Read mode, so some restructuring is needed (maybe remove the subsection heading?)

rzikm · 2026-04-14T08:14:59Z

docs/standard/io/zip-tar-best-practices.md

+- **ZIP:** Unix permissions are stored in the upper 16 bits of `ExternalAttributes`. When extracting on Unix via `ExtractToDirectory` or `ExtractToFile`, the runtime restores ownership permissions (read/write/execute for user/group/other), subject to the process umask. SetUID, SetGID, and StickyBit are stripped. Permissions are not applied if the upper bits are zero. This happens when the ZIP was created on Windows, because the Windows runtime sets `DefaultFileExternalAttributes` to `0`. On Windows, these attributes are always ignored during extraction.
+- **TAR:** The `TarEntry.Mode` property represents `UnixFileMode` and can store all 12 permission bits (read/write/execute for user/group/other, plus SetUID, SetGID, and StickyBit). When extracting on Unix via `ExtractToDirectory` or `ExtractToFile`, the runtime applies only the 9 ownership bits (rwx for user/group/other), subject to the process umask. SetUID, SetGID, and StickyBit are stripped for security.
+
+When processing untrusted archives, validate `TarEntry.Mode` before extracting. An archive could set executable permissions on files that should not be executable.


The examples above don't touch/apply Mode at all, that is probably related to the lack of mention of ExtractToFile helpers in the earlier parts of the article.

An archive could set executable permissions on files that should not be executable.

That sentence is weird, the archive author clearly may have wanted some files to be executable, so who really decides that the files should not be executable?

I would reword it simply as a warning along the lines that untrusted archives may contain malicious executable files

rzikm · 2026-04-14T08:23:22Z

docs/standard/io/zip-tar-best-practices.md

+
+### File name sanitization differs by platform
+
+On Windows, when using `ExtractToDirectory`, the runtime replaces control characters and ``"*:<>?|`` with underscores in entry names. On Unix, only null characters are replaced. Archive entries with names like `file:name.txt` are renamed to `file_name.txt` on Windows but extracted as-is on Unix. The per-entry APIs (`Open()`, `ExtractToFile()`) do not perform any name sanitization.


The per-entry APIs (Open(), ExtractToFile()) do not perform any name sanitization.

Do you think that we should mention entry.ExtractToFile(entry.Name) is safe only if user properly validates Name/Mode/...?

rzikm · 2026-04-14T08:25:10Z

docs/standard/io/zip-tar-best-practices.md

+
+## Data integrity
+
+ZIP entries include a CRC-32 checksum that you can use to verify data hasn't been corrupted or tampered with.


I think you should also mention TAR CRC in the first paragraph, now users might assume that this section is Zip-only and skip the rest of it.

set up compression guide

9091e1d

dotnetrepoman bot added this to the April 2026 milestone Apr 10, 2026

alinpahontu2912 requested a review from rzikm April 10, 2026 10:36

dotnet-policy-service bot added the dotnet-fundamentals/svc label Apr 10, 2026

rzikm reviewed Apr 10, 2026

View reviewed changes

address comments

9de9456

rzikm reviewed Apr 14, 2026

View reviewed changes


		### ZipArchiveMode.Update loads entries into memory

		Don't use `ZipArchiveMode.Update` for large or untrusted archives. When you open a `ZipArchive` in `Update` mode and call `Open()` or `OpenAsync()` on an entry, its uncompressed data is loaded into a `MemoryStream` to support in-place modifications. Accessing entry metadata (such as `FullName`, `Length`, or `ExternalAttributes`) does not trigger decompression. For large or malicious archives, opening entry content streams can cause `OutOfMemoryException`.


		Don't use `ZipArchiveMode.Update` for large or untrusted archives. When you open a `ZipArchive` in `Update` mode and call `Open()` or `OpenAsync()` on an entry, its uncompressed data is loaded into a `MemoryStream` to support in-place modifications. Accessing entry metadata (such as `FullName`, `Length`, or `ExternalAttributes`) does not trigger decompression. For large or malicious archives, opening entry content streams can cause `OutOfMemoryException`.

		Additionally, when you open a `ZipArchive` in `Read` mode with an unseekable stream (for example, a network stream), the runtime copies the entire stream into a `MemoryStream` up front to enable seeking through the central directory.


		### File name sanitization differs by platform

		On Windows, when using `ExtractToDirectory`, the runtime replaces control characters and ``"*:<>?\|`` with underscores in entry names. On Unix, only null characters are replaced. Archive entries with names like `file:name.txt` are renamed to `file_name.txt` on Windows but extracted as-is on Unix. The per-entry APIs (`Open()`, `ExtractToFile()`) do not perform any name sanitization.


		## Data integrity

		ZIP entries include a CRC-32 checksum that you can use to verify data hasn't been corrupted or tampered with.

Conversation

alinpahontu2912 commented Apr 10, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Internal previews

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rzikm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alinpahontu2912 commented Apr 10, 2026 •

edited by github-actions bot

Loading