[API Proposal]: Introduce PathNormalizationOption in ZipFile.Open for Cross-Platform Zip Entry Path Compatibility

[XmmShp]

Background and motivation

For zip files, ZipFile allows the creation of archives with '\' as the filename separator. However, in practice, entry paths are usually provided using a method similar to the following:

var zipEntryPath = Path.GetRelativePath(folderPath, filePath);

On Windows platforms, this results in paths separated by '\'. When the resulting .zip archive is moved to a Unix platform and extracted using ZipFile, issues arise, as mentioned in issue #98247 .

I believe it would be beneficial to provide an API to normalize the path separators in the entries of the archive to ensure compatibility across different operating systems.

---

Currently, when developers use ZipFile to create compressed files, inconsistencies in path separators across different operating systems can lead to issues. Specifically, .zip files created on Windows may use backslashes (\) as path separators, while Unix-based systems expect forward slashes (/). This discrepancy can cause errors when moving and extracting .zip files across platforms.

Although this issue can be resolved by manually replacing string separators, it is far from ideal. Ideally, there should be a direct and straightforward way to ensure consistent path separators, improving both user experience and code maintainability.

API Proposal

namespace System.IO.Compression;

public enum PathNormalizationOption
{
    None = 0, // No normalization of path separators.
    NormalizeToForwardSlash = 1, // Converts all directory separators to '/'.
}

public class ZipFile
{
    public static ZipArchive Open(string path, ZipArchiveMode mode, PathNormalizationOption option = PathNormalizationOption.None);
}

API Usage

using (var archive = ZipFile.Open(zipPath, ZipArchiveMode.Create, PathNormalizationOption.NormalizeToForwardSlash))
{
    // Do something with archive
}

With this approach, developers can easily choose whether to normalize path separators without manually performing string replacement operations.

Alternative Designs

Another possible design would be to add a boolean parameter to methods like CreateEntryFromFile to specify whether path separators should be normalized. However, this approach is less intuitive and centralized compared to setting the option directly when opening the archive.

Risks

The risk associated with this change is minimal, as it only involves adding a new enumeration type and an additional parameter to an existing method. Moreover, it does not affect existing behavior by default unless the path normalization option is explicitly specified.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-io-compression
See info in area-owners.md if you want to be subscribed.

[ericstj]

@XmmShp -- have you tried doing this with existing APIs? This seems like a pretty special purpose API, we don't even have it on Path but similar problems exist there when folks are dealing with path strings that might need to work cross-platform. cc @dotnet/area-system-io.

If you can't do it today with existing APIs, then maybe you might want to consider making a more generalized API proposal like ZipArchiveEntry.Rename or similar?

[XmmShp]

@XmmShp -- have you tried doing this with existing APIs?

@ericstj I solved it locally with a simple string.Replace(Path.DirectorySeparatorChar, '/') method, but I believe a more directive solution should be provided for this issue. It might even be considered to set this as an Option for Open, because I think this problem could trouble many people using dotnet to manipulate Zip files across platforms.

[dovisutu]

It's not quite intuitive that callers are responsible for ensuring that forward slashes should be used as directory separators (dotnet documentations apparently did't mention it, and there are several instances of reporting it in this repo), so at least something needs to be done.

Technically noting the separator issue in the documentation is already ok, but I would still prefer to have this normalization (optionally, of course, as backslashes are valid in zip entries) in methods like CreateFromFile, where it's common to set the entry path to some sort of file-system-based relative path with potentially wrong separators, and having to replace it ourselves is somewhat awkward. So basically adding a bool argument that (well, it has to) defaults to false.

A generalized NormalizePath method as proposed seems too overkill, though, unless normalizing paths turns out to be more common - and then we wouldn't put it in ZipArchive.

[XmmShp]

Thank you all for your attention and discussion on the previous proposal. After further consideration, I believe introducing an option (e.g., PathNormalizationOption) in the ZipFile.Open method to handle path separator normalization could be a more integrated and user-friendly solution. This approach not only simplifies the developer's workflow but also enhances cross-platform compatibility when working with .zip files.