Getting started
editInstall the package
Add the Meziantou.Framework.Compression package to a project:
dotnet package add Meziantou.Framework.CompressionThe examples of this documentation omit the using directives: they need using Meziantou.Framework.Compression;.
Open an archive
ArchiveFile.Open detects the format of an archive from its content, so that the extension of the file does not matter. It returns an Archive: its Entries are known when the archive is opened, and can be read in any order. ArchiveFile.ExtractToDirectory extracts all of them:
// The format is detected from the content: zip, 7z, RAR, or tar compressed with gzip, bzip2, XZ, ...
using (var archive = ArchiveFile.Open(path))
{
foreach (var entry in archive.Entries)
{
if (entry.IsDirectory)
continue;
using var stream = entry.Open();
using var reader = new StreamReader(stream);
var text = reader.ReadToEnd();
Assert.NotNull(text);
}
var hello = archive.GetEntry("hello.txt");
Assert.Equal(16, hello?.Length);
}
ArchiveFile.ExtractToDirectory(path, destination);- The other volumes of a multi-volume archive are found next to the first one. Open a stream with ArchiveReaderOptions.VolumeResolver to give them yourself.
- A compressed tar archive is decompressed to a temporary file, which is deleted when the archive is disposed.
- ArchiveFile.DetectFormat tells the format of a file without opening it, as an ArchiveFormatInfo: the ArchiveFormat and the CompressionFormat around it.
Every entry is an ArchiveEntry, with its name, its length, its times, its attributes and the target of a link. The stream that Open returns checks the CRC or the hash of the content, and throws an InvalidDataException at its end when they do not match.
Read an archive from a stream that is not seekable
ArchiveReader.Create reads the entries one after the other, from a stream that does not need to be seekable, such as the response of an HTTP request. It supports zip, RAR, tar and the compressed tar archives; a 7z archive needs to be seekable, so it throws a NotSupportedException:
// The stream does not need to be seekable: a network response, a pipe, ...
using var input = File.OpenRead(path);
using var archiveReader = ArchiveReader.Create(input);
Assert.Equal(ArchiveFormat.Tar, archiveReader.Format);
Assert.Equal(CompressionFormat.GZip, archiveReader.CompressionFormat);
while (archiveReader.MoveToNextEntry())
{
var entry = archiveReader.Entry!;
if (entry.FullName.EndsWith(".txt", StringComparison.Ordinal))
{
// The content can be read until the reader moves to the next entry
using var content = archiveReader.OpenEntryStream();
using var copy = new MemoryStream();
content.CopyTo(copy);
Assert.Equal(entry.Length, copy.Length);
}
}The content of an entry can be read until the reader moves to the next entry, and the content that is not read is skipped. In a zip archive read forward only, the length and the CRC of an entry written with a data descriptor are known only once its content is read: until then, Length is -1.
Errors
InvalidDataException: the data are not an archive of a supported format, or they are corrupted.- ArchivePasswordException: the archive is encrypted, and ArchiveReaderOptions.Password is missing or wrong.
NotSupportedException: the archive uses a method that the library does not support (RAR 1.5, the PKWARE strong encryption of zip, ...).