[API Proposal]: Provide a NormalizeEntrySeparator(Char, Char) method for ZipFileExtension.

[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.

API Proposal

namespace System.IO.Compression;

public partial class ZipFileExtensions
{
    public static ZipArchive NormalizeEntrySeparator(this ZipArchive archive);
    public static ZipArchive NormalizeEntrySeparator(this ZipArchive archive, char newSeparator);
    public static ZipArchive NormalizeEntrySeparator(this ZipArchive archive, char originalSeparator, char newSeparator);
}

API Usage

using (var archive = ZipFile.Open(zipPath, ZipArchiveMode.Create))
{
    // Do something with archive
    archive.NormalizeEntrySeparators(); // Replace Path.DirectorySeparatorChar in the entry path with '/'.
    char separatorChar = '/';
    archive.NormalizeEntrySeparators(separatorChar); // Replace Path.DirectorySeparatorChar in the entry path with the separatorChar.
    char originSeparatorChar = '\';
    archive.NormalizeEntrySeparators(originSeparatorChar, separatorChar); // Replace the originSeparatorChar in the entry path with the separatorChar.
}

Alternative Designs

Perhaps we could also provide an Option when calling ZipFile.Open that allows users to specify their own separator, or offer an overload for functions like CreateEntry or CreateEntryFromFile that includes a separatorChar parameter. However, this might make things more complicated.

Risks

No response

[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.